> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Route-mode trust and safety

> Understand the trust boundary in Archal route mode: which service domains it intercepts, how TLS trust is installed, and why scored runs use Docker.

Route mode reroutes supported service traffic from a controlled runtime to hosted clones. High-fidelity service simulation requires Docker or sandbox mode so Archal can control DNS and TLS trust.

Read this before autolooping a real app - it's the trust boundary.

> 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_PROXY` and `HTTPS_PROXY`
* Archal-owned clone URLs
* Archal REST routing config

The short-lived CA is installed inside the sandbox container or exposed through CA trust env vars for runtimes that need them. That container is torn down after the run.

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

For "Partial" rows, patch the runtime to trust the Archal CA without changing service URLs. For "No" rows, move the service call behind a server-side harness entrypoint.

## 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 changes with the hosted catalog. Confirm the live
set with `archal clone --json`; the table below is the high-level surface, not
a domain allowlist:

| Clone            | Primary routed surface                                              |
| ---------------- | ------------------------------------------------------------------- |
| Apify            | Apify REST API domain                                               |
| GitHub           | GitHub API and upload 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                                             |
| Tavily           | Tavily API domain                                                   |

Unsupported services and transports are not intercepted.

Explicit low-fidelity local debug mode may require host entries or proxy settings. Scored service simulation does not use that path.

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

Hosted clone sessions are separate from local cleanup. Stop them with `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 `fetch` implementation or TLS client may ignore the system trust store and `NODE_EXTRA_CA_CERTS`. Check the [runtime compatibility table](#sdk-runtime-compatibility) 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.

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