CLI tool
opensandbox-group/OpenSandbox avatar
opensandbox-group/OpenSandbox

OpenSandbox puts one lifecycle API in front of Docker and Kubernetes sandboxes for AI agents

Secure, Fast, and Extensible Sandbox runtime for AI agents. Sandbox Runtime: Built-in lifecycle management supporting Docker and high-performance Kubernetes runtime, enabling both local runs and large-scale distributed scheduling.

17,297 stars1,647 forksPythonApache-2.0

At a glance

What is it?
OpenSandbox is an Apache-2.0 sandbox server, SDK set and osb CLI that gives agents isolated environments for commands, files, browsers and desktops. It starts on local Docker and scales to a Kubernetes runtime with Firecracker sandboxes, but its headline speed and pause/resume claims belong to that Kubernetes path, not to a laptop.
Who is it for?
OpenSandbox fits teams that want agents to run code, browsers or desktops in isolated environments on infrastructure they control, and that expect to move from a Docker host to Kubernetes without rewriting client code. It is more than a single developer needs for occasional local scripts, because even the local path requires running a sandbox server alongside Docker.
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 1 day 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 November 14, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • opensandbox-group/OpenSandbox17,297 ★ · +5,078
Star history
Repository2026-07-282026-11-14
opensandbox-group/OpenSandbox12.2k17.3k

5,078 Stars in the last 109 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

A sandbox server sits between your agent and the container runtime

OpenSandbox is not a library that spawns containers from inside your process. Clients talk to a sandbox server, and the server manages the lifecycle of sandboxes on Docker locally or on Kubernetes in a cluster, through one unified API. Local use requires Docker, and Python 3.10 or newer for the examples and the local runtime.

The server is started with uvx, after generating a config file from the Docker example:

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

uvx opensandbox-server

# Show help
# uvx opensandbox-server -h

The init-config step writes ~/.sandbox.toml from the docker template, so the first server you run targets local Docker. Moving to a cluster means switching to the Kubernetes runtime, which has its own operator documentation under the control-plane architecture docs, and the repository carries kubernetes/ and manifests/ directories for it.

The consequence is an extra moving part even for a one-person setup. Every SDK call and every osb command needs a reachable server, so a laptop workflow involves keeping that process running in addition to Docker.

Five SDKs, the osb CLI and an MCP server share one sandbox protocol

Clients exist for Python, Java and Kotlin, TypeScript and JavaScript, C# and .NET, and Go. The package names are not uniform, which matters when you search a registry:

bash
pip install opensandbox
npm install @alibaba-group/opensandbox
dotnet add package Alibaba.OpenSandbox
go get github.com/alibaba/OpenSandbox/sdks/sandbox/go

The Java and Kotlin artifact is com.alibaba.opensandbox:sandbox, and both the Gradle and Maven snippets use a {latest_version} placeholder rather than a real number, so you have to look up and pin the version yourself. The Go module path sits under github.com/alibaba even though the repository lives at opensandbox-group/OpenSandbox, so copy it exactly rather than deriving it from the repository URL.

The Python quick start creates a sandbox from the alpine image with Sandbox.create, runs a shell command through sandbox.commands.run, and writes a script with sandbox.files.write_files and WriteEntry objects. The calls are async and the sample uses asyncio, so synchronous code needs an event loop wrapper. An MCP server exposes sandbox creation and command execution to agents that speak MCP, and the specs/ directory holds the lifecycle and execution API definitions for anyone building a custom runtime integration.

osb needs a domain, a protocol and an API key before its first command

The osb CLI covers the common loop: create sandboxes, run commands, move files, inspect diagnostics and manage runtime egress policy. It installs as a separate package:

bash
pip install opensandbox-cli
# or
uv tool install opensandbox-cli

Configuration comes first, then sandbox work:

bash
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>
osb sandbox create --image python:3.12 --timeout 30m -o json
osb command run <sandbox-id> -o raw -- python -c "print(1 + 1)"

Each flag shapes the result. --image picks any container image, here python:3.12. --timeout 30m bounds the sandbox's lifetime, so set it to cover the longest agent session you expect. -o json returns machine-readable output for the create call, which is where you read the sandbox ID, while -o raw prints the command's own output. Everything after -- is passed to the sandbox untouched.

The example values point at localhost:8080 over plain http. That suits a server on the same machine; a server on another host needs its own domain and a protocol decision you make deliberately.

The 64 ms figure belongs to Firecracker on Kubernetes, not to local Docker

The headline numbers come from the Fast Sandbox runtime: Firecracker sandbox creation at 64 ms P50 when created serially and 125.4 ms P99 at 10 concurrent creations. Firecracker sandboxes also support pause and resume with memory and disk state preserved. Both claims sit under Fast Sandbox, which is described as fast, high-density sandboxes on Kubernetes, with separate pages for integration, performance and checkpoints.

That scoping is easy to miss. The quick start runs on local Docker, and nothing in it ties the Firecracker creation times or the pause/resume behaviour to that path. Someone evaluating OpenSandbox on a laptop and expecting snapshots of a running agent, or creation times in the tens of milliseconds, is measuring a different runtime from the one those figures describe.

The practical consequence is a planning one. If fast creation or pause/resume is the reason you are choosing OpenSandbox, budget for the Kubernetes Fast Sandbox deployment and read docs/architecture/fast-sandbox/performance.md and checkpoints.md for the conditions behind the numbers, rather than extrapolating from local Docker runs.

Egress policies and the credential vault decide what sandboxed code can reach

Isolation of execution is only half of running untrusted agent code; the other half is what that code can talk to. OpenSandbox handles inbound traffic through a unified ingress gateway and outbound traffic through per-sandbox egress policies, and osb can manage the runtime egress policy from the terminal.

The Credential Vault addresses a separate risk: agents need to call external services, but handing real API keys to code running inside a sandbox exposes them to whatever that code does. The vault lets agents call those services without exposing the real credentials to sandbox workloads.

Neither control helps if it is never configured. A sandbox created with only an image and a timeout, as in the CLI quick start, says nothing about egress, so the network posture of that sandbox is whatever your server configuration provides. Anyone running model-generated code, coding agents with shell access, or browsers pointed at arbitrary sites should set egress rules and route secrets through the vault before exposing the system to real workloads. The ingress and egress design pages under docs/architecture/network/ and the credential vault guide are where those settings live.

Resource pools and batch creation target evaluation and RL runs

Beyond single interactive sandboxes, the local-to-cluster lifecycle API offers resource pools and batch creation, aimed at agent evaluation and reinforcement learning workloads where each trial needs a fresh environment. The Harbor Evaluation example runs evaluations with a separate sandbox per trial.

The examples/ directory shows how wide the integration surface is. It includes Claude Code, Codex CLI, Gemini CLI, Kimi CLI, OpenCode, GitHub Copilot CLI and OpenClaw for coding agents; LangGraph, Google ADK, Microsoft Agent Framework, Deep Agents and DeerFlow for frameworks; Chrome, Playwright and desktop for browser and GUI automation; and a code interpreter for running model-generated code. Storage patterns are covered too, with Docker OSSFS and PVC volume mounts, a host volume mount, a Kubernetes PVC mount and an AKS Kata example.

The consequence for adopters is that a close starting point may already exist, but each one is a separate integration with its own assumptions about images, volumes and runtime. Pick the example closest to your stack and treat it as a starting point; its runtime choice, Docker or Kubernetes, determines which of the features above it can use.

Three releases in twelve days, under foundation governance

The 1.2.0 line moved quickly: release-1.2.0-rc.1 on 2026-10-15, rc.2 on 2026-10-21 and the final OpenSandbox 1.2.0 on 2026-10-27. The last push to the main branch was on 2026-11-01, and the repository is not archived. The license is Apache-2.0.

OpenSandbox is listed as an Agentic AI Foundation (AAIF) project, and the repository root carries CHARTER.md, GOVERNANCE.md, MAINTAINERS.md, ROADMAP.md and SECURITY.md, plus an oseps/ directory alongside the code. A separate console/ directory sits next to server/, cli/ and sdks/.

Fast release candidates mean that a client SDK, the server and the osb CLI can drift apart if you upgrade them at different times. Since the Java snippets never name a version and the Python, npm, .NET and Go install lines install whatever is current, pin each client to the same release as your server and upgrade them together. The release tags follow a release-X.Y.Z pattern, which is the reference to use when matching components.

Editorial conclusion

OpenSandbox fits teams that want agents to run code, browsers or desktops in isolated environments on infrastructure they control, and that expect to move from a Docker host to Kubernetes without rewriting client code. It is more than a single developer needs for occasional local scripts, because even the local path requires running a sandbox server alongside Docker. Before relying on it, check whether the Firecracker figures and pause/resume apply to the runtime you will deploy, configure egress policies and the credential vault for untrusted code, and pin SDK versions yourself where the install snippet shows a placeholder.

Frequently asked questions

What is OpenSandbox?

OpenSandbox is an Apache-2.0 sandbox runtime that gives AI applications isolated environments to execute code, run commands, manage files and operate browsers or desktops. It starts locally with Docker and deploys on Kubernetes through a unified sandbox API.

What is a sandbox and why is it used in OpenSandbox?

In OpenSandbox a sandbox is an isolated environment where an agent runs commands, code, browsers or desktops away from the host. Egress policies and a credential vault limit what that code can reach and which secrets it sees.

How does an OpenSandbox sandbox relate to Docker?

OpenSandbox uses Docker for local execution and requires it there; the sandbox server manages sandbox lifecycle on top of Docker or Kubernetes. Its Fast Sandbox runtime on Kubernetes uses Firecracker and supports pause and resume.

Official sources

  1. Official documentation
  2. Official README
  3. Project repository
  4. Release notes
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/opensandbox-group-opensandbox.svg)](https://hysenlabs.com/projects/opensandbox-group-opensandbox)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/opensandbox-group-opensandbox.svg)](https://hysenlabs.com/projects/opensandbox-group-opensandbox)

Was this useful?