OpenSandbox Architecture: How the Pieces Fit Before You Deploy
By Fabio Douek
Jump to section
- Overview
- Architecture
- Concepts
- The sandbox and its states
- The Kubernetes objects
- The configuration model
- Egress in three layers, and the Credential Vault
- The isolation menu
- What runs where on Kubernetes
- Setup
- Step 1: Tools and the companion code
- Step 2: The server config, and why not the packaged example
- Step 3: Start the server
- Testing
- Test 1: A first sandbox from the Python SDK
- Test 2: The same with the osb CLI
- Test 3: A deny-by-default network policy
- What the local runs showed
- Verdict
- What you sign up for
- Who it suits
Explain (TLDR) like I am...
Imagine a sandbox at the park where a robot helper can dig and build without making a mess anywhere else. Now imagine every robot gets its own little sandbox, a grown-up who sets it up and tidies it away, and a gate that decides which parts of the park the robot may visit.
The clever bit is that the gate keeps the real keys. The robot only carries pretend keys, and when it walks up to a door it is allowed through, the gate swaps in the real one. When I tried it, the gate kept one door shut until I said yes, and then it opened right away.
OpenSandbox is an Apache 2.0 platform for running code written by AI agents in isolated sandboxes on infrastructure the organization operates. The Agentic AI Foundation, a directed fund of the Linux Foundation, announced it as a project on October 22, 2026, though its maintainers and several package names still trace back to Alibaba.
The diligence questions are maturity and custody. There is no long-term support line and no stable v1 API, recent releases are not signed despite what the documentation says, and outbound credentials sit in a proxy inside the same pod as the untrusted code. Treat it as infrastructure the team owns and audits.
The presenting problem is code written by an agent that needs somewhere safe to run, with network access and API keys it should not be able to steal. The treatment is layered: a container or virtual machine per sandbox, an egress sidecar that filters names and packets, and a vault that adds credentials on the way out.
The evidence here is a local trial of release 1.2.0 on Docker, where a deny-by-default policy blocked one host and allowed it after a live change. Contraindications: gVisor cannot be combined with egress control, and most of the release's new features target a Firecracker profile this series does not run.
There is a quiet tension in handing an agent a shell: you want it to get real work done, and you worry about what it can reach. OpenSandbox tries to hold both, giving each agent its own space while the network rules and the secrets stay in someone else's hands.
The relief is real, and so is the new homework. A team that adopts it takes on a server, a controller, sidecars and a release line planned every two weeks with no long-term support. The project now sits in a Linux Foundation fund, yet about half of its commits come from accounts tied to one company, which is worth saying out loud early.
Think of OpenSandbox as a set of rehearsal rooms booked one per player. The lifecycle server is the booking desk, execd is the engineer sitting in each room, and the egress sidecar is the door that decides who may step out into the hall and which hallways lead anywhere.
The local session kept good time: about four seconds to open a room once the gear was warm, longer for the first take of the day. The interesting part was the door. One hallway stayed shut until I changed the chart mid-session, and the next take walked straight through with no count-in.
The story is ownership. OpenSandbox lets a platform team run agent sandboxes on its own machines, with a vault that keeps real API keys out of the sandbox. The Agentic AI Foundation, a directed fund of the Linux Foundation, announced it as a project on October 22, 2026.
Time to value on a laptop is short: a pinned config file, a first sandbox in about four seconds once warm, and a working deny-by-default network policy in the same session. The honest positioning is for teams willing to run infrastructure and keep up with fast releases, not for teams shopping for a hosted product.
Overview
On October 22, 2026, at AGNTCon + MCPCon North America in San Jose, the Agentic AI Foundation (AAIF) announced OpenSandbox as one of its projects, contributed by Alibaba. The paperwork came two days earlier: the project’s technical charter, adopted October 20, 2026, makes it “OpenSandbox a Series of LF Projects, LLC” and names AAIF as “a directed fund of The Linux Foundation”. Xiaobin Xu, Head of Development Infrastructure at Alibaba, gave the reason in the announcement:
“While OpenSandbox was created at Alibaba, we don’t want its future to be defined by a single company. By bringing the project to AAIF, we’re creating a path for more developers and organizations to help shape how sandbox environments work across the agent ecosystem.”
OpenSandbox is an Apache 2.0 platform for running the code AI agents write: shell commands, files, code interpreters, browsers. You ask a lifecycle server for a sandbox, it creates one on Docker or Kubernetes, and a small daemon inside the sandbox, execd, runs what you send it. The part I care most about is the network side. An egress sidecar can hold a sandbox to a deny-by-default allowlist, and its Credential Vault adds API credentials to outbound requests, so the code in the sandbox is meant to hold only placeholders. Own the sandbox, and keep the keys outside it: that’s the angle of this series.
The code has been public since December 17, 2025, when the repository was created and the first execd release was tagged. Release 1.2.0 shipped on October 27, 2026, and every image, package and chart in this series is pinned to it.
This post, part 1 of 6, is the map: how the pieces fit, the concepts you need before deploying anything, and a short local run with the Python SDK, the osb CLI and a network policy. Part 2 installs OpenSandbox on Amazon EKS 1.37, part 3 covers the sandbox lifecycle, pools and isolation, part 4 the egress sidecar and Credential Vault, part 5 AWS credentials signed at the egress, and part 6 stress-tests two nodes. Everything in Setup and Testing ran on my arm64 Mac on October 31, 2026, under Docker Desktop (Docker 29.2.1).
Architecture
The project’s architecture overview describes OpenSandbox as six surfaces and three traffic paths. The surfaces are what you install or call. The paths are what you secure.
| Surface | What it is | Where it runs |
|---|---|---|
| Client | SDKs for Python, JavaScript/TypeScript, Java/Kotlin, C#/.NET and Go; the osb CLI; an MCP server (opensandbox-mcp) | Your application, your laptop, the agent’s host |
| Protocol | OpenAPI specs under specs/: the lifecycle API (base path /v1), the execd API, the egress API, diagnostics | Contracts, not a process |
| Lifecycle control plane | A FastAPI server: API keys, request validation, endpoint resolution, an optional proxy, a small store | One process on Docker, one Deployment on Kubernetes |
| Runtime backends | Docker, or Kubernetes through a controller and three custom resources; optionally Fast Sandbox for Firecracker microVMs | Your Docker host or your cluster |
| Sandbox data plane | Your image plus execd on port 44772 | One container, or one pod |
| Network and security | Ingress gateway, egress sidecar, Credential Vault, secure container runtimes | One gateway Deployment; one sidecar per sandbox |
Lifecycle and execution traffic come from whichever client you use. Outbound traffic starts inside the sandbox. The three paths, in the diagram’s colors:
- Lifecycle (amber). Create, list, pause, resume, renew and delete go to the server. It validates the request and hands it to the runtime backend: on Docker it creates the containers itself, on Kubernetes it writes a custom resource and the controller does the rest.
- Execution and service (blue). Commands, files, the interactive terminal (PTY) and code execution skip the server. A client asks the server once for the endpoint of port 44772 and then talks to
execddirectly (a host port on Docker, a pod IP on Kubernetes), through the ingress gateway, or through the server’s proxy at/sandboxes/{id}/proxy/{port}when neither is reachable, where the server relays the request toexecditself. - Outbound (green). Traffic from the sandbox to the outside world. With no network policy it leaves like any container’s traffic. With one, it goes through the sandbox’s own egress sidecar, which enforces the policy and can inject credentials.
Two rules from the server architecture doc are worth knowing before you deploy anything: the API never talks to a runtime directly, and sandboxes are never rows in the server’s database. On Kubernetes the custom resources are the source of truth; on Docker, the containers and their labels are. The server’s store holds only what the server owns: snapshot metadata and the template catalog for Fast Sandbox.
Fast Sandbox is the odd one out. It’s a separate platform (opensandbox-group/fast-sandbox) that runs Firecracker microVMs inside pre-warmed pods, and the server routes to it when a create request names a templateId. This series doesn’t install it; the isolation menu below lists what it needs.
Concepts
Everything in this section is read from the docs and source at the release-1.2.0 tag. I run the Docker path in Setup and Testing below; the Kubernetes side gets run on EKS in parts 2 to 6.
The sandbox and its states
A sandbox is one isolated environment with an ID, an image, resource limits and, usually, an expiry. In the spec, creation is asynchronous: the server can answer while the sandbox is still Pending, and the SDKs poll until it’s Running. On Kubernetes, the 1.2.0 server answers only once the pod is running (part 3 checks). The lifecycle spec defines eight states:
A few rules the names don’t tell you:
resume()only works fromPaused. A sandbox whose workload exited ends inTerminated(exit code 0) orFailed(non-zero), and the answer to either is a new sandbox. The server never quietly restarts one. A deleted pod is another matter: part 3, Test 6, shows the controller re-creating it while the sandbox staysRunning.- On Kubernetes,
DELETEreturns 204 and the sandbox reportsStoppinguntil its pods are gone, then 404. That’s a 1.2.0 change, as is an expired BatchSandbox reportingTerminatedwith the reasonSANDBOX_EXPIRED, per the release notes; part 3 never caught that state on the way to deletion. - Pausing on Kubernetes commits the sandbox’s root filesystem to an image in an OCI registry and deletes the pod. Resume recreates it from that image under the same ID. Files come back; memory, running processes and Credential Vault entries don’t (pause and resume guide). Part 3 measures it.
Expiry and renewal. Four mechanisms decide how long a sandbox lives:
| Mechanism | What it does | Limits |
|---|---|---|
timeout at create | Sets an absolute expiry, counted from creation. It isn’t an idle timeout, and server or runtime restarts don’t reset it | At least 60 s; capped by max_sandbox_timeout_seconds when the server sets one (unset by default; the packaged example configs set 86,400) |
renew-expiration | Sets a new absolute expiry | Can shorten as well as extend; not capped by max_sandbox_timeout_seconds |
| Renew-on-access | Traffic through the server proxy, or gateway events delivered through Redis, moves the expiry to max(now + extendSeconds, current expiry) | Opt-in: [renew_intent] on the server and lifecycle.renewalPolicy.extendSeconds (300 to 86,400) on the sandbox |
| Idle pause and wake on access | Pauses an idle sandbox and wakes it on the next request | Fast Sandbox only in 1.2.0 |
timeoutis optional in the API: leave it out or sendnulland the sandbox never expires on its own, though Kubernetes providers that can’t run non-expiring workloads may reject that.- The Python SDK sends 10 minutes when you don’t pass a timeout, and no expiry when you pass
timeout=None. My scripts set 10 minutes explicitly.
The Kubernetes objects
On Kubernetes the server never creates a pod. It creates custom resources, objects of new types that the project adds to Kubernetes through custom resource definitions (CRDs), in the sandbox.opensandbox.io/v1alpha1 group. One controller manager with three reconcilers, control loops that keep each resource’s pods and images in line with its spec, turns them into pods and images:
| Object | What it is | Fields that matter |
|---|---|---|
BatchSandbox (short name bsbx) | One sandbox, or a batch of identical ones: a pod template or a reference to a Pool, an expiry, a pause flag, optional tasks | replicas, template or poolRef, expireTime, pause, taskTemplate |
Pool | Warm, ready pods that a sandbox can claim instead of waiting for a cold start | template, capacitySpec (bufferMin, bufferMax, poolMin, poolMax), recycleStrategy (Delete, Restart or Noop) |
SandboxSnapshot | One root-filesystem commit of a sandbox, run as a Job on the sandbox’s node and pushed to an OCI registry | sandboxName; status phase Pending, Committing, Succeed or Failed |
The base chart also installs four sandbox.fast.io CRDs for Fast Sandbox by default, whether you use it or not. A few details that shape parts 2 and 3:
- A
BatchSandboxcan also run tasks, commands the controller starts inside its pods, and it has its own phase list:Succeedmeans “the pod is ready”, not “the task finished”. - Pool recycling is a trade-off you choose.
Delete, the default, deletes a used pod;Noophands the next sandbox the previous one’s files and processes. A sandbox drawn from a pool can’t takevolumesor anetworkPolicy, so per-request egress rules and pools don’t mix. - Snapshot settings (registry, push credentials, image naming) are controller flags, not server config. The commit Job runs as UID 0 with the node’s containerd socket mounted.
- Because the server stores only snapshot records and templates, losing its database loses public snapshot metadata, not sandboxes.
The configuration model
Every server setting lives in one TOML file. Locally it’s ~/.sandbox.toml unless --config or SANDBOX_CONFIG_PATH says otherwise. On Kubernetes the server chart renders a ConfigMap and mounts it at /etc/opensandbox/config.toml.
The chart doesn’t map values to settings one by one. configToml is the entire file as a single string, and overriding it replaces everything in it, including the sandbox namespace. The chart then appends an [ingress] block it generates from the server.gateway.* values, a few settings arrive as environment variables so that secrets stay out of the ConfigMap, and a checksum/config annotation restarts the pod whenever the TOML changes. The configuration reference has every key; these are the sections this series touches:
| TOML section | What it controls | How it’s set on Kubernetes |
|---|---|---|
[server] | Bind address and port, api_key, max_sandbox_timeout_seconds | configToml (port 80 in the chart); the key from a Secret through server.env as OPENSANDBOX_SERVER_API_KEY |
[runtime] | type (docker or kubernetes), execd_image | configToml |
[docker] | Network mode, host port range, publish_host, dropped capabilities, pids_limit | Docker only |
[kubernetes] | Sandbox namespace, BatchSandbox template file, sandbox_create_timeout_seconds (60 by default), API rate limits | configToml; a custom template file through server.volumes and server.volumeMounts |
[ingress] | direct or gateway, the gateway address and route mode, signing keys for gateway endpoint tokens | Generated from server.gateway.* and appended to configToml; keys from secureAccess.keys or an existing Secret |
[egress] | Sidecar image, mode (dns or dns+nft), disable_ipv6, sidecar requests and limits | configToml |
[store] | SQLite path or PostgreSQL | configToml; the DSN through OPENSANDBOX_STORE_POSTGRESQL_DSN |
[secure_runtime] | runc, gVisor, Kata or Kata with Firecracker, and the RuntimeClass to use | configToml |
[tenants] | Multi-tenant API keys from a tenants.toml file | configToml, plus the file through server.volumes |
The server’s image, replicas and resources are ordinary Deployment values, and pause and resume settings belong to the controller chart (controller.snapshot.*), not to the TOML.
Egress in three layers, and the Credential Vault
Egress control is a sidecar container that shares the sandbox’s network namespace. It’s the only running container in the pod with the NET_ADMIN capability; the workload container has it dropped, so code in the sandbox can’t rewrite its own firewall. If the sidecar can’t install its rules at startup it exits, rather than run as a silent pass-through (egress architecture).
The sidecar exists only when the create request includes a networkPolicy. No policy, no sidecar, and outbound traffic is unfiltered. A policy is a defaultAction (allow or deny, with deny as the default) plus rules whose target is a domain, a wildcard (*.example.com matches subdomains, not the apex), an IP or a CIDR. Rules can be changed while the sandbox runs. The three layers each build on the one before:
- DNS proxy, always on. All port-53 traffic is redirected to a DNS proxy in the sidecar on
127.0.0.1:15353. A denied name getsNXDOMAIN; an allowed name resolves and its addresses are recorded. On its own this isdnsmode, which gates names only. A process that connects to an IP directly isn’t stopped. - nftables, in
dns+nftmode. A packet filter that drops anything not explicitly allowed. Addresses learned from allowed DNS answers get a bounded lease, so “allowed” doesn’t quietly become “allowed forever”. DNS over TLS (port 853) is always dropped, and the port-scoped rules added in 1.2.0 need this mode. - Transparent HTTPS proxy, optional. A mitmproxy listener on port 18081 that ports 80 and 443 are redirected into. It terminates TLS with a CA the sidecar generates, and
execd’s bootstrap installs that CA in the sandbox’s trust stores and setsSSL_CERT_FILE,REQUESTS_CA_BUNDLEandNODE_EXTRA_CA_CERTS, so clients keep certificate checks on. The project calls this layer “experimental but production-usable”.
The Credential Vault is built on the third layer. A credential is a name and a value. A binding says where it goes (scheme, host, method, path) and how: bearer, basic, apiKey, customHeaders or passthrough, plus optional placeholder substitutions in the path, query, headers or body. Values are write-only; reading the vault never returns them. Here is one request, start to finish:
- A trusted client outside the sandbox writes credentials and bindings to the sidecar’s API on port 18080, authenticated with that sandbox’s egress token.
- The workload looks up the host. The DNS proxy answers only for allowed names and leases the addresses into nftables’ allow sets.
- The workload connects to port 443 with its placeholder token. A redirect rule sends the connection to the HTTPS proxy, which terminates TLS with the sidecar’s CA.
- The proxy reads the active vault over a private Unix socket and picks the most specific binding that matches the request’s scheme, host, port, method and path: an exact host beats a wildcard. One winner: it sets the header. A tie: the request is refused, with a 403 when the body is small and fully known, or a dropped connection when the body is large (over about 1 MiB) or chunked. No match: the request goes on unchanged. If the socket doesn’t answer, every intercepted request fails closed.
- The proxy opens its own connection upstream, and nftables polices that connection like any other.
- The upstream host gets the real credential. On the way back, response headers that contain an injected value are replaced with
[REDACTED]. Response bodies are not.
The vault has hard prerequisites: dns+nft mode, a network policy and credentialProxy.enabled on the create request. The policy should be deny-by-default with every bound host allowed; default-allow still works in 1.2.0 but logs a security warning. The vault lives only in the sidecar’s memory, so on Kubernetes a pause wipes it and a trusted client has to write it again after resume. And the real credentials sit in the sidecar, which is in the same pod as the untrusted code. Part 4 pokes at all of it, including an issue, open as of November 7, 2026, where the binding is chosen from the Host header rather than the TLS server name (#1758).
The isolation menu
By default a sandbox is an ordinary container under runc, sharing the node’s kernel. Secure container runtimes add a layer, and OpenSandbox supports four of them, plus Fast Sandbox as a separate platform:
| Runtime | [secure_runtime] type | What the nodes need | With egress and the vault |
|---|---|---|---|
| runc | "" (the default) | Nothing extra | Works (Test 3 below runs it on Docker) |
| gVisor | gvisor | runsc and containerd-shim-runsc-v1 on every node, a RuntimeClass | Rejected with HTTP 400 |
| Kata (QEMU or Cloud Hypervisor) | kata | KVM: bare metal, or nested virtualization that exposes /dev/kvm; kata-deploy for the RuntimeClasses | Supported per the docs; part 2 tries it |
| Kata with Firecracker | firecracker (Kubernetes only, RuntimeClass required) | KVM, as above | Allowed by the server; not tried in this series |
| Fast Sandbox | Not a runtime type: chosen per request with templateId | A separate install: KVM, an XFS reflink state disk (setup refuses a disk without reflink; turning XFS off falls back to full copies), one CPU model per pool, cgroup v2, amd64 | One egress process shared by the sandboxes in each pre-warmed pod; the vault survives pause |
The project’s own estimates of the startup cost are about 10 to 50 ms for gVisor, 125 ms for Kata with Firecracker, 200 ms for Cloud Hypervisor and 500 ms for QEMU. I haven’t measured any of them here. Three rules decide what you can actually run:
- One profile per server process. The runtime is server config, not a request field, so a request can’t choose. If you need two, you run two server releases. On Kubernetes the server checks at startup that the RuntimeClass exists and refuses to start if it doesn’t.
- gVisor and egress don’t mix. gVisor’s network stack has no iptables
nattable, which the sidecar’s DNS redirect needs, so the server refuses the combination when the request arrives. gVisor also can’t do the root-filesystem pause and resume. Once you want egress control or the vault, the menu is runc or Kata. - Kata needs KVM. On EC2 that used to mean a
.metalinstance. Since February 2026, EC2 has offered nested virtualization on virtual instances, starting with the 8th-generation C8i, M8i and R8i, and since June 18, 2026, that includes M7i, C7i and R7i, which is what this series’ nodes use. Part 2 checks for/dev/kvmand tries a Kata pod on it; whether Kata runs well nested is still an open question at this point.
What runs where on Kubernetes
A sandbox on Kubernetes is one pod with up to three containers, built by the server’s BatchSandbox provider:
| Container | Kind | What it does | Privileges |
|---|---|---|---|
execd-installer | Init container, from execd_image | Copies execd, bootstrap.sh and helpers into an emptyDir mounted at /opt/opensandbox | privileged when the sandbox has a network policy and disable_ipv6 is on (the default), to write the IPv6 sysctl |
sandbox | Main container, your image | Runs /opt/opensandbox/bootstrap.sh and then your entrypoint; bootstrap starts execd on 44772 and installs the proxy CA when there is one | NET_ADMIN dropped when there is a policy |
egress | Sidecar, only with a networkPolicy | DNS proxy, nftables, the optional HTTPS proxy and the vault; API on 18080 | Adds NET_ADMIN |
Three pod-level settings come from the provider and the default template. automountServiceAccountToken: false, so the sandbox holds no Kubernetes API token. restartPolicy: Never, the 1.2.0 default, because an in-place restart wipes the writable layer while the sandbox keeps looking healthy. And the default BatchSandbox template’s tolerations: [{operator: Exists}], which lets sandbox pods land on any tainted node; part 2 swaps that template out. By the Pod Security Standards, a privileged init container and a sidecar that adds NET_ADMIN mean that a sandbox namespace at the baseline or restricted level would reject sandboxes that have a network policy. I haven’t tried it.
On Docker the same sandbox is one or two containers: sandbox-<id> and, with a policy, sandbox-egress-<id>. The sandbox container joins the sidecar’s network namespace, and the sidecar publishes all of the sandbox’s ports. Test 3 shows it.
Setup
Part 1 runs locally: no cluster, no AWS account, no API keys. The goal is to see each path from the diagram work before part 2 adds Kubernetes.
Step 1: Tools and the companion code
You need Docker, uv (it installs Python, the SDK and the CLI on first use) and curl. The three images take about 1.1 GB on arm64.
git clone https://github.com/fabiodouek/my2centsai-blog-samples.git
cd my2centsai-blog-samples/opensandbox-architecture
| File | What it does |
|---|---|
sandbox.toml | The server config: the packaged Docker example with seven lines changed |
common.py | Connection settings (OSB_DOMAIN, OSB_API_KEY) and the helpers the Python scripts share |
00_server.sh | Shows where the packaged example is stale, pulls the images, starts the server and waits for /health |
01_first_sandbox.py | Python SDK: create a sandbox, run commands, write and read a file, read metrics, kill it |
02_cli.sh | The same through osb |
03_network_policy.py | A deny-by-default policy, one host allowed at creation and a second allowed while the sandbox runs |
99_cleanup.sh | Kills every sandbox, stops the server, removes leftover containers |
Step 2: The server config, and why not the packaged example
The server package can write its own example config with opensandbox-server init-config <path> --example docker. On 1.2.0 that example is out of date. 00_server.sh writes a fresh copy and prints where it differs from the config I ship:
Packaged example (opensandbox-server 1.2.0 init-config --example docker) vs ./sandbox.toml:
-execd_image = "opensandbox/execd:v1.1.0"
+execd_image = "opensandbox/execd:release-1.2.0"
-image = "opensandbox/egress:v1.1.7"
+image = "opensandbox/egress:release-1.2.0"
-mode = "dns"
+mode = "dns+nft"
(api_key, publish_host, [proxy] resolve_internal and [store] path differ too: local choices)
execd:v1.1.0 and egress:v1.1.7 are the last per-component tags from August 2026, before the project moved every component to one version. The 1.2.0 images are tagged release-1.2.0. And mode = "dns" gates names only, which also means the Credential Vault refuses to turn on.
Seven lines change against the example, and the shipped file keeps all of the example’s comments and other settings. Here are the changed lines in context; the end-of-line notes are mine and are not in the file:
[server]
host = "127.0.0.1"
port = 8080
api_key = "local-dev-key" # was commented out; a throwaway local value
[proxy]
resolve_internal = false # the example's own advice for macOS
[runtime]
type = "docker"
execd_image = "opensandbox/execd:release-1.2.0"
[store]
type = "sqlite"
path = "./opensandbox.db" # next to the scripts, gitignored
[docker]
network_mode = "bridge"
publish_host = "127.0.0.1" # commented out in the example
[egress]
image = "opensandbox/egress:release-1.2.0"
mode = "dns+nft"
The key matters because without one the server won’t start unattended: an empty api_key needs YES typed at a terminal within 30 seconds, or OPENSANDBOX_INSECURE_SERVER=YES.
publish_host. With it commented out, as in the packaged example, Docker publishes every sandbox's ports on 0.0.0.0. The example's own comment says what's at stake: "Set an IP to keep execd and the sandbox ports off public interfaces". In an earlier run, not in the video, docker ps showed 0.0.0.0:53476->44772/tcp for a sandbox: its execd command API on every network interface of my laptop. With publish_host = "127.0.0.1", the same ports bound to localhost and the SDK worked unchanged.
Step 3: Start the server
./00_server.sh
The script runs the server with uvx opensandbox-server@1.2.0 --config ./sandbox.toml, logs to server.log and waits for the health check:
image ready: opensandbox/execd:release-1.2.0
image ready: opensandbox/egress:release-1.2.0
image ready: python:3.12-slim
OpenSandbox server 1.2.0 ready at http://127.0.0.1:8080 (pid 28990, log: server.log)
In the recorded run, with the images already pulled, the script took 3.3 seconds, including the example diff. In an earlier run, curl http://127.0.0.1:8080/health answered {"status":"healthy"}. Running the script again only reports that the server is already up.
Testing
Test 1: A first sandbox from the Python SDK
The core of 01_first_sandbox.py, trimmed. The connection settings and the run() helper, which prints a command and its output and exit code, live in common.py:
sb = SandboxSync.create(
image=SandboxImageSpec(IMAGE), # python:3.12-slim
timeout=timedelta(minutes=10),
connection_config=connection(), # 127.0.0.1:8080, the API key from sandbox.toml
)
try:
run(sb, "uname -a")
run(sb, "python3 --version")
sb.files.write_files([WriteEntry(path="/tmp/hello.txt", data=text, mode=644)])
assert sb.files.read_file("/tmp/hello.txt") == text, "file content changed on the way"
m = sb.get_metrics()
finally:
sb.kill()
uv run python 01_first_sandbox.py
created sandbox 924dd5cb-9254-4c7c-91b7-51a1a98e5b5b from python:3.12-slim in 14.2 s
state: Running
$ uname -a
Linux 425375d63b8a 6.12.76-linuxkit #1 SMP Fri Mar 6 10:10:19 UTC 2026 aarch64 GNU/Linux
exit code: 0
$ python3 --version
Python 3.12.16
exit code: 0
file round trip: ok
metrics: 1 CPU, 0.0% used, 9 of 2048 MiB memory
killed
The create went to the server, the lifecycle path. Everything after it went straight to execd on a localhost port Docker published for the sandbox, the execution path, with the server out of the loop. The kernel line is Docker Desktop’s VM: under runc the sandbox shares the host kernel, which is the isolation you get by default. The API requires a size on every create; when you don’t pass one, the Python SDK asks for 1 CPU and 2 GiB.
The 14.2 seconds is the first create after a server start, and it’s not typical; the results table below has the spread. The server log says why. On the first create the server reads the execd image’s files into memory once (execd cache read archive, 8,278 ms in this run), and on every create it copies that archive into the new container. That copy took 4,660 ms on this first create and 3,253 and 3,117 ms on the next two (the CLI’s sandbox and the policy sandbox below): most of a warm create. Creating the container itself took 26 to 35 ms, and starting it 75 to 136 ms.
One thing I didn’t expect: every SDK create also sends a POST /v1/metrics/events with the create duration to the lifecycle server. It goes to your own server, not to a third party, and OPENSANDBOX_DISABLE_METRICS=1 turns it off.
Test 2: The same with the osb CLI
02_cli.sh drives the same server with the CLI, keeping its settings in a local osb.toml (the script passes --config ./osb.toml to every call):
osb config init
osb config set connection.domain 127.0.0.1:8080
osb config set connection.api_key local-dev-key
osb sandbox create --image python:3.12-slim --timeout 10m -o json
osb sandbox list
osb command run "$id" -- ls /
osb file write "$id" /tmp/hello.txt --content "hello from the cli"
osb file cat "$id" /tmp/hello.txt
osb sandbox metrics "$id"
osb sandbox kill "$id"
The recorded output of ./02_cli.sh, in a collapsed block. I cut the ls / listing with ..., and left out the progress spinners osb draws while it lists and kills, which the terminal erases:
CLI output
$ osb config set connection.domain 127.0.0.1:8080
✅ Set connection.domain = 127.0.0.1:8080
$ osb config set connection.api_key local-dev-key
✅ Set connection.api_key = local-dev-key
$ osb sandbox create --image python:3.12-slim --timeout 10m -o json
{
"id": "48254b07-8157-4a97-be9e-a49872f5e14c",
"status": "created",
"timeout": "0:10:00",
"image": "python:3.12-slim"
}
$ osb sandbox list
Sandboxes
╭──────────────────────────────────────┬───────────┬──────────────────┬─────────────────────────┬──────────────────────────╮
│ ID │ STATUS │ IMAGE │ CREATED_AT │ EXPIRES_AT │
├──────────────────────────────────────┼───────────┼──────────────────┼─────────────────────────┼──────────────────────────┤
│ 48254b07-8157-4a97-be9e-a49872f5e14c │ ● Running │ python:3.12-slim │ 2026-10-31T18:41:13.40… │ 2026-10-31T18:51:13.409… │
╰──────────────────────────────────────┴───────────┴──────────────────┴─────────────────────────┴──────────────────────────╯
$ osb command run 48254b07-8157-4a97-be9e-a49872f5e14c -- ls /
bin
boot
dev
...
usr
var
$ osb file write 48254b07-8157-4a97-be9e-a49872f5e14c /tmp/hello.txt --content "hello from the cli"
✅ Written: /tmp/hello.txt
$ osb file cat 48254b07-8157-4a97-be9e-a49872f5e14c /tmp/hello.txt
hello from the cli
$ osb sandbox metrics 48254b07-8157-4a97-be9e-a49872f5e14c
Sandbox Metrics
╭─────────────────────┬─────────────────────╮
│ Key │ Value │
├─────────────────────┼─────────────────────┤
│ cpu_count │ 1.0 │
├─────────────────────┼─────────────────────┤
│ cpu_used_percentage │ 0.05333413371682062 │
├─────────────────────┼─────────────────────┤
│ memory_total_in_mib │ 2048.0 │
├─────────────────────┼─────────────────────┤
│ memory_used_in_mib │ 7.1171875 │
├─────────────────────┼─────────────────────┤
│ timestamp │ 1793472078882 │
╰─────────────────────┴─────────────────────╯
$ osb sandbox kill 48254b07-8157-4a97-be9e-a49872f5e14c
Sandboxes
╭──────────────────────────────────────┬────────────────────╮
│ SANDBOX_ID │ STATUS │
├──────────────────────────────────────┼────────────────────┤
│ 48254b07-8157-4a97-be9e-a49872f5e14c │ deletion_requested │
╰──────────────────────────────────────┴────────────────────╯
$ osb sandbox list
ℹ️ No sandboxes found.
Same server, same results, and a few CLI habits worth knowing:
osb config setfails untilosb config inithas created the file.createreports"status": "created"whilelistalready shows the sandbox running.listreturns 20 rows a page by default, and its JSON uses snake_case (has_next_page) where the REST API uses camelCase (hasNextPage).- A command that fails inside the sandbox makes
osbexit 1; a wrong key prints a four-line panel withINVALID_API_KEYand a request ID.
The CLI also covers snapshots, templates, egress policy, the Credential Vault, diagnostics and an interactive terminal (osb terminal, new in 1.2.0). It has no commands for pools.
Test 3: A deny-by-default network policy
03_network_policy.py creates a sandbox that may reach pypi.org and nothing else, checks two hosts, then allows the second one while the sandbox runs (trimmed; the script names the hosts in constants):
sb = SandboxSync.create(
image=SandboxImageSpec(IMAGE),
timeout=timedelta(minutes=10),
network_policy=NetworkPolicy(
defaultAction="deny",
egress=[NetworkRule(action="allow", target="pypi.org")],
),
connection_config=connection(),
)
check(sb, "pypi.org", "200")
check(sb, "github.com", "blocked")
sb.patch_egress_rules([NetworkRule(action="allow", target="github.com")])
check(sb, "github.com", "200")
python:3.12-slim has no curl, and with egress denied nothing can be installed, so the script writes a short Python probe into the sandbox and runs it for each host. It exits 1 if any answer differs from the expected one.
created sandbox d9b9e966-c139-462f-9c1e-7aa49bd88312 in 5.1 s
policy before: default deny; allow pypi.org
pypi.org: 200
github.com: blocked
policy after: default deny; allow github.com, allow pypi.org
github.com: 200
killed
All three checks matched. A few things the run showed:
- The sidecar adds a container, and some create time (see the table). On the host there were now two containers,
sandbox-<id>andsandbox-egress-<id>, and the sandbox container ran in the sidecar’s network namespace (NetworkMode container:<sidecar>). In an earlier run,docker psshowed the sidecar carrying all the published ports: container ports 8080, 18080 and 44772, each on a random localhost port. - A blocked host looks like a DNS failure. Inside the sandbox, a denied name fails the way a missing domain does, with
socket.gaierror: [Errno -2] Name or service not known(the error an earlier run printed; the video shows onlyblocked), not a refused connection: the DNS layer answers first, and nftables would catch anything that dialed an IP directly. - A patch is immediate and merges.
patch_egress_rulesadded the rule at the top of the list, leftdefault denyalone, and the very next request went through. The patch didn’t go through the lifecycle server either: the SDK sent it straight to the sidecar’s API on port 18080, the same API the Credential Vault uses.
What the local runs showed
The middle column is the run in the video. The right column is the spread over every run I made on this Mac on October 31, 2026, including earlier runs that aren’t in the video.
| Step | In the video run | All runs |
|---|---|---|
| Server start, images already pulled | 3.3 s | 2.1 to 6.2 s (four runs), including the example diff |
| First create after a server start | 14.2 s | 12.5 to 15.4 s (seven starts) |
| Later create, no policy | 4.0 s through osb on screen, including the CLI’s own start-up | 3.5 to 4.1 s with the SDK, one run at 5.4 s (earlier runs); 4.0 to 4.8 s through osb (three takes) |
| Create with an egress policy | 5.1 s | 5.0 to 5.4 s |
| Kill from the SDK, no sidecar | 0.44 s | 0.25 to 0.44 s |
| Kill from the SDK, with a sidecar | 0.89 s | 0.86 to 1.0 s (three takes) |
| Default sandbox size (Python SDK) | 1 CPU, 2 GiB; 9 MiB used at rest (7 MiB in the CLI’s sandbox) | 1 CPU, 2 GiB; 6 to 9 MiB used at rest |
Allowed host (pypi.org) | 200, 0.45 s after the previous line | 0.44 to 0.53 s |
| Blocked host before the patch, then after | Fails 0.25 s after the previous line, then 200 | 0.25 to 0.27 s |
Images, as docker images reports them on arm64 | not shown | execd 185 MB, egress 573 MB, python:3.12-slim 384 MB (an earlier run) |
One more thing the run taught me: stopping the server doesn’t stop sandboxes. When I killed the server process, the sandbox containers kept running. So the cleanup script kills every sandbox through the API before it stops the server, then removes any container still carrying an opensandbox.io/id or opensandbox.io/egress-sidecar-for label:
./99_cleanup.sh
Verdict
The architecture holds together better than I expected for a project this young. One lifecycle API sits over Docker and Kubernetes, your images need nothing added because the platform injects execd when it creates a sandbox, and the egress sidecar turns “this sandbox can reach the internet” into a policy you can read and change at runtime. Locally, every test passed once I pinned the config. The packaged example pointing at images from before 1.2.0 was my first taste of how fast the project moves, and of what that speed costs.
What you sign up for
| Concern | OpenSandbox 1.2.0 as of October 31, 2026 |
|---|---|
| Governance | Announced as an AAIF project on October 22, 2026; LF Projects charter adopted October 20, 2026 |
| Who writes it | 175 contributors. Accounts with Alibaba in their GitHub company or email field wrote 56% of all commits and 48% in the last 13 weeks; one maintainer wrote about 36% of all commits and about 40% of the last 13 weeks. All four project maintainers have Alibaba in their company or email field |
| Pace | About 123 commits a week over the last 13 weeks; median time to close an issue, 3 days |
| Package names | npm @alibaba-group/opensandbox, Maven com.alibaba.opensandbox, NuGet Alibaba.OpenSandbox, Go module github.com/alibaba/OpenSandbox/... (#1134, open). The PyPI names are neutral |
| Releases | One version for every image, chart and SDK. The policy is a new line every two weeks with only the latest supported and no LTS; 1.1.0 to 1.2.0 took 36 days. Helm charts aren’t published: you render them from the git tag |
| API stability | /v1 paths, v1alpha1 CRDs, and a stable v1 API listed on the roadmap as “not currently planned” |
| Supply chain | The docs say releases are signed and attested; 1.1.0, 1.1.1 and 1.2.0 aren’t (#2463, open). No published security advisories. OpenSSF Best Practices Silver |
| Kubernetes | Supported v1.21 to v1.34, per the release BOM (the bill of materials that pins every image and package in a release). CI runs kind clusters only: 1.22.4 to 1.34.2 for the controller end-to-end tests, 1.30.4 for the fuller stack jobs. No managed cloud. This series runs EKS 1.37 |
| Where 1.2.0’s features land | Mostly the Fast Sandbox (Firecracker) profile: auto-pause and wake on access, a vault that survives pause, a pinned proxy CA. The BatchSandbox path got port-scoped egress rules and fixes |
| Community | GitHub: 590 issues from 211 authors. Three Hacker News submissions, none with a comment. Discord and DingTalk can’t be searched from outside |
| Adoption evidence | Self-reported: 25 comments on the “Who is using OpenSandbox” issue (#143), about 85% of them from China |
What I’d keep in mind before building on it:
- The standard Kubernetes path trails the microVM path. On BatchSandbox you get manual pause and resume, a vault that’s wiped on every pause, and no idle auto-pause. Fast Sandbox has those, behind a separate install (see the isolation menu). This series stays on BatchSandbox.
- Egress narrows the isolation menu to runc or Kata, and Kata needs KVM (see the isolation menu).
- The defaults were written for a different setup. Seven image references in the charts point at Alibaba’s registry in China, the gateway the docs call required is off in the umbrella chart, and the packaged Docker example is out of date. Part 2 is mostly about the gap between the defaults and EKS.
- The keys stay outside the sandbox, not outside the pod. The vault sidecar shares the pod with the code you don’t trust; parts 4 and 5 test how much that matters.
- Pin everything. One umbrella version, a new line planned every two weeks, and only the latest supported means you either upgrade on the project’s schedule or accept running something unsupported.
Who it suits
OpenSandbox fits a platform team that wants to run agent sandboxes on infrastructure it already owns, with network policy and credentials under its own control, and that’s comfortable treating GitHub issues as the support channel. The concepts are clean enough that the investment carries over even as the project moves.
It doesn’t fit yet for anyone who needs a long-term support line, signed releases for a compliance review, or a stable API contract, or who wants 1.2.0’s headline features without running Firecracker on dedicated KVM nodes. Part 2 takes everything above to Amazon EKS 1.37 and finds out where the defaults break.