SOS Relay SOS Relay home

English source · Local-first networking notes

English source Markdown ↓

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 and doors.md 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

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:

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:

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.

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.

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.

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.

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.

How agents should select a provider

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.
  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.

# 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:

# 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

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:

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.

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:

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