{"id":34533214,"url":"https://github.com/alibaba/opensandbox","last_synced_at":"2026-04-25T09:09:02.206Z","repository":{"id":329106293,"uuid":"1118085970","full_name":"alibaba/OpenSandbox","owner":"alibaba","description":"Secure, Fast, and Extensible Sandbox runtime for AI agents.","archived":false,"fork":false,"pushed_at":"2026-04-07T07:59:31.000Z","size":84813,"stargazers_count":9793,"open_issues_count":79,"forks_count":759,"subscribers_count":41,"default_branch":"main","last_synced_at":"2026-04-07T08:31:22.727Z","etag":null,"topics":["ai","ai-agent","ai-infra","kubernetes","sandbox"],"latest_commit_sha":null,"homepage":"https://open-sandbox.ai","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alibaba.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-17T08:41:09.000Z","updated_at":"2026-04-07T08:12:06.000Z","dependencies_parsed_at":"2026-04-02T07:08:17.073Z","dependency_job_id":null,"html_url":"https://github.com/alibaba/OpenSandbox","commit_stats":null,"previous_names":["alibaba/opensandbox"],"tags_count":84,"template":false,"template_full_name":null,"purl":"pkg:github/alibaba/OpenSandbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alibaba%2FOpenSandbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alibaba%2FOpenSandbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alibaba%2FOpenSandbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alibaba%2FOpenSandbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alibaba","download_url":"https://codeload.github.com/alibaba/OpenSandbox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alibaba%2FOpenSandbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31782740,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T02:24:21.117Z","status":"ssl_error","status_checked_at":"2026-04-14T02:24:20.627Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agent","ai-infra","kubernetes","sandbox"],"created_at":"2025-12-24T05:53:59.259Z","updated_at":"2026-04-25T09:09:02.192Z","avatar_url":"https://github.com/alibaba.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/logo.svg\" alt=\"OpenSandbox logo\" width=\"150\" /\u003e\n\n  \u003ch1\u003eOpenSandbox\u003c/h1\u003e\n\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"https://trendshift.io/repositories/21828\" target=\"_blank\"\u003e\n      \u003cimg src=\"https://trendshift.io/api/badge/repositories/21828\" alt=\"alibaba%2FOpenSandbox | Trendshift\" style=\"width: 320px; height: 70px;\" width=\"320\" height=\"70\" /\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/alibaba/OpenSandbox\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/stars/alibaba/OpenSandbox.svg?style=social\" alt=\"GitHub stars\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://deepwiki.com/alibaba/OpenSandbox\"\u003e\n    \u003cimg src=\"https://deepwiki.com/badge.svg\" alt=\"Ask DeepWiki\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.apache.org/licenses/LICENSE-2.0.html\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-Apache%202.0-blue.svg\" alt=\"license\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://badge.fury.io/py/opensandbox\"\u003e\n    \u003cimg src=\"https://badge.fury.io/py/opensandbox.svg\" alt=\"PyPI version\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://badge.fury.io/js/@alibaba-group%2Fopensandbox\"\u003e\n    \u003cimg src=\"https://badge.fury.io/js/@alibaba-group%2Fopensandbox.svg\" alt=\"npm version\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://landscape.cncf.io/?item=orchestration-management--scheduling-orchestration--opensandbox\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/CNCF-Landscape-0C66E4\" alt=\"CNCF Landscape\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://qr.dingtalk.com/action/joingroup?code=v1,k1,A4Bgl5q1I1eNU/r33D18YFNrMY108aFF38V+r19RJOM=\u0026_dt_no_comment=1\u0026origin=11\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/DingTalk-Join-0089FF?logo=dingtalk\u0026logoColor=white\" alt=\"DingTalk\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/alibaba/OpenSandbox/actions\"\u003e\n    \u003cimg src=\"https://github.com/alibaba/OpenSandbox/actions/workflows/real-e2e.yml/badge.svg?branch=main\" alt=\"E2E Status\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/alibaba/OpenSandbox/actions\"\u003e\n    \u003cimg src=\"https://github.com/alibaba/OpenSandbox/actions/workflows/kubernetes-nightly-build.yml/badge.svg?branch=main\" alt=\"E2E Status\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n  \u003chr /\u003e\n\u003c/div\u003e\n\n[Documentation](https://open-sandbox.ai/) | [中文文档](https://open-sandbox.ai/zh/)\n\nOpenSandbox is a **general-purpose sandbox platform** for AI applications, offering multi-language SDKs, unified sandbox APIs, and Docker/Kubernetes runtimes for scenarios like Coding Agents, GUI Agents, Agent Evaluation, AI Code Execution, and RL Training.\n\nOpenSandbox is now listed in the [CNCF Landscape](https://landscape.cncf.io/?item=orchestration-management--scheduling-orchestration--opensandbox).\n\n## Features\n\n- **Multi-language SDKs**: Provides sandbox SDKs in Python, Java/Kotlin, JavaScript/TypeScript, C#/.NET, Go.\n- **Sandbox Protocol**: Defines sandbox lifecycle management APIs and sandbox execution APIs so you can extend custom sandbox runtimes.\n- **Sandbox Runtime**: Built-in lifecycle management supporting Docker and [high-performance Kubernetes runtime](./kubernetes), enabling both local runs and large-scale distributed scheduling.\n- **Sandbox Environments**: Built-in Command, Filesystem, and Code Interpreter implementations. Examples cover Coding Agents (e.g., Claude Code), browser automation (Chrome, Playwright), and desktop environments (VNC, VS Code).\n- **Network Policy**: Unified [Ingress Gateway](components/ingress) with multiple routing strategies plus per-sandbox [egress controls](components/egress).\n- **Strong Isolation**: Supports secure container runtimes like gVisor, Kata Containers, and Firecracker microVM for enhanced isolation between sandbox workloads and the host. See [Secure Container Runtime Guide](docs/secure-container.md) for details.\n\n## SDKs\n\nPython:\n\n```bash\npip install opensandbox\n```\n\nJava/Kotlin (Gradle Kotlin DSL):\n\n```kotlin\ndependencies {\n    implementation(\"com.alibaba.opensandbox:sandbox:{latest_version}\")\n}\n```\n\nJava/Kotlin (Maven):\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.alibaba.opensandbox\u003c/groupId\u003e\n    \u003cartifactId\u003esandbox\u003c/artifactId\u003e\n    \u003cversion\u003e{latest_version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nJavaScript/TypeScript:\n\n```bash\nnpm install @alibaba-group/opensandbox\n```\n\nC#/.NET:\n\n```bash\ndotnet add package Alibaba.OpenSandbox\n```\n\nGo:\n\n```bash\ngo get github.com/alibaba/OpenSandbox/sdks/sandbox/go\n```\n\n## CLI\n\nOpenSandbox also provides `osb`, a terminal CLI for the common sandbox workflow: create sandboxes, run commands, move files, inspect diagnostics, and manage runtime egress policy.\n\nInstall:\n\n```bash\npip install opensandbox-cli\n# or\nuv tool install opensandbox-cli\n```\n\nQuick start:\n\n```bash\nosb config init\nosb config set connection.domain localhost:8080\nosb config set connection.protocol http\nosb sandbox create --image python:3.12 --timeout 30m -o json\nosb command run \u003csandbox-id\u003e -o raw -- python -c \"print(1 + 1)\"\n```\n\nSee the [CLI README](cli/README.md) for the full command reference.\n\n## MCP\n\nThe OpenSandbox MCP server exposes sandbox creation, command execution, and text file operations to MCP-capable clients such as Claude Code and Cursor.\n\nInstall and run:\n\n```bash\npip install opensandbox-mcp\nopensandbox-mcp --domain localhost:8080 --protocol http\n```\n\nMinimal stdio config:\n\n```json\n{\n  \"mcpServers\": {\n    \"opensandbox\": {\n      \"command\": \"opensandbox-mcp\",\n      \"args\": [\"--domain\", \"localhost:8080\", \"--protocol\", \"http\"]\n    }\n  }\n}\n```\n\nSee the [MCP README](sdks/mcp/sandbox/python/README.md) for client-specific setup.\n\n## Getting Started\n\nRequirements:\n\n- Docker (required for local execution)\n- Python 3.10+ (required for examples and local runtime)\n\n### Install and Configure the Sandbox Server\n\n```bash\nuvx opensandbox-server init-config ~/.sandbox.toml --example docker\n\nuvx opensandbox-server\n\n# Show help\n# uvx opensandbox-server -h\n```\n\n### Create a Code Interpreter and Execute Commands/Codes\n\nInstall the Code Interpreter SDK\n\n```bash\nuv pip install opensandbox-code-interpreter\n```\n\nCreate a sandbox and execute commands and codes.\n\n```python\nimport asyncio\nfrom datetime import timedelta\n\nfrom code_interpreter import CodeInterpreter, SupportedLanguage\nfrom opensandbox import Sandbox\nfrom opensandbox.models import WriteEntry\n\nasync def main() -\u003e None:\n    # 1. Create a sandbox\n    sandbox = await Sandbox.create(\n        \"opensandbox/code-interpreter:v1.0.2\",\n        entrypoint=[\"/opt/opensandbox/code-interpreter.sh\"],\n        env={\"PYTHON_VERSION\": \"3.11\"},\n        timeout=timedelta(minutes=10),\n    )\n\n    async with sandbox:\n\n        # 2. Execute a shell command\n        execution = await sandbox.commands.run(\"echo 'Hello OpenSandbox!'\")\n        print(execution.logs.stdout[0].text)\n\n        # 3. Write a file\n        await sandbox.files.write_files([\n            WriteEntry(path=\"/tmp/hello.txt\", data=\"Hello World\", mode=644)\n        ])\n\n        # 4. Read a file\n        content = await sandbox.files.read_file(\"/tmp/hello.txt\")\n        print(f\"Content: {content}\") # Content: Hello World\n\n        # 5. Create a code interpreter\n        interpreter = await CodeInterpreter.create(sandbox)\n\n        # 6. Execute Python code (single-run, pass language directly)\n        result = await interpreter.codes.run(\n              \"\"\"\n                  import sys\n                  print(sys.version)\n                  result = 2 + 2\n                  result\n              \"\"\",\n              language=SupportedLanguage.PYTHON,\n        )\n\n        print(result.result[0].text) # 4\n        print(result.logs.stdout[0].text) # 3.11.14\n\n    # 7. Cleanup the sandbox\n    await sandbox.kill()\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n### More Examples\n\nOpenSandbox provides examples covering SDK usage, agent integrations, browser automation, and training workloads. All example code is located in the `examples/` directory.\n\n#### 🎯 Basic Examples\n\n- **[code-interpreter](examples/code-interpreter/README.md)** - End-to-end Code Interpreter SDK workflow in a sandbox.\n- **[aio-sandbox](examples/aio-sandbox/README.md)** - All-in-One sandbox setup using the OpenSandbox SDK.\n- **[agent-sandbox](examples/agent-sandbox/README.md)** - Example integration for running OpenSandbox workloads on Kubernetes with [kubernetes-sigs/agent-sandbox](https://github.com/kubernetes-sigs/agent-sandbox).\n- **Volumes** — [Docker PVC / named volumes](examples/docker-pvc-volume-mount/README.md), [Docker OSSFS](examples/docker-ossfs-volume-mount/README.md), [Kubernetes PVC](examples/kubernetes-pvc-volume-mount/README.md): persistent and shared storage patterns.\n\n#### 🤖 Coding Agent Integrations\n\n- **Coding CLIs** — [Claude Code](examples/claude-code/README.md), [Gemini CLI](examples/gemini-cli/README.md), [OpenAI Codex CLI](examples/codex-cli/README.md), [Qwen Code](examples/qwen-code/README.md), [Kimi CLI](examples/kimi-cli/README.md): run each vendor CLI inside OpenSandbox.\n- **[langgraph](examples/langgraph/README.md)** - LangGraph state-machine workflow that creates/runs a sandbox job with fallback retry.\n- **[google-adk](examples/google-adk/README.md)** - Google ADK agent using OpenSandbox tools to write/read files and run commands.\n- **[openclaw](examples/openclaw/README.md)** - Launch an OpenClaw Gateway inside a sandbox.\n\n#### 🌐 Browser and Desktop Environments\n\n- **[chrome](examples/chrome/README.md)** - Chromium sandbox with VNC and DevTools access for automation and debugging.\n- **[playwright](examples/playwright/README.md)** - Playwright + Chromium headless scraping and testing example.\n- **[desktop](examples/desktop/README.md)** - Full desktop environment in a sandbox with VNC access.\n- **[vscode](examples/vscode/README.md)** - code-server (VS Code Web) running inside a sandbox for remote dev.\n\n#### 🧠 ML and Training\n\n- **[rl-training](examples/rl-training/README.md)** - DQN CartPole training in a sandbox with checkpoints and summary output.\n\nFor more details, please refer to [examples](examples/README.md) and the README files in each example directory.\n\n## Project Structure\n\n| Directory | Description                                                      |\n|-----------|------------------------------------------------------------------|\n| [`sdks/`](sdks/) | Multi-language SDKs (Python, Java/Kotlin, TypeScript/JavaScript, C#/.NET) |\n| [`specs/`](specs/README.md) | OpenAPI specs and lifecycle specifications                      |\n| [`server/`](server/README.md) | Python FastAPI sandbox lifecycle server                          |\n| [`cli/`](cli/README.md) | OpenSandbox command-line interface                               |\n| [`kubernetes/`](kubernetes/README.md) | Kubernetes deployment and examples                               |\n| [`components/execd/`](components/execd/README.md) | Sandbox execution daemon (commands and file operations)          |\n| [`components/ingress/`](components/ingress/README.md) | Sandbox traffic ingress proxy                                    |\n| [`components/egress/`](components/egress/README.md) | Sandbox network egress control                                   |\n| [`sandboxes/`](sandboxes/) | Runtime sandbox implementations                                   |\n| [`examples/`](examples/README.md) | Integration examples and use cases                               |\n| [`oseps/`](oseps/README.md) | OpenSandbox Enhancement Proposals                                |\n| [`docs/`](docs/) | Architecture and design documentation                            |\n| [`tests/`](tests/) | Cross-component E2E tests                                        |\n| [`scripts/`](scripts/) | Development and maintenance scripts                              |\n\nFor detailed architecture, see [docs/architecture.md](docs/architecture.md).\n\n## Documentation\n\n- [docs/architecture.md](docs/architecture.md) – Overall architecture \u0026 design philosophy\n- [oseps/README.md](oseps/README.md) – OpenSandbox Enhancement Proposals\n- SDK\n  - Sandbox base SDK ([Java/Kotlin SDK](sdks/sandbox/kotlin/README.md), [Python SDK](sdks/sandbox/python/README.md), [JavaScript/TypeScript SDK](sdks/sandbox/javascript/README.md), [C#/.NET SDK](sdks/sandbox/csharp/README.md)), [Go SDK](sdks/sandbox/go/README.md) - includes sandbox lifecycle, command execution, file operations\n  - Code Interpreter SDK ([Java/Kotlin SDK](sdks/code-interpreter/kotlin/README.md), [Python SDK](sdks/code-interpreter/python/README.md), [JavaScript/TypeScript SDK](sdks/code-interpreter/javascript/README.md), [C#/.NET SDK](sdks/code-interpreter/csharp/README.md)) - code interpreter\n- [cli/README.md](cli/README.md) - OpenSandbox CLI installation and command reference\n- [sdks/mcp/sandbox/python/README.md](sdks/mcp/sandbox/python/README.md) - MCP server installation and client setup\n- [specs/README.md](specs/README.md) - OpenAPI definitions for sandbox lifecycle API and sandbox execution API\n- [server/README.md](server/README.md) - Sandbox server startup and configuration; supports Docker and Kubernetes runtimes\n\n## License\n\nThis project is open source under the [Apache 2.0 License](LICENSE).\n\n## Roadmap [2026.03]\n\n### SDK\n\n- [x] **Sandbox client connection pool** - Client-side sandbox connection pool management, providing pre-provisioned sandboxes to obtain an environment at X ms. Implemented for Kotlin `SandboxPool` and documented in the [Kotlin SDK README](sdks/sandbox/kotlin/README.md#6-sandbox-pool-client-side). Related PRs: [#301](https://github.com/alibaba/OpenSandbox/pull/301), [#393](https://github.com/alibaba/OpenSandbox/pull/393), [#617](https://github.com/alibaba/OpenSandbox/pull/617).\n- [x] **Go SDK** - Go client SDK for sandbox lifecycle management, command execution, and file operations. See the [Go SDK README](sdks/sandbox/go/README.md). Related PRs: [#597](https://github.com/alibaba/OpenSandbox/pull/597), [#683](https://github.com/alibaba/OpenSandbox/pull/683), [#707](https://github.com/alibaba/OpenSandbox/pull/707).\n\n### Sandbox Runtime\n\n- [x] **Persistent volumes** - Mountable persistent volumes for sandboxes. See [Proposal 0003](oseps/0003-volume-and-volumebinding-support.md), [Docker PVC / named volumes](examples/docker-pvc-volume-mount/README.md), [Docker OSSFS](examples/docker-ossfs-volume-mount/README.md), and [Kubernetes PVC](examples/kubernetes-pvc-volume-mount/README.md). Related PRs: [#166](https://github.com/alibaba/OpenSandbox/pull/166), [#233](https://github.com/alibaba/OpenSandbox/pull/233), [#424](https://github.com/alibaba/OpenSandbox/pull/424), [#515](https://github.com/alibaba/OpenSandbox/pull/515), [#563](https://github.com/alibaba/OpenSandbox/pull/563).\n- [ ] **Local lightweight sandbox** - Lightweight sandbox for AI tools running directly on PCs.\n- [x] **Secure Container** - Secure sandbox for AI Agents running inside container. See the [Secure Container Runtime Guide](docs/secure-container.md). Related PRs: [#177](https://github.com/alibaba/OpenSandbox/pull/177), [#249](https://github.com/alibaba/OpenSandbox/pull/249), [#417](https://github.com/alibaba/OpenSandbox/pull/417).\n\n### Deployment\n\n- [x] **Guide** - Deployment guide for self-hosted Kubernetes cluster. See the [Kubernetes README](kubernetes/README.md) and Helm chart docs in [kubernetes/charts/](kubernetes/charts/). Related PRs: [#232](https://github.com/alibaba/OpenSandbox/pull/232), [#302](https://github.com/alibaba/OpenSandbox/pull/302), [#342](https://github.com/alibaba/OpenSandbox/pull/342).\n\n## Contact and Discussion\n\n- Issues: Submit bugs, feature requests, or design discussions through GitHub Issues\n- DingTalk: Join the [OpenSandbox technical discussion group](https://qr.dingtalk.com/action/joingroup?code=v1,k1,A4Bgl5q1I1eNU/r33D18YFNrMY108aFF38V+r19RJOM=\u0026_dt_no_comment=1\u0026origin=11)\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=alibaba/OpenSandbox\u0026type=date\u0026legend=top-left)](https://www.star-history.com/#alibaba/OpenSandbox\u0026type=date\u0026legend=top-left)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falibaba%2Fopensandbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falibaba%2Fopensandbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falibaba%2Fopensandbox/lists"}