agent-infra/sandbox: one container for an agent's browser, shell and files
All-in-One Sandbox for AI Agents that combines Browser, Shell, File, MCP and VSCode Server in a single Docker container.
At a glance
- What is it?
- AIO Sandbox bundles a browser, shell, file API, MCP servers and code-server inside a single Docker image so an agent can act in one filesystem. It is convenient for prototyping and awkward if you want per-tool isolation.
- Who is it for?
- Adopt it when you want an agent to download a file in a browser and immediately read it from the shell, and when a single trusted container per session is acceptable. Skip it if your threat model requires per-tool isolation or if you cannot run containers with seccomp=unconfined.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem: single-purpose sandboxes force you to stitch state together
The README states the motivation plainly: traditional sandboxes are single-purpose, whether browser, code or shell, and that makes file sharing and functional coordination hard. If an agent downloads a PDF in a browser sandbox and then needs to parse it with a shell command, someone has to move bytes between two runtimes. That usually means a shared volume, an object store, or an upload endpoint, plus the glue code to keep the two views consistent. AIO Sandbox removes that seam by running everything in one container with one filesystem, so a file written by the browser tool is the same file the shell tool sees at the same path. The audience is agent framework authors and developers who need a disposable execution environment that already contains a browser, a terminal, an editor and MCP servers, rather than assembling four images and a message bus.
Architecture: one container, many interfaces, one port
Everything listens behind port 8080. The README lists the entry points once the container is up: the API docs at /v1/docs, a VNC browser at /vnc/index.html?autoconnect=true, VSCode Server at /code-server/, and MCP services at /mcp. Browser control is exposed three ways according to the README: VNC for visual interaction, CDP for programmatic control, and MCP tools for higher-level automation. The MCP servers listed are Browser, File, Shell and Markitdown, so document conversion sits alongside the execution tools rather than being something you add. The SDKs talk to the same HTTP surface: the Python example calls client.sandbox.get_context() to read home_dir, then client.shell.exec_command(command="ls -la") and client.file.read_file(file=...). The TypeScript client mirrors this with sandbox.shell.exec and sandbox.file.read. The design consequence is that there is no isolation boundary between tools at runtime. A shell command can read whatever the browser wrote, and the reverse holds too. That is the feature and the risk in the same sentence.
Getting it running, and the flags you should not drop
The README's quick start is a single docker run against ghcr.io/agent-infra/sandbox:latest, published on 127.0.0.1:8080, with SANDBOX_API_KEY set via -e and --security-opt seccomp=unconfined passed to the container. That seccomp flag is not decorative: the image expects a relaxed seccomp profile, which is worth knowing before you drop it into a cluster with a default runtime policy. Authentication is opt-in. The README says SANDBOX_API_KEY protects all services (API, JupyterLab, VNC) and can be supplied three ways: the X-AIO-API-Key header, an Authorization: Bearer header, or an ?api_key= query parameter. Without that variable, the README states services remain open for backward compatibility. The examples bind the host side to 127.0.0.1 on purpose, because the sandbox itself listens on 0.0.0.0 inside the container; the cloud deployment guide tells you to keep 8080 private and publish it through a reverse proxy or Ingress. For reproducible deployments the README says to pin a release tag, and it documents a mainland China mirror at enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox. Client libraries are installed separately: pip install agent-sandbox, npm install @agent-infra/sandbox, or go get github.com/agent-infra/sandbox-sdk-go. The Python client is constructed as Sandbox(base_url="http://localhost:8080").
Where the all-in-one model works against you
The shared filesystem is the whole pitch, and it is also the failure mode. If an agent is tricked into running a destructive shell command, nothing in this design stops it from touching the files the browser session just downloaded, because they are the same files. There is no per-tool capability boundary described in the README. The security posture rests on two things instead: the container boundary, and the API key. The API key is off by default, and the README frames that as backward compatibility. If you expose port 8080 without setting SANDBOX_API_KEY, the documentation's own wording is that services remain open. The query parameter form, ?api_key=, also puts the secret in URLs, which end up in logs and browser history in a way headers do not. A second constraint is operational: --security-opt seccomp=unconfined weakens the default syscall filtering for the container, so this is not a workload you should co-locate casually with others on the same host. Finally, the container is heavy by construction. A browser, a Jupyter environment, VSCode Server and multiple MCP servers ship in one image, which is a lot of surface for a task that only needs to run a Python function. If your agent never opens a web page or a file, a narrower runtime is the better fit.
How it differs from a plain Docker container or E2B-style remote sandboxes
The obvious alternative is a hand-rolled Docker image with Python, a headless Chrome and an SSH or exec endpoint. That gives you full control over what is installed and how the pieces are wired, and it avoids the seccomp relaxation if you configure Chrome to run without it. What you give up is the pre-wiring: the MCP servers, the VNC endpoint, code-server, Jupyter and the port-forwarding preview all have to be assembled and kept in sync yourself, and the SDK surface (get_context, exec_command, read_file, screenshot) is something you would write. The other comparison class is hosted sandbox APIs, where the vendor runs the container and you call an SDK. Those typically isolate each session for you and remove the container runtime from your responsibility, at the cost of running outside your network and paying per session. AIO Sandbox sits between the two: you own the container and the network exposure, but you get a documented bundle of tools and three official SDKs instead of a blank base image. If your constraint is data residency or air-gapped execution, self-hosting this image is the point. If your constraint is not wanting to run container infrastructure at all, it is the wrong choice.
Maintenance, versions and the Apache-2.0 terms
The project is active rather than archived, with a last push in September 2026 and releases v1.9.3, v1.10.0 and v1.11.0 between late May and late June 2026. The README's own guidance is to pin a release tag for reproducible deployments, which matters here because the quick start otherwise pulls :latest and the image contains a browser and a set of MCP servers that will change under you. Pinning also lets you test an upgrade before it reaches production agents. The mirror tag and the GitHub Container Registry tag are versioned in parallel, so a pin needs to be verified against whichever registry you actually pull from. On licensing: the repository is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant, with the usual requirements around retaining notices and stating changes. The README does not enumerate the licences of the bundled components, and a browser, code-server, Jupyter and MCP servers each carry their own terms. If you redistribute the image or build a product on it, that is the inventory to check; nothing here is legal advice, and the bundled notices are the authoritative source. The SDK packages are published separately on PyPI and npm, so their version numbers can drift from the container tag you pinned.
Who should adopt it, and what to confirm before you do
This fits agent developers who need a disposable environment where browsing, file handling and command execution share state, and who are comfortable running a container with a relaxed seccomp profile. It also fits evaluation work: the repository ships an examples directory and an evaluation directory, and the README links a paper, so there is material to check against your own tasks before committing. It does not fit anyone who needs per-tool isolation, who must run under a strict default seccomp policy, or who only needs to execute code with no browser or file interaction. Before adopting, confirm four concrete things. First, that SANDBOX_API_KEY is set in every environment, including local ones, and that you are not relying on the query parameter form. Second, that port 8080 is reachable only through the reverse proxy or Ingress you intend, since the container listens on 0.0.0.0 internally. Third, that the release tag you pin resolves in your registry, whether that is ghcr.io/agent-infra/sandbox:1.11.0 or the Volcengine mirror. Fourth, that your runtime permits seccomp=unconfined, or that you have a plan for what happens when it does not.
Editorial conclusion
Adopt it when you want an agent to download a file in a browser and immediately read it from the shell, and when a single trusted container per session is acceptable. Skip it if your threat model requires per-tool isolation or if you cannot run containers with seccomp=unconfined. Before deploying, verify three things against your own setup: that SANDBOX_API_KEY actually gates the endpoints you expose, that port 8080 stays private behind a reverse proxy, and that the version tag you pin exists in the registry you pull from.
Community notes