# Operating In Agent Sandbox > Read this when you are an AI coding agent running inside an Agent Sandbox container. Explains the network proxy, allowlist policy, filesystem/git constraints, how to discover your own limits from the read-only .agent-sandbox directory, and what to do when a request fails with "Blocked by proxy policy" (HTTP 403) or a direct connection is refused. Use it before fighting a network/permission error or concluding a tool is broken. Use when this capability is needed. - Skill: `tomevault-io/operating-in-agent-sandbox` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/operating-in-agent-sandbox` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/operating-in-agent-sandbox/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/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: `. - 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..policy.yaml` — extra allowlist for the active agent only. - `compose/base.yml` and `compose/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: ```yaml 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 ```bash # Should succeed only if api.github.com is on the allowlist: curl -sS -o /dev/null -w '%{http_code}\n' https://api.github.com # A 403 body of "Blocked by proxy policy: " 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 ``` ## What you cannot do (stop and don't retry) - **You cannot change network policy from inside the container.** `.agent-sandbox/` is mounted read-only, and policy only takes effect after a proxy reload or restart, which is a host-side action. Editing those files from inside will fail or have no effect. - **The `agentbox` CLI is not yours to run** — it runs on the host, not in this container. - **You cannot bypass the firewall or proxy.** No SSH, no direct sockets, no alternate egress. Retrying a blocked request, disabling TLS verification, or hunting for another route wastes turns and won't work. ## What to do when something is blocked 1. Confirm the cause. `Blocked by proxy policy: ` = host not on the allowlist. A connection refused/admin-prohibited on a direct attempt = firewall; route it through the proxy instead (usually automatic via the env vars). 2. Check whether the host is already allowed in `/run/agentbox/policy.yaml` (or, failing that, `.agent-sandbox/policy/*.yaml`). 3. Prefer an allowlisted alternative if one exists (e.g. a mirror or registry that is already permitted). 4. If you genuinely need a blocked host, **ask the human** rather than working around it. Give them the exact host(s) and a ready-to-paste snippet, e.g.: > I need outbound access to `pypi.org` and `files.pythonhosted.org`. Add to > `.agent-sandbox/policy/user.policy.yaml`: > ```yaml > domains: > - pypi.org > - files.pythonhosted.org > ``` > Then on the host run `agentbox proxy reload` to apply it (or > `agentbox compose restart proxy`). > (`agentbox policy config` shows the effective allowlist.) ## Filesystem and git - `/workspace` is your project and is writable. `.agent-sandbox/` is read-only. - Git remotes are rewritten from SSH to HTTPS, and outbound git goes through the proxy. Push/pull works only for repos the policy allows. - Credentials are injected at the proxy via credential shims; you generally will not see raw tokens as env vars, and you do not need them — authenticated requests to allowed services are handled for you. ## Bottom line Treat blocks as guardrails carrying information, not obstacles to defeat. Read `.agent-sandbox/` to learn the rules, prefer what's already allowed, and when you truly need more access, hand the human a precise, minimal request they can apply on the host. --- > Source: [mattolson/agent-sandbox](https://github.com/mattolson/agent-sandbox) — distributed by [TomeVault](https://tomevault.io).