Monday, November 16, 2026 Edition No. 240
Search
Review · Infrastructure · 45 min read

OpenSandbox Architecture: How the Pieces Fit Before You Deploy

By Fabio Douek

Jump to section
Explain (TLDR) like I am...
What is this?

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.

GitHub See the source code here: opensandbox-architecture

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.

CLIENT SURFACE SDKs in five languages Python · JavaScript/TypeScript · Java/Kotlin · C#/.NET · Go osb CLI sandbox · command · file · egress MCP server opensandbox-mcp · stdio or HTTP PROTOCOL SURFACE OpenAPI specs: lifecycle (/v1) · execd · egress · diagnostics LIFECYCLE CONTROL PLANE lifecycle server FastAPI · API key auth endpoints · optional proxy store SQLite or PostgreSQL snapshots, templates RUNTIME BACKENDS Dockerlocal or single host Kubernetescontroller and three CRDs Fast SandboxFirecracker microVMs, optional ingress gateway Kubernetes · shared proxy ONE SANDBOX execd :44772 commands · files · PTY · code · metrics workload your image and entrypoint egress sidecar only when the request has a networkPolicy DNS proxy nftables HTTPS proxy Credential Vault (in memory) OUTSIDE external APIs model providers package indexes web services lifecycle API delegates creates direct to execd: host port or pod IP server proxy lifecycle: create, pause, resume, renew, delete execution: commands, files, PTY, service ports outbound: from the sandbox, through the sidecar
OpenSandbox's six surfaces and three traffic paths, after the project's own architecture overview. Lifecycle and execution traffic come from the clients (an SDK, the CLI or the MCP server); outbound traffic starts inside the sandbox, and the server's proxy leg starts at the server. On Docker a sandbox is one container, plus a second for the egress sidecar; on Kubernetes it is one pod.
SurfaceWhat it isWhere it runs
ClientSDKs 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
ProtocolOpenAPI specs under specs/: the lifecycle API (base path /v1), the execd API, the egress API, diagnosticsContracts, not a process
Lifecycle control planeA FastAPI server: API keys, request validation, endpoint resolution, an optional proxy, a small storeOne process on Docker, one Deployment on Kubernetes
Runtime backendsDocker, or Kubernetes through a controller and three custom resources; optionally Fast Sandbox for Firecracker microVMsYour Docker host or your cluster
Sandbox data planeYour image plus execd on port 44772One container, or one pod
Network and securityIngress gateway, egress sidecar, Credential Vault, secure container runtimesOne 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 execd directly (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 to execd itself.
  • 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:

Pending Running Pausing Paused Stopping Resuming Terminated Failed created pause done kill or TTL kill, or the TTL expires cleaned up resume resumed on error
The eight states in the lifecycle API. Dashed outlines are terminal: a stopped or failed sandbox is never resumed. Dashed red lines are the transitions to Failed.

A few rules the names don’t tell you:

  • resume() only works from Paused. A sandbox whose workload exited ends in Terminated (exit code 0) or Failed (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 stays Running.
  • On Kubernetes, DELETE returns 204 and the sandbox reports Stopping until its pods are gone, then 404. That’s a 1.2.0 change, as is an expired BatchSandbox reporting Terminated with the reason SANDBOX_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:

MechanismWhat it doesLimits
timeout at createSets an absolute expiry, counted from creation. It isn’t an idle timeout, and server or runtime restarts don’t reset itAt 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-expirationSets a new absolute expiryCan shorten as well as extend; not capped by max_sandbox_timeout_seconds
Renew-on-accessTraffic 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 accessPauses an idle sandbox and wakes it on the next requestFast Sandbox only in 1.2.0
  • timeout is optional in the API: leave it out or send null and 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:

ObjectWhat it isFields 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 tasksreplicas, template or poolRef, expireTime, pause, taskTemplate
PoolWarm, ready pods that a sandbox can claim instead of waiting for a cold starttemplate, capacitySpec (bufferMin, bufferMax, poolMin, poolMax), recycleStrategy (Delete, Restart or Noop)
SandboxSnapshotOne root-filesystem commit of a sandbox, run as a Job on the sandbox’s node and pushed to an OCI registrysandboxName; 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 BatchSandbox can also run tasks, commands the controller starts inside its pods, and it has its own phase list: Succeed means “the pod is ready”, not “the task finished”.
  • Pool recycling is a trade-off you choose. Delete, the default, deletes a used pod; Noop hands the next sandbox the previous one’s files and processes. A sandbox drawn from a pool can’t take volumes or a networkPolicy, 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 sectionWhat it controlsHow it’s set on Kubernetes
[server]Bind address and port, api_key, max_sandbox_timeout_secondsconfigToml (port 80 in the chart); the key from a Secret through server.env as OPENSANDBOX_SERVER_API_KEY
[runtime]type (docker or kubernetes), execd_imageconfigToml
[docker]Network mode, host port range, publish_host, dropped capabilities, pids_limitDocker only
[kubernetes]Sandbox namespace, BatchSandbox template file, sandbox_create_timeout_seconds (60 by default), API rate limitsconfigToml; 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 tokensGenerated 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 limitsconfigToml
[store]SQLite path or PostgreSQLconfigToml; the DSN through OPENSANDBOX_STORE_POSTGRESQL_DSN
[secure_runtime]runc, gVisor, Kata or Kata with Firecracker, and the RuntimeClass to useconfigToml
[tenants]Multi-tenant API keys from a tenants.toml fileconfigToml, 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:

  1. 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 gets NXDOMAIN; an allowed name resolves and its addresses are recorded. On its own this is dns mode, which gates names only. A process that connects to an IP directly isn’t stopped.
  2. nftables, in dns+nft mode. 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.
  3. 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 sets SSL_CERT_FILE, REQUESTS_CA_BUNDLE and NODE_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:

trusted client your code, outside the sandbox ONE SANDBOX · SHARED NETWORK NAMESPACE workload no NET_ADMIN placeholder token in env trusts the sidecar's CA EGRESS SIDECAR · NET_ADMIN DNS proxy :15353 denied names: NXDOMAIN HTTPS proxy :18081 80 and 443 redirected here TLS with the sidecar's CA injects the matching binding Credential Vault API :18080 · token real values, in memory nftables (dns+nft) drops every packet to an IP that isn't allowed or leased UPSTREAM allowed host gets the real header response headers redacted 1 write the vault 2 3 4 5 6
One HTTPS request through the egress sidecar with the Credential Vault on. Blue is the trusted side writing the vault; green is the request leaving the sandbox.
  1. 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.
  2. The workload looks up the host. The DNS proxy answers only for allowed names and leases the addresses into nftables’ allow sets.
  3. 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.
  4. 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.
  5. The proxy opens its own connection upstream, and nftables polices that connection like any other.
  6. 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] typeWhat the nodes needWith egress and the vault
runc"" (the default)Nothing extraWorks (Test 3 below runs it on Docker)
gVisorgvisorrunsc and containerd-shim-runsc-v1 on every node, a RuntimeClassRejected with HTTP 400
Kata (QEMU or Cloud Hypervisor)kataKVM: bare metal, or nested virtualization that exposes /dev/kvm; kata-deploy for the RuntimeClassesSupported per the docs; part 2 tries it
Kata with Firecrackerfirecracker (Kubernetes only, RuntimeClass required)KVM, as aboveAllowed by the server; not tried in this series
Fast SandboxNot a runtime type: chosen per request with templateIdA 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, amd64One 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 nat table, 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 .metal instance. 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/kvm and 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:

ContainerKindWhat it doesPrivileges
execd-installerInit container, from execd_imageCopies execd, bootstrap.sh and helpers into an emptyDir mounted at /opt/opensandboxprivileged when the sandbox has a network policy and disable_ipv6 is on (the default), to write the IPv6 sysctl
sandboxMain container, your imageRuns /opt/opensandbox/bootstrap.sh and then your entrypoint; bootstrap starts execd on 44772 and installs the proxy CA when there is oneNET_ADMIN dropped when there is a policy
egressSidecar, only with a networkPolicyDNS proxy, nftables, the optional HTTPS proxy and the vault; API on 18080Adds 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
FileWhat it does
sandbox.tomlThe server config: the packaged Docker example with seven lines changed
common.pyConnection settings (OSB_DOMAIN, OSB_API_KEY) and the helpers the Python scripts share
00_server.shShows where the packaged example is stale, pulls the images, starts the server and waits for /health
01_first_sandbox.pyPython SDK: create a sandbox, run commands, write and read a file, read metrics, kill it
02_cli.shThe same through osb
03_network_policy.pyA deny-by-default policy, one host allowed at creation and a second allowed while the sandbox runs
99_cleanup.shKills 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.

⚠️ Set 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 set fails until osb config init has created the file.
  • create reports "status": "created" while list already shows the sandbox running.
  • list returns 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 osb exit 1; a wrong key prints a four-line panel with INVALID_API_KEY and 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> and sandbox-egress-<id>, and the sandbox container ran in the sidecar’s network namespace (NetworkMode container:<sidecar>). In an earlier run, docker ps showed 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 only blocked), 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_rules added the rule at the top of the list, left default deny alone, 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.

StepIn the video runAll runs
Server start, images already pulled3.3 s2.1 to 6.2 s (four runs), including the example diff
First create after a server start14.2 s12.5 to 15.4 s (seven starts)
Later create, no policy4.0 s through osb on screen, including the CLI’s own start-up3.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 policy5.1 s5.0 to 5.4 s
Kill from the SDK, no sidecar0.44 s0.25 to 0.44 s
Kill from the SDK, with a sidecar0.89 s0.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 line0.44 to 0.53 s
Blocked host before the patch, then afterFails 0.25 s after the previous line, then 2000.25 to 0.27 s
Images, as docker images reports them on arm64not shownexecd 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

ConcernOpenSandbox 1.2.0 as of October 31, 2026
GovernanceAnnounced as an AAIF project on October 22, 2026; LF Projects charter adopted October 20, 2026
Who writes it175 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
PaceAbout 123 commits a week over the last 13 weeks; median time to close an issue, 3 days
Package namesnpm @alibaba-group/opensandbox, Maven com.alibaba.opensandbox, NuGet Alibaba.OpenSandbox, Go module github.com/alibaba/OpenSandbox/... (#1134, open). The PyPI names are neutral
ReleasesOne 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 chainThe 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
KubernetesSupported 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 landMostly 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
CommunityGitHub: 590 issues from 211 authors. Three Hacker News submissions, none with a comment. Discord and DingTalk can’t be searched from outside
Adoption evidenceSelf-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.

Comments