Operating In Agent Sandbox

Operating Inside an Agent Sandbox

Agent Sandbox runs AI coding agents inside a locked-down local container. If you are reading this from inside one, your network is restricted and your filesystem is partly read-only by design. This is not a bug. Knowing the rules lets you work with the sandbox instead of wasting turns fighting it.

This skill is generic. The authoritative, current constraints for your specific sandbox always live in the read-only .agent-sandbox/ directory in your project root. Read those files; do not rely on memory or assumptions.

Am I in a sandbox?

You are almost certainly inside an Agent Sandbox if any of these hold:

• HTTP_PROXY / HTTPS_PROXY are set to http://proxy:8080.
• A read-only .agent-sandbox/ directory exists at the workspace root.
• You are the non-root user dev (uid 501) and lack general sudo.
• A proxy CA certificate is mounted at /etc/mitmproxy.

The network model (two enforcement layers)

1. Firewall (in your container). All direct outbound traffic is dropped. Only the Docker host network — which includes the proxy sidecar — is reachable. A direct connection that bypasses the proxy is rejected immediately (ICMP admin-prohibited), so it fails fast rather than hanging. SSH outbound is disabled.

2. Proxy (the proxy sidecar). All HTTP/HTTPS must go through http://proxy:8080. The standard proxy env vars are already set, so most tools (curl, git, package managers, language toolchains) use it automatically. The proxy enforces a domain/service allowlist. Anything not on the allowlist is blocked.

   • A blocked request returns HTTP 403 with body Blocked by proxy policy: <host>.
   • For HTTPS, the blocking CONNECT is refused before the tunnel opens.

The proxy is a TLS-terminating man-in-the-middle. Its CA cert is installed in the container's system trust store. Tools that use the system store just work. A tool that ships its own CA bundle (some Node, Python, Go setups) may report a certificate error — point it at the proxy CA file /etc/mitmproxy/ca.crt (e.g. NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE, SSL_CERT_FILE) rather than disabling verification.

Discover your actual limits

The single most useful file is the effective allowlist, written by the proxy:

• /run/agentbox/policy.yaml — the complete, sanitized list of hosts reachable through the proxy, with their allowed schemes/methods/paths. This is the merged result of every policy layer (agent baseline + user policy), rewritten on proxy startup and on each successful policy reload (SIGHUP). If a host is not in this file, requests to it return HTTP 403. Credentials and request-rewriting rules are intentionally omitted. (Older sandboxes may not export this file yet; if it is missing, fall back to the .agent-sandbox/ files below and to probing.)

For the editable inputs and your runtime config, read these under the read-only .agent-sandbox/ mount:

• active-target.env — which agent is active and the project name.
• policy/user.policy.yaml — shared user-owned allowlist (applies to every agent).
• policy/user.agent.<agent>.policy.yaml — extra allowlist for the active agent only.
• compose/base.yml and compose/agent.<agent>.yml — mounts, volumes, and env you run with.

Note: the .agent-sandbox/policy/*.yaml files show only the user-editable layer. Each agent also has a baseline allowlist (its own API, auth, and CDN endpoints) that is merged in but is not authored in these files. The baseline is reflected in /run/agentbox/policy.yaml. When unsure whether a host is allowed, check that file, or just try the request and read the result.

Allowlist entries take two forms:

services:          # symbolic bundles, e.g. github, claude — expand to known host sets
  - github
domains:           # explicit hosts; wildcards like "*.example.com" are allowed
  - raw.githubusercontent.com

Quick checks you can run

# Should succeed only if the GitHub API is allowed for this repository (the
# allowlist is scoped to repository paths, so the API root itself returns 403):
curl -sS -o /dev/null -w '%{http_code}\n' https://api.github.com/repos/OWNER/REPO

# A 403 body of "Blocked by proxy policy: <host>" means the host is not allowed.
# A direct (non-proxy) attempt is refused by the firewall, not the proxy:
curl --noproxy '*' --connect-timeout 3 https://example.com   # expected to fail