Sandbox strategy: OpenSandbox
Status: Accepted
Sandbox strategy: OpenSandbox
Section titled “Sandbox strategy: OpenSandbox”Decision
Section titled “Decision”Adopt the OpenSandbox spec as the sandbox standard. Run a rolling fork (sharpi/opensandbox) with the strategy: contribute upstream, ship before approval.
The spec
Section titled “The spec”OpenSandbox defines agent sandboxing through 3 OpenAPI specs:
| Spec | Purpose |
|---|---|
| Lifecycle | Create, start, stop, destroy sandbox instances. Image management. |
| Execd | Execute commands inside running sandboxes. Stdin/stdout/stderr streaming. |
| Egress | Network policy: allowlists, denylists, domain-level filtering. |
Any runtime that implements these 3 specs is a valid sandbox backend. The specs are backend-agnostic — gVisor, Kata, Firecracker, and Apple Container all implement the same API.
Our contributions
Section titled “Our contributions”The rolling fork adds four features that don’t exist upstream:
| Contribution | Purpose |
|---|---|
| Apple Container backend | Native macOS sandbox using Apple’s Virtualization.framework. Enables sandbox mode on developer Macs without Docker. |
| Credential proxy | Secrets never enter the sandbox directly. The proxy sits between the IAM provider and the sandbox, injecting secrets into an isolated namespace with per-access audit logging. |
| Policy engine | Template-driven egress rules. Egress inferred from capabilities + [overrides].egress compiled into sandbox network policy. |
| Go SDK | Client library for the 3 OpenAPI specs. Used by cli/internal/sandbox/ to drive sandbox lifecycle from arpi spawn. |
Rolling fork strategy
Section titled “Rolling fork strategy”- Develop features in
sharpi/opensandboxfork. - Ship internally immediately — do not wait for upstream approval.
- Submit upstream PRs for each contribution.
- Rebase on upstream releases. If a contribution is accepted upstream, drop our fork’s version.
- If upstream diverges incompatibly, maintain the fork.
What was rejected
Section titled “What was rejected”Docker Sandboxes — Docker’s proprietary sandbox API. No open spec, no backend pluggability, vendor lock to Docker runtime. OpenSandbox achieves the same isolation with an open spec and multiple backends.
Where it lives
Section titled “Where it lives”OpenSandbox is consumed by the Compute domain (see template-schema.md). The control plane calls the OpenSandbox API through the SandboxProvider interface when a template’s [compute] section requests a sandbox.
Agent sandboxing needs a spec, not a product. Without a spec:
- You’re locked to one vendor’s runtime.
- You can’t swap backends (gVisor locally, Firecracker in prod).
- You can’t contribute isolation improvements to an ecosystem.
OpenSandbox is Apache 2.0, spec-first, and already has multiple backend implementations. Our Apple Container backend contribution makes it usable on macOS — the primary developer platform.
Current Status
Section titled “Current Status”Updated 2026-03-27
The sandbox strategy is accepted but partially implemented. Docker Go SDK is the v1 sandbox backend and is production-ready for container lifecycle management. The OpenSandbox spec remains the target architecture, but the Go SDK is not yet available (expected Q1 2026 on the OpenSandbox roadmap — still pending).
| Contribution | Status |
|---|---|
| Apple Container backend | DEFERRED — requires macOS 26+ (Apple Containerization framework is pre-1.0, Swift-native, no Go SDK). Revisit when macOS 26 ships. |
| Credential proxy | DEFERRED — blocked on OpenSandbox fork. Currently secrets are injected via infisical run environment variables in sandbox mode. |
| Policy engine | DEFERRED — depends on OpenSandbox egress spec. |
| Go SDK | DEFERRED — OpenSandbox upstream has not shipped a Go SDK yet. CLI shells out to Docker SDK for container lifecycle. |
The opensandbox/ git submodule does not yet exist. The environments/ domain described in this ADR has not been built — execution environment config currently lives in infra/.
Verification criteria status
Section titled “Verification criteria status”| Criterion | Status |
|---|---|
arpi spawn in sandbox mode calls OpenSandbox lifecycle API | DEFERRED — uses Docker Go SDK |
| Apple Container backend works on macOS without Docker | DEFERRED — macOS 26+ |
| Credential proxy injects secrets without container env dump | DEFERRED — uses env var injection |
| Egress policy compiled from definition | DEFERRED — no policy engine yet |
| Go SDK covers all 3 OpenAPI specs | DEFERRED — no upstream Go SDK |
| Fork rebases cleanly on upstream releases | DEFERRED — no fork created yet |
Verification
Section titled “Verification”arpi spawnin sandbox mode calls OpenSandbox lifecycle API, not Docker CLI- Apple Container backend works on macOS without Docker installed
- Credential proxy injects secrets without them appearing in container env dump
- Egress policy compiled from definition blocks all non-gateway traffic
- Go SDK covers all 3 OpenAPI specs with typed client
- Fork rebases cleanly on upstream releases