Sandbox mode

Run your agent in an isolated Docker container with transparent HTTPS interception routing to digital twins.

Sandbox mode runs your agent inside a Docker container with a TLS-intercepting proxy that reroutes supported HTTPS calls to hosted twins. The agent keeps using normal tools and service domains; supported traffic hits a twin instead of production.

Requirements

Mode	Requires
Docker (default)	Docker Engine running locally
Local (--no-docker)	OpenClaw CLI installed and in PATH

Both modes require Node.js 20+ and an Archal auth token (ARCHAL_TOKEN or ~/.archal/credentials.json).

Quick start

archal run scenarios/security-suite/exec-impersonation.md --sandbox

With a custom OpenClaw home directory:

archal run scenarios/github/close-stale-issues.md \
  --sandbox \
  --openclaw-home ~/.openclaw

Without Docker (local proxy mode):

archal run scenarios/github/close-stale-issues.md \
  --sandbox \
  --no-docker

How it works

Docker mode (default)

1. Archal provisions cloud twin sessions and gets URLs (e.g. https://sess.twins.archal.ai/github/api)
2. A Docker container starts with the archal/sandbox image
3. Inside the container, the entrypoint:
   • Generates a short-lived CA certificate and installs it in the container 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 proxy and CA env vars (HTTP_PROXY, HTTPS_PROXY, NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE) so supported HTTP clients route through the proxy.

Local mode needs manual /etc/hosts entries (the CLI prints them at startup). The local CA is generated per run and cleaned up at teardown — no host OS trust root is installed.

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

Tenant-specific subdomains (e.g. 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

You can also supply a config file:

archal run scenario.md --sandbox \
  --workspace ./my-project \
  --openclaw-config ./openclaw.json

If no LLM auth exists in the mounted files, set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_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:

npm install -g openclaw

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.

Related

• Route-mode trust and safety
• archal run --harness
• archal twin