OpenSandbox: a sandbox runtime for AI agents that need Docker or Kubernetes

The problem OpenSandbox solves, and who is meant to use it

An AI agent that writes and runs code needs somewhere to run it that is not your laptop or your production node. The usual answer is a container, and the usual problem is that containers are a deployment primitive, not an agent primitive. You still have to create the container, wait for it, exec into it, move files in and out, tear it down, and decide what it can reach on the network. OpenSandbox packages that whole loop as a product: a sandbox server, a protocol for lifecycle and execution, and clients that speak it.

The README frames the target audience by scenario rather than by job title: Coding Agents, GUI Agents, Agent Evaluation, AI Code Execution and RL Training. Those are different workloads. A coding agent wants a long-lived shell with a filesystem it can edit. An evaluation harness wants many short-lived sandboxes that start fast and die cleanly. RL training wants volume. OpenSandbox tries to cover all three with one API surface, which is why it ships both a Docker runtime for local work and a Kubernetes runtime for distributed scheduling.

The SDK list is unusually broad for a project at this stage: Python, Java/Kotlin via Gradle or Maven, JavaScript/TypeScript on npm, C#/.NET, and Go. That breadth is the clearest signal of intended use. This is not a Python-only research tool. It is aimed at platform teams who will be asked to give several product teams a way to run untrusted code.

How the sandbox protocol, server and execd fit together

The architecture is layered, and the repository layout shows it. The specs/ directory holds the sandbox protocol, which the README describes as defining both sandbox lifecycle management APIs and sandbox execution APIs. That split matters. Lifecycle is create, start, stop, delete. Execution is run a command, read a file, write a file. A runtime that implements the protocol can be swapped without changing the client.

The server/ directory contains the sandbox server, released as server/v0.2.3. The components/ directory holds the pieces that sit around it: components/execd, released as docker/execd/v1.1.0, plus components/ingress and components/egress. The name execd suggests an execution daemon that receives command and file operations inside a running sandbox, though the README does not describe its internal design beyond the release tag. The ingress component is described as a unified ingress gateway with multiple routing strategies, and egress as per-sandbox outbound controls.

The data flow implied by the documentation is: a client SDK or the osb CLI talks to the server, the server schedules a sandbox through the Docker or Kubernetes runtime, and command and file operations go through the execution API to whatever process handles them inside the sandbox. A separate credential vault injects credentials into outbound requests so the workload never holds the real secret. That last piece is the most interesting design decision in the README, because it moves secret handling out of the sandbox and into the network path. The README points to docs/guides/credential-vault.md for the details, and does not summarise them.

Installing OpenSandbox and running a first command

The README lists two hard requirements for local use: Docker, and Python 3.10 or later for the examples and local runtime. The server is started with uvx, which means you do not install it into a project environment first. The first command writes a configuration file from the Docker example, and the second starts the server.

uvx opensandbox-server init-config ~/.sandbox.toml --example docker
uvx opensandbox-server

After the server is running, the README's CLI quick start configures the connection. Note that the domain is set to localhost:8080 with the http protocol, and an API key is set separately. The README does not say how that key is generated, which is a gap you will hit immediately.

osb config init
osb config set connection.domain localhost:8080
osb config set connection.protocol http
osb config set connection.api_key <your-api-key>

The CLI installs from PyPI or through uv, and creates a sandbox from an image with a timeout. The -o json flag returns the sandbox object, which is where you get the sandbox id used by later commands.

pip install opensandbox-cli
osb sandbox create --image python:3.12 --timeout 30m -o json
osb command run <sandbox-id> -o raw -- python -c "print(1 + 1)"

If you prefer the Python SDK, the README's code interpreter example installs opensandbox-code-interpreter and creates a sandbox from opensandbox/code-interpreter:v1.1.0, passing an entrypoint, an environment variable and a ten minute timeout. The example is truncated in the README at the point where it runs a shell command, so the file and code execution calls are not shown. Expect to read docs/examples/code-interpreter.md before you have a complete script.

Where OpenSandbox is the wrong tool

The most concrete limitation is documented rather than implied: image verification. The README states that tagged release images are signed keylessly with Cosign and include provenance attestations, and that production images should be pinned by digest and verified against the OpenSandbox GitHub Actions identity following docs/community/release-verification.md. That is a correct practice, and it is also work. If your team does not already have a process for verifying image signatures, adopting OpenSandbox adds one before you run a single sandbox.

A second limitation is the documentation itself. The README does not document rollback, does not describe how to upgrade a running server, and does not explain how the API key used by the CLI is issued. The credential vault, the ingress gateway and the egress controls each have their own documents, which means the README alone is not enough to operate the system.

The third limitation is scope. OpenSandbox is a platform, not a library. If you want to run one Python snippet in a subprocess, this is a large amount of infrastructure for that job, and a plain container or a language-level isolation mechanism will be simpler. The Kubernetes runtime in particular only pays off when you actually need distributed scheduling. A single developer running Docker locally gets the Docker path and none of the scheduling benefit.

Finally, the maintenance signal. The repository is not archived, but the last push was on 2026-08-26, and the most recent releases (docker/execd/v1.1.0, server/v0.2.3, python/sandbox/v0.1.16) all carry the same date. That is a real release event, not a stale repository, but it is also not evidence of a steady cadence. The README does not state a release schedule or a support policy.

How OpenSandbox differs from running your own containers or a hosted sandbox API

The obvious alternative is Docker plus your own orchestration: create a container, exec into it, copy files, remove it. That approach has no protocol to learn and no server to run, and it is the right answer when the workload is yours and the code is trusted. The difference in OpenSandbox is that lifecycle and execution are separated into a documented protocol, so the same client code can target a local Docker daemon or a Kubernetes cluster. With hand-rolled Docker you write that abstraction yourself, once, and then maintain it.

The second alternative is a hosted code execution service, where the sandbox is someone else's problem. Those services remove the operational burden entirely and typically bill per execution. The trade-off is the opposite of OpenSandbox's: you cannot choose the isolation runtime, you cannot put the sandbox on your own network, and the credential vault pattern in the README, where secrets are injected into outbound requests rather than handed to the workload, is not something you control. OpenSandbox is for teams that need that control and are willing to run the server.

The third comparison is against Kubernetes-sigs/agent-sandbox, which the README references directly in examples/agent-sandbox/. The README describes that example as running OpenSandbox workloads on Kubernetes with kubernetes-sigs/agent-sandbox, which suggests the two are intended to compose rather than compete. If you are already committed to that project's model, the OpenSandbox example is the place to start, not a reason to choose one over the other.

Maintenance cost, licence and what the release process commits you to

The licence is Apache-2.0, which permits commercial use, modification and redistribution with the usual attribution and notice requirements. Nothing in the README suggests additional restrictions. This is not legal advice, and if you are embedding the sandbox server in a product you should read LICENSE and the NOTICE handling yourself.

The operational cost is where the real commitment sits. Running OpenSandbox means running the sandbox server, and depending on your configuration, the ingress gateway and the egress path. The Kubernetes runtime means cluster resources and the scheduling behaviour that comes with it. Release images are published to three registries (Docker Hub, GitHub Container Registry and Alibaba Cloud Container Registry) under the same component name, so you have a choice of pull source, and the README asks you to pin by digest.

Upgrade cost is the least documented part. The README does not describe version compatibility between the server and the SDKs, and the release tags are per component (server 0.2.3, execd 1.1.0, Python sandbox SDK 0.1.16), which means the components version independently. Before you deploy, check whether the SDK version you install is tested against the server version you run. The README does not answer that, and the release notes are the place to look.

Editorial conclusion

Adopt OpenSandbox if you already run Docker or Kubernetes and want a sandbox layer that ships SDKs, an osb CLI and an MCP server rather than a single Python helper. Avoid it if you need a hosted service with an SLA, or if you cannot accept that the last push to main was 2026-08-26 and the README does not document rollback, upgrade paths or a support commitment. Before installing, verify three things: whether the release images you plan to pin are signed and attested as the README claims, whether your runtime needs the gVisor, Kata or Firecracker path described in docs/guides/secure-container.md, and whether the egress controls in components/egress actually cover the outbound traffic your workload generates. The Apache-2.0 licence removes the legal question, not the operational one.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes