Local proxy routing is low-fidelity debug behavior. It is not used for scored service simulation.
What Archal changes
In controlled route mode, Archal maps real service domains to a TLS intercept listener and installs or exposes a short-lived CA. Agent-visible service routing does not include:HTTP_PROXYandHTTPS_PROXY- Archal-owned clone URLs
- Archal REST routing config
SDK runtime compatibility
Interception only works if your HTTP client uses normal DNS and trusts the runtime CA.| 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 /agent-output/ca.crt (Docker) or temp CA (local) to trust store. |
JVM (HttpClient, OkHttp) | Partial | Needs an explicit trust store containing the Archal CA. |
Browser fetch | No | Use a server-side harness entrypoint instead of browser-network execution. |
What gets rerouted
Only service domains registered for the selected clones are rerouted. Non-clone traffic keeps using the normal network path. Current route-mode clone set:| Clone | Primary routed surface |
|---|---|
| GitHub | GitHub API and web domains |
| Discord | Discord REST API domains |
| Slack | Slack API domains |
| Stripe | Stripe API domain |
| Jira | Atlassian/Jira API domains |
| Linear | Linear API domain |
| Supabase | Supabase API domains |
| Google Workspace | Supported Gmail, Calendar, Drive, Sheets, People, and OAuth domains |
| Ramp | Primary Ramp API domain |
What Archal can see
If a request is routed to a clone, Archal can see the request metadata needed to forward it to the hosted clone. Depending on the flow and trace settings, that can include headers and request bodies for supported clone traffic. That is why route mode should be treated as explicit test infrastructure, not a hidden background transport change.Cleanup behavior
Controlled route mode generates a fresh CA 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 is the normal way to clean up
archal clone stop when you are done.
Troubleshooting: TLS interception is running but my SDK isn’t intercepted
If TLS interception starts but your agent’s calls are still hitting the real service, usually one of these is the cause:- The runtime does not trust the CA. A custom
fetchimplementation or TLS client may ignore the system trust store andNODE_EXTRA_CA_CERTS. Check the runtime compatibility table above and configure the client to trust the Archal CA. - The runtime is not controlled. High-fidelity service routing requires Docker or sandbox mode so Archal can control DNS and TLS trust. Local uncontainerized runs are debug-only.
- 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 clone does not cover that domain yet. Archal only intercepts domains registered for selected clones. Calls to unsupported services pass through unchanged - check the clone’s docs page for the routed-domains list.
-v to archal run; Archal logs every intercepted hostname under debug.