Sandbox mode runs your agent inside a Docker container where a TLS-intercepting proxy transparently reroutes HTTPS calls to cloud-hosted digital twins. The agent thinks it’s talking to real services (GitHub, Slack, Stripe, etc.) — it uses real CLI tools, real credentials format, real domains — but every request hits a twin instead.
Requirements
| Mode | Requires |
|---|
| Docker (default) | Docker Engine running locally |
Local (--no-docker) | OpenClaw CLI installed and in PATH |
ARCHAL_TOKEN or ~/.archal/credentials.json).
Quick start
archal openclaw run scenarios/security-suite/exec-impersonation.md
archal run scenarios/github/close-stale-issues.md \
--sandbox \
--openclaw-home ~/.openclaw
archal run scenarios/github/close-stale-issues.md \
--sandbox \
--no-docker
How it works
Docker mode (default)
- Archal provisions cloud twin sessions and gets URLs (e.g.
https://sess.twins.archal.ai/github/api)
- A Docker container starts with the
archal/sandbox image
- Inside the container, the entrypoint:
- Generates a short-lived CA certificate and installs it in the system trust store
- Writes
/etc/hosts entries mapping service domains to 127.0.0.1 (e.g. 127.0.0.1 api.github.com)
- Starts a TLS proxy on
:443 that uses SNI to present valid per-domain certs
- Injects fake service credentials into the environment (
STRIPE_API_KEY, SLACK_TOKEN, etc.)
- Configures the
gh CLI with a dummy OAuth token
- Starts the OpenClaw gateway and sends the scenario task to the agent
When the agent makes an HTTPS request to api.github.com, DNS resolves to 127.0.0.1, the proxy terminates TLS with a CA-signed cert, strips the agent’s fake credentials, injects the real ARCHAL_TOKEN, and forwards the request to the cloud twin. The agent never knows the difference.
Non-twinned traffic (e.g. LLM API calls to api.anthropic.com) passes through to the real internet.
Local mode (--no-docker)
Starts the proxy on the host and spawns OpenClaw directly. The agent process gets HTTPS_PROXY and CA cert env vars (NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE) so HTTP clients route through the proxy.
Local mode requires you to add /etc/hosts entries manually for full interception. The CLI prints the needed entries at startup.
Supported services
The proxy intercepts these domains and routes them to twin endpoints:
| Twin | Intercepted domains |
|---|
| GitHub | api.github.com, github.com |
| Slack | slack.com, api.slack.com, *.slack.com |
| Jira | atlassian.net, *.atlassian.net, api.atlassian.com, jira.atlassian.com |
| Stripe | api.stripe.com |
| Linear | api.linear.app |
| Supabase | supabase.co, *.supabase.co, api.supabase.com |
acme.atlassian.net) are discovered from the mounted OpenClaw config and added to /etc/hosts automatically.
What gets mounted
Full home mount (default)
When you pass --openclaw-home (or let it default to ~/.openclaw), the entire OpenClaw home is copied into the container read-only. This preserves the agent’s personality, memory, skills, plugins, and auth profiles.
archal run scenario.md --sandbox --openclaw-home ~/.openclaw
Workspace-only mount
When you pass --workspace instead, only the workspace directory is mounted. A minimal OpenClaw config is generated inside the container.
archal run scenario.md --sandbox --workspace ./my-project
archal run scenario.md --sandbox \
--workspace ./my-project \
--openclaw-config ./openclaw.json
ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_API_KEY as environment variables.
GraphQL bridge
The gh CLI uses GraphQL for many commands (gh issue list, gh repo view, etc.). Since cloud twins expose REST endpoints, the proxy includes a GraphQL-to-REST bridge that translates common GraphQL queries into REST calls against the GitHub twin. This means gh commands work inside the sandbox without modification.
Flags reference
| Flag | Description | Default |
|---|
--sandbox | Enable sandbox mode | off |
--no-docker | Skip Docker, use local OpenClaw + proxy | Docker mode |
--openclaw-home <dir> | Full OpenClaw home directory to mount | ~/.openclaw |
--workspace <dir> | Workspace directory (workspace-only mode) | — |
--openclaw-config <path> | Path to openclaw.json (workspace-only mode) | — |
--openclaw-version <version> | OpenClaw version to install in the sandbox image | latest |
--openclaw-eval-mode <mode> | Eval mode: isolated or stateful | — |
Container resources
The sandbox container runs with --memory=2g --cpus=2 limits. The proxy binds :443 on 127.0.0.1 inside the container (runs as root, no special capabilities needed).
Troubleshooting
Docker is not available
Install Docker, or use --no-docker with OpenClaw installed locally.
OpenClaw CLI was not found in PATH
In --no-docker mode, install OpenClaw globally:
Sandbox proxy does not yet support domain interception for: <twin>
The requested twin doesn’t have domain mappings in the proxy. Only the six services listed above are supported.
Agent fails with TLS errors
The CA cert may not be trusted. In Docker mode this is automatic. In local mode, verify that NODE_EXTRA_CA_CERTS points to the generated CA cert.
gh auth status fails
The proxy intercepts GET / on api.github.com and returns a synthetic API root response. If gh still fails, ensure GH_TOKEN is not set as an environment variable — it bypasses the proxy’s auth header injection.