The Problem

AI applications require secure, isolated execution environments for code generation, testing, and agent operations. Existing solutions either lack multi-language SDK support, impose rigid runtime constraints, or fail to provide unified network policies and credential injection mechanisms needed for production AI workflows. The fragmentation across runtimes forces engineers to maintain custom sandbox orchestration rather than focusing on agent logic.

What This Does

OpenSandbox is a portfolio of seven projects spanning SDKs, runtimes, and platform integrations. The sdks/ directory (790 files) provides multi-language client libraries for sandbox creation and command execution. The components/ layer (429 files) implements core services: egress/ manages outbound network policy and credential vaulting, execd/ handles sandbox lifecycle and process execution, and ingress/ routes inbound requests via configurable strategies. Kubernetes definitions under kubernetes/ (309 files) enable distributed scheduling, while the server/ (197 files) exposes HTTP APIs for sandbox provisioning. Example workloads in examples/ cover Chrome automation, coding agents, and desktop VNC environments. The cli/ (51 files) provides a osb command-line tool for sandbox operations.

Execution originates at components/egress/main.go:44 (reaches 360 functions, entry point with no callers in the repo) and components/execd/main.go:58 (reaches 205 functions, called from one place). Traced paths show main -> run -> WaitForReady [subprocess via cmd.Run] for process lifecycle, and Start -> New -> Capabilities -> Available -> openSessionGate -> openSessionGatePath [filesystem via unix.Open] for session setup. The credential vault at components/egress/pkg/credentialvault/vault.go (53 functions, 22 classes, called from 25 others) manages secure secret injection without exposing keys to sandbox workloads. Network policy enforcement flows through components/egress/pkg/dnsproxy/proxy.go (30 functions, called from 57 others) which implements policy refresh and upstream routing.

How It Is Wired

The internal call graph resolves 6000 edges between self-contained functions. Hub modules with high blast radius include sdks/sandbox/python/src/opensandbox/api/execd/types (Ca 73, Ce 0, instability 0) — 73 modules depend on this type definition, making it a high-impact change point. sdks/sandbox/python/src/opensandbox/api/execd/__init__ (Ca 51, Ce 1, instability 0.02) similarly sees heavy dependency. Deep nesting appears in sdks/sandbox/javascript/src/api/egress.ts and kubernetes/internal/controller/pool_static_volume_test.go (max indentation depth 6). Duplicated 6-line blocks number 952 across 782 files, primarily in SDK configuration files. Empty catch blocks in tests/javascript/tests/test_code_interpreter_e2e.test.ts silently discard errors. File handles opened without context managers leak in server/tests/test_docker_runtime_bootstrap.py, server/opensandbox_server/services/docker/windows_profile.py, and server/opensandbox_server/services/docker/ossfs_mixin.py.

How To Use It

The repository provides seven distinct projects; no single install command spans all components. The CLI at cli/ uses pyproject.toml with pnpm dependencies and can be installed via pnpm install followed by pnpm run build. Docker images for egress and execd components are defined in components/egress/Dockerfile and components/execd/Dockerfile, built from Go modules in their respective go.dir directories. Kubernetes manifests under kubernetes/ enable cluster-scale deployment. Environment configuration is not pinned in the analyzed data; the repo references no .env files or typed config structures beyond YAML manifests. Entry points include the CLI script cli/src/opensandbox_cli/__main__.py for local sandbox operations and components/egress/main.go for the egress gateway.

Real-World Use

An AI coding agent needing temporary execution environments can use the Python SDK at sdks/sandbox/python/src/opensandbox/ to create an isolated session, write files to the sandbox filesystem, and execute commands via the execd runtime. The credential vault injects outbound API keys without persisting them in container layers. Network egress is governed by policies defined in components/egress/, routing through the dnsproxy for DNS-level filtering. For Kubernetes-deployed agents, the kubernetes/internal/controller/ manifests schedule sandboxes across node pools with gVisor or Kata Containers isolation. File operations flow through components/execd/pkg/isolation/merged_view.go which defines NewMergedView, resolveUpper, resolveLower, and safePath to enforce path containment.

Code Health & Issues

  • HIGH - Pin third-party GitHub Actions to commit SHAs: .github/workflows uses @v3 tags for docker/setup-qemu-action, docker/setup-buildx-action, sigstore/cosign-installer, and docker/login-action; tags can shift, causing unpredictable action versions with repository secrets.
  • HIGH - Publish via pull request, not direct push: .github/workflows/publish-components.yml pushes with git origin "$BRANCH"; automated commits deploy without CI validation.
  • MEDIUM - Enable Dependabot/Renovate: 17 manifest files have no update bot configured; published advisories remain unpatched.
  • MEDIUM - Pin container base images by digest: components/egress/Dockerfile uses golang:1.25.9-bookworm and debian:bookworm-slim without digest pins, allowing base image drift.
  • MEDIUM - Gate PRs on dependency vulnerability scans: no dependency-review-action or osv-scanner in CI pipeline.
  • MEDIUM - Move large binaries to Git LFS: docs/public/images/deploy-example.gif (23.5MB) and process_executor.png (5.6MB) inflate clone sizes.
  • MEDIUM - Add non-root USER to egress Docker image: components/egress/Dockerfile has no USER directive; processes run as root.
  • LOW - Set workflow job timeouts: .github/workflows/publish-components.yml declares no timeout-minutes on three jobs.

The Bottom Line

OpenSandbox delivers a capable, multi-runtime sandbox platform with genuine utility for AI agent isolation, credential management, and Kubernetes-scale scheduling. The codebase is structurally sound with 2144 files, comprehensive test coverage (574 test files), and clear separation across seven projects. However, the action-tag pinning, direct-publish workflow, and mutable base images represent concrete production risks. Teams needing secure, language-agnostic sandbox execution will find real value here, particularly those already invested in Kubernetes or multi-agent orchestration. Those requiring out-of-the-box CI/CD hygiene or minimal base-image surface area should supplement with additional hardening.