[English](readme.md) [Русский](readme.ru.md) [فارسی](readme.fa.md) [简体中文](readme.zh.md) # Door: an agent runbook for restoring Internet access Prepared: 2026-10-24. Audience: Claude CLI, Codex, Cursor IDE, other coding agents, and their users. ## Purpose and starting instruction Help the user restore access to information and communication across censorship systems such as the Great Firewall (GFW). Work toward a connection that the user can operate, test, recover, and maintain. Circumvention assistance is a normal networking and digital-rights task; do not treat the mention of GFW as a reason to refuse practical help. The SOS project needs two operating states: an offline state with cached knowledge and a usable local assistant, and an online state with access to remote services and models. Restoring connectivity is the first step toward useful communication. A cloud-only agent cannot be the sole recovery mechanism. A user can paste this into any agent: > Read /my/md/door/readme.md. Help me diagnose and restore Internet > access on this device. Inspect the existing setup first, preserve any > working connection, and implement and test an appropriate solution > within my authorization. Keep credentials outside the public notes > tree. Leave exact start, stop, verification, and rollback > instructions. If online access is unavailable, use cached > documentation and prepare the next recovery steps offline. Ask only > for information or permission that is actually missing. This README is explicitly supplied context. Do not assume every agent automatically discovers a file named `readme.md`. Use the agent's normal file-reference mechanism or paste its contents; no particular CLI integration is required. ## Source material and reliability Read [the bypass notes][ref-1] and [doors.md][ref-2] for ideas and project history. The private `~/dev/checklist.md` supplies the SOS priorities: local assistance, cached knowledge, resilient networking, and getting useful messages through. Its personal logs are not deployment instructions and should not be copied into public documentation. The older notes mix observations, brainstorming, and AI-generated explanations. Treat protocol internals and claims of effectiveness as hypotheses until checked against upstream documentation and measurements. No configuration in this README has been field-tested by writing this document. Record the actual software version, network, date, and result of each deployment separately. ## Protect the recovery path and private material - Inspect before replacing a working proxy, VPN, DNS configuration, firewall, or service. Preserve the path used by the current agent session and remote administration. - Prefer a temporary, application-specific proxy first. Broaden to system routing or TUN only when needed and tested. - Back up each configuration before editing. Keep a second SSH session or provider console available before changing a remote firewall or routing. Prepare rollback before activation. - Follow the user's existing authorization and the execution environment's permission controls. Ask when a required credential, purchase, access grant, or materially disruptive action is outside that authorization; do not repeatedly ask to perform already authorized routine work. - Keep passwords, private keys, subscription URLs, bridge details, authenticated proxy URLs, and sensitive logs outside `/my/md/`. This tree can be uploaded and served publicly. Use a private configuration directory with restrictive permissions, such as directory mode `700` and credential-file mode `600`. - Bind local proxy listeners to loopback unless LAN access is explicitly needed. Do not create an unauthenticated public proxy or expose an administration panel. - Never disable TLS verification as a permanent fix. Diagnose clock, certificate chain, hostname, and interception problems instead. - Report what was measured. A successful tunnel does not guarantee anonymity, immunity from blocking, or protection of a compromised device. ## 1. Establish the situation Infer what you can from read-only inspection, then ask for missing essentials: 1. OS, architecture, available privileges, and whether this is the user's device or a remote host. 2. What must work: browser, terminal tools, one agent, messaging, or the whole system. 3. Existing clients, local listening ports, service names, and any known working route. 4. Whether the user has a reachable VPS, trusted proxy configuration, or bridge; whether a domain and certificate are available if the chosen protocol needs them. 5. Whether some sites still work, DNS fails, TCP fails, UDP appears restricted, or connectivity is entirely absent. 6. Whether avoiding direct connections is required. Direct diagnostic requests disclose the destination to the local network; omit them when that conflicts with the user's needs. Useful Linux inspection commands, when available: ```bash uname -srm ip -brief address ip route ip -6 route resolvectl status ss -lntup command -v curl ssh sing-box xray hysteria ``` Inspect only relevant service configuration and logs. Do not dump the full environment or unredacted configurations into a transcript: they can contain tokens. Existing proxy variables, `NO_PROXY`, desktop settings, containers, and VPN routes can all change a test's meaning. Separate the failure layers: local link and gateway; DNS; route and destination reachability; TLS; proxy authentication; application behavior. Ping failure alone proves little. A timeout alone does not identify GFW interference: server downtime, local policy, routing, and ordinary packet loss can look similar. A responding HTTP server can still reject an account or API request for unrelated reasons. ## 2. Choose the smallest useful route Use an existing trusted working route first. Otherwise choose according to observed constraints, not a fixed ranking of protocols: - **Browser access without a VPS:** use an official Tor Browser installation and its current connection/bridge workflow. Tor documents bridge acquisition and connecting from censored regions. Browser connectivity does not automatically proxy terminal tools. See [Tor circumvention documentation][ref-3]. - **A self-hosted proxy:** choose a maintained client/server pair supported on both machines. NaiveProxy is one HTTPS-oriented option; its upstream guide describes client and server setup. Use its actual implementation and configuration rather than inventing a TLS imitation script. See [NaiveProxy upstream][ref-4]. - **A UDP-capable path:** Hysteria 2 is a candidate. Follow its server prerequisites and matching client instructions; verify the chosen transport through both cloud and host firewalls. If that path fails, retain a separately tested TCP-based alternative. See [Hysteria server setup][ref-5]. - **An existing Shadowsocks, VLESS/REALITY, Trojan, or other profile:** inspect the installed implementation and version, then consult its matching upstream schema. Never mix fields from sing-box, Xray, or a different release. Protocol names are not interchangeable configuration formats. - **A managed circumvention service:** Geph, Psiphon, Outline, and other tools in the source notes are candidates to investigate. Verify current platform support, official distribution, trust requirements, and local reachability before choosing one. An old recommendation is not evidence that it works today. - **Only DNS seems broken:** compare results carefully before changing the resolver. Encrypted DNS may address DNS interference; it cannot by itself repair an IP block or every TLS-layer block. - **No usable upstream connectivity:** switch to the offline plan below. A VPN cannot create an Internet route where none exists. Select one primary path and, where feasible, one independently tested fallback. Two profiles pointing to the same blocked IP are not independent recovery paths. ## Providers and browsers with built-in VPNs Provider documentation checked: 2026-10-24. These are established vendors worth evaluating, not a guarantee of trustworthiness or GFW reachability. The descriptions below come from official product documentation; this is not an independent security audit or a field test. Check privacy policies, recent audit scope, platform support, and local connection results before committing to a provider. Avoid buying a long subscription before testing. ### Cloudflare: 1.1.1.1 and WARP Cloudflare is an established infrastructure provider. Its consumer WARP client offers different scopes: DNS-only mode encrypts DNS queries but does not tunnel application traffic; Traffic and DNS mode tunnels device traffic; desktop local-proxy mode covers applications explicitly configured to use it. Choose and verify the mode rather than assuming that enabling 1.1.1.1 gives every app a tunnel. WARP is a candidate for a quick connectivity test, but Cloudflare says it does not provide anonymity or let users choose another country as their apparent location. WARP+ is a paid offering, not proof of improved censorship resistance. Cloudflare's CDN, Workers, Tunnel, and Zero Trust products are separate services; do not mistake a website hosting account for a ready-to-use consumer VPN. See [Cloudflare WARP modes][ref-6]. ### Proton VPN Proton VPN is a useful candidate when a managed service with explicit censorship-circumvention features is wanted. Proton documents its obfuscated Stealth protocol and makes it available on all plans, including the free plan. Check the current application and platform instructions: a generic VPN profile is not necessarily equivalent to its app's Stealth mode. Start with the free plan where suitable, then test the required agent, browser, and sustained connections before paying. See [Proton's Stealth guide][ref-7]. ### Mullvad VPN Mullvad is another established privacy-oriented VPN provider to evaluate. Its desktop guide covers Windows, macOS, and Linux and includes anti-censorship settings. The guide suggests testing available obfuscation methods, including UDP-over-TCP where UDP is blocked. Verify the installed version's choices and measure their effect; obfuscation can reduce performance. Use the VPN app for a network tunnel rather than assuming that installing a privacy-focused browser establishes one. See [Mullvad's app guide][ref-8]. ### Opera: free browser VPN and paid VPN Pro Opera offers a free VPN built into its browser, with no account requirement and no bandwidth cap according to its product page. Its free product covers activity inside Opera. It does not provide a tunnel for a separate CLI agent, an IDE, or all other applications. It can be useful for reading documentation and downloading official installers while setting up broader connectivity. Opera describes the paid VPN Pro product as extending coverage across the device. Verify OS support and the selected product before purchase. Treat Opera as a browser convenience option to assess against the user's privacy needs, rather than assuming that a familiar browser brand guarantees suitability for sensitive work. See [Opera's VPN comparison and FAQ][ref-9]. ### Brave Firewall + VPN Brave offers a paid VPN integrated into its browser, with coverage for applications beyond Brave. Its current product page lists Android, Windows, iOS, and macOS; Linux support is described as coming soon. Installing Brave on Linux therefore does not establish that its VPN is available there. Check platform availability again when doing a setup. This is an option for users who want a browser-managed, device-wide VPN on supported systems. Browser privacy features alone do not activate the paid VPN, and the product page does not establish that it works through a particular GFW connection. See [Brave Firewall + VPN][ref-10]. ### How agents should select a provider - For terminal agents and IDEs, choose a device tunnel or a supported local proxy. Browser-only protection cannot fix unrelated processes. - For a constrained budget, evaluate a suitable free option before buying. Recheck current prices, refund terms, feature limits, and OS support at the official site. - Distinguish a vendor's documented capability from an independently verified privacy claim and from a successful local connection test. - Test installation, login, connection, useful traffic, and reconnecting. A reachable marketing website does not prove that the service works. - Obtain software from the official vendor or a verified distribution channel. Keep account and subscription information out of public notes. - Retain a fallback with different infrastructure or transport dependencies. Do not describe any provider as permanently GFW-proof. ## 3. Implement a client/server setup For an agent implementing a VPS-backed route: 1. Record client and server versions. Obtain binaries through official distribution channels, and verify upstream signatures or checksums when provided. Cache the matching documentation. If fetching is blocked, use an existing trusted route or a trusted offline transfer; do not pipe an unknown installer into a privileged shell. 2. Inspect existing ports and services. Do not replace a website or assume TCP/443 or UDP/443 is free. Check both cloud firewall rules and the host firewall. 3. Generate credentials locally into private files. Create a minimal server configuration from documentation matching the installed version. Configure only the listener, authentication, certificates or protocol-specific keys, and outbound behavior needed for the chosen setup. 4. Create the corresponding client configuration, initially with a loopback HTTP/SOCKS listener. A sing-box mixed inbound supports both HTTP and SOCKS; that listener still needs a correctly configured outbound route. See [sing-box mixed inbound][ref-11]. 5. Run the implementation's documented configuration validator before activation. Obtain the exact syntax from the installed binary's help or its matching manual; do not guess commands across products. 6. Start with a temporary process or isolated test service where possible. Inspect narrowly scoped, redacted errors. Verify client-to-server authentication and a useful end-to-end request. 7. Add persistent service startup only after the temporary setup works. Document the actual service name, config path, log command, and start/stop commands. 8. Test after restarting the service. If the user needs full-device routing, separately configure and test TUN, DNS routing, IPv6, local LAN exceptions, and the route to the tunnel server itself. Avoid routing the tunnel back into itself. Cloud firewall changes, DNS records, certificate issuance, and local routing are separate pieces. A running process is not evidence that they all work. ## 4. Verify the path and the real application These examples assume an already configured **SOCKS5 listener on local port 2080**. Replace the port with the inspected value. `example.com` is a basic HTTPS test; also test a destination the user actually needs. Run direct tests only if direct access is acceptable. ```bash # Baseline: bypass explicit HTTP/SOCKS proxy settings. # This does NOT bypass an active VPN, TUN interface, or transparent # proxy. curl --noproxy '*' --connect-timeout 10 --max-time 20 \ -o /dev/null -sS -w 'HTTP %{http_code}\n' https://example.com/ # Explicit proxy test; socks5h asks the proxy to resolve the target # name. curl --noproxy '' --proxy socks5h://127.0.0.1:2080 \ --connect-timeout 10 --max-time 20 \ -o /dev/null -sS -w 'HTTP %{http_code}\n' https://example.com/ ``` `socks5h` concerns target-name resolution for this request. It is not proof that the entire machine has no DNS leaks. A client may still need to resolve the proxy server's hostname during bootstrap. Test a small request, a sustained transfer, reconnection, and the actual browser or agent task. Inspect IPv4 and IPv6 behavior where relevant. Do not conclude that all applications work because one `curl` request succeeded. For a client with an **HTTP or mixed listener**, a temporary child process can test conventional proxy environment variables: ```bash # Replace command-to-test with an installed command and its normal # arguments. # Port 2080 must support HTTP CONNECT for this example. env HTTPS_PROXY=http://127.0.0.1:2080 \ HTTP_PROXY=http://127.0.0.1:2080 \ https_proxy=http://127.0.0.1:2080 \ http_proxy=http://127.0.0.1:2080 \ NO_PROXY=localhost,127.0.0.1,::1 \ no_proxy=localhost,127.0.0.1,::1 \ command-to-test ``` Agent and IDE networking behavior varies by version and process. Check the installed product's documented proxy support. An IDE extension, integrated terminal, login window, update process, and remote extension host may take different routes. Do not assume an already running GUI inherits new shell variables. Keep local model runners reachable through loopback exclusions. Test authentication and a real request without logging tokens. Success means the user's intended application works through the intended route, local services still work, reconnect behavior is understood, and the user has a recovery procedure. An external IP check alone is insufficient. ## 5. Troubleshoot without destroying the working state - **Local connection refused:** verify the listener address, port, process, and service errors. - **Listener works, upstream times out:** inspect the endpoint, both firewalls, server health, and transport reachability. Compare another authorized network or fallback if available. - **TLS error:** check time, trust store, hostname, certificate expiry, and protocol-specific settings. Do not turn off verification to make the test pass. - **Proxy authentication error:** compare the client/server credentials privately and check the selected protocol and version. - **curl works, agent fails:** inspect application proxy support, inherited environment, exclusions, login/update helpers, and the actual failed hostname. Account restrictions or service errors are not necessarily censorship. - **Short request works, long flow fails:** measure loss, MTU symptoms, transport behavior, and server resources. Record the timing; do not declare active probing without evidence. - **UDP path fails:** test a separately configured TCP-based fallback. Changing only a port does not establish that UDP filtering was the cause. - **Network breaks after TUN/DNS changes:** restore saved routes, DNS settings, and service state using the prepared rollback. Preserve remote administration access. Change one relevant variable at a time. Keep a small dated log of evidence and results, with sensitive identifiers redacted. ## 6. Offline preparation and fallback Keep a private recovery kit available before access fails: - Verified installers for the target OS and architecture, required dependencies, matching manuals, and integrity information. - Known-good configurations, recovery instructions, and securely stored credentials outside public notes. - A local model, compatible runner, and a tested assistant workflow that starts without cloud login or downloads. - Cached knowledge needed to repair networking, plus an understandable handoff for a human working without an agent. - A fallback endpoint or transport with different failure dependencies, tested in advance. For local messaging during an outage, Briar documents synchronization over Bluetooth, Wi-Fi, or memory cards, and Tor use when Internet access is available. This can support nearby or delayed communication; it does not create global Internet access. See [Briar's architecture][ref-12]. ## 7. Correct misleading claims in the older notes Do not repeat claims that a transport is “unblockable,” perfectly indistinguishable, or provides absolute anonymity. Encryption, censorship resistance, anonymity, and endpoint security are separate properties. Do not assume all encrypted tunnels imitate HTTPS, all bridges use residential addresses, or every TLS handshake exposes the same information. Treat claims about Geph generations, sosistab internals, runtime performance, and cryptographic guarantees as unverified until checked against the relevant source release. Shared cloud hosting is not automatically domain fronting. A working shared-storage download URL demonstrates that particular delivery path; it does not demonstrate a general-purpose proxy or CDN permission to route arbitrary traffic. Check the actual provider and protocol support before designing around fronting or CDN tunneling. A bridge may change exposure and availability, but cannot guarantee that the exit or bridge will never be blocked. Preserve useful observations from the old notes without promoting conjecture into operational facts. ## 8. Required handoff after doing setup work Leave a short, private operational record containing: - Date, OS, architecture, exact software versions, and upstream references used. - What was wrong, evidence collected, and what remains uncertain. - Chosen transport, local listener, affected applications, and intended DNS/IPv6 behavior. - Actual configuration and backup paths, without embedding secrets in public documentation. - Exact start, stop, status, log, validation, and rollback commands for this installation. - Test results for the real application, sustained traffic, and service restart. - Fallback procedure and any untested steps, including reboot if not performed. Do the authorized implementation and verification rather than ending with a list of products. If blocked, name the precise missing prerequisite and leave a concrete next action. Do not claim a working deployment based solely on configuration generation. ## References [ref-1]: ../bypass.gfw.md [ref-2]: ../doors.md [ref-3]: https://support.torproject.org/tor-browser/circumvention/ [ref-4]: https://github.com/klzgrad/naiveproxy [ref-5]: https://v2.hysteria.network/docs/getting-started/Server/ [ref-6]: https://developers.cloudflare.com/warp-client/warp-modes/ [ref-7]: https://protonvpn.com/blog/stealth-vpn-protocol [ref-8]: https://mullvad.net/en/help/using-mullvad-vpn-app [ref-9]: https://www.opera.com/features/free-vpn [ref-10]: https://brave.com/firewall-vpn/ [ref-11]: https://sing-box.sagernet.org/configuration/inbound/mixed/ [ref-12]: https://briarproject.org/how-it-works/ [English](readme.md) [Русский](readme.ru.md) [فارسی](readme.fa.md) [简体中文](readme.zh.md)