Route-mode trust and safety

Understand what Archal changes, what it routes, and what can fail in route mode.

Route mode reroutes supported service traffic from a local app to hosted twins. Enabled by default for local harness runs; pass --no-proxy to opt out when your harness already wires twin URLs through env vars.

Read this before attaching a real app — it’s the trust boundary.

“Route mode” and “proxy mode” are the same thing. The flag is --proxy / --no-proxy; the docs use “route mode” for the concept.

What Archal changes

In local route mode, Archal starts a local proxy and injects proxy and CA env vars into the target process.

That includes:

• HTTP_PROXY and HTTPS_PROXY
• NODE_EXTRA_CA_CERTS
• SSL_CERT_FILE
• REQUESTS_CA_BUNDLE
• CURL_CA_BUNDLE

In Docker sandbox mode, the same short-lived CA is installed inside the sandbox container only. That container is the thing that is torn down after the run.

SDK runtime compatibility

Interception only works if your HTTP client respects the env vars above.

Runtime / client	Works	Notes
Node.js (https, fetch, undici, axios, node-fetch, googleapis, @octokit/*, @slack/*)	Yes
Python requests / httpx	Yes
curl	Yes
Python urllib	Partial	Point SSL_CERT_FILE at the CA explicitly.
Go (net/http)	Partial	Add /archal-out/ca.crt (Docker) or temp CA (local) to trust store.
JVM (HttpClient, OkHttp)	Partial	Needs -Dhttps.proxyHost/Port and an explicit trust store.
Browser fetch	No	Use the twin’s REST base URL directly.

For “Partial” or “No” rows, disable the proxy with --no-proxy and wire ARCHAL_<TWIN>_BASE_URL directly.

What gets rerouted

Only service domains registered for the selected twins are rerouted. Non-twinned traffic keeps using the normal network path.

Examples:

• GitHub twins reroute GitHub API and web domains
• Google Workspace twins reroute the supported Google API domains for that twin
• unsupported services and transports are not intercepted

In local mode, some runtimes also need host entries for full interception. Archal prints the required /etc/hosts lines when that is necessary.

What Archal can see

If a request is routed to a twin, Archal can see the request metadata needed to forward it to the hosted twin. Depending on the flow and trace settings, that can include headers and request bodies for supported twin traffic.

That is why route mode should be treated as explicit test infrastructure, not a hidden background transport change.

Cleanup behavior

Local route mode generates a fresh CA in a temp directory for the run and removes it on teardown.

That means:

• no host keychain cleanup step is required in the default local path
• the temp CA files do not persist after normal teardown
• stopping the run or proxy is the normal way to clean up

Hosted twin sessions are separate from local cleanup. Stop them with archal twin stop when you are done.

Troubleshooting: the proxy is running but my SDK isn’t intercepted

If the TLS proxy listening on :NNNN line prints but your agent’s calls are still hitting the real service, usually one of these is the cause:

• The SDK bypasses env vars. A custom fetch implementation or TLS client may ignore HTTPS_PROXY or NODE_EXTRA_CA_CERTS. Check the runtime compatibility table above — if your runtime is “Partial” or “No,” disable the proxy with --no-proxy and wire twin base URLs directly.
• A subprocess strips the env. If your harness spawns sub-processes that clear process.env or re-execute under a different shell, the proxy env will not survive the hop. Forward the relevant env vars explicitly.
• TLS is being pinned. Services with embedded certificate pinning (rare in the SaaS SDKs Archal supports, but occasionally seen in enterprise SDK wrappers) will reject the temp CA. Patch the SDK to respect a custom trust store, or use an adapter pattern to skip the SDK’s HTTP client.
• The twin does not cover that domain yet. Archal only intercepts domains registered for selected twins. Calls to unsupported services pass through unchanged — check the twin’s docs page for the routed-domains list.

If none of these explain the behavior, pass -v to archal run; the proxy logs every intercepted hostname under debug.