{"id":35711277,"url":"https://github.com/agent-sandbox/agent-sandbox","last_synced_at":"2026-01-13T20:33:04.950Z","repository":{"id":328267166,"uuid":"1110443867","full_name":"agent-sandbox/agent-sandbox","owner":"agent-sandbox","description":"Agent-sandbox is an enterprise-grade ai-first, cloud-native runtime environment for AI Agents. Allows Agents to securely run untrusted LLM-generated Code, Browser use, Computer use, and Shell commands etc. with stateful, long-running, multi-session and multi-tenant.","archived":false,"fork":false,"pushed_at":"2025-12-29T10:53:32.000Z","size":19496,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-01T05:31:34.621Z","etag":null,"topics":["agent","agent-sandbox","ai-infra","ai-sandbox","browser-use","code-executor","computer-use","container","mcp","sandbox"],"latest_commit_sha":null,"homepage":"","language":"Go","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/agent-sandbox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-05T07:46:33.000Z","updated_at":"2025-12-29T10:53:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/agent-sandbox/agent-sandbox","commit_stats":null,"previous_names":["agent-sandbox/agent-sandbox"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/agent-sandbox/agent-sandbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-sandbox%2Fagent-sandbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-sandbox%2Fagent-sandbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-sandbox%2Fagent-sandbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-sandbox%2Fagent-sandbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agent-sandbox","download_url":"https://codeload.github.com/agent-sandbox/agent-sandbox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-sandbox%2Fagent-sandbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28399861,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"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":["agent","agent-sandbox","ai-infra","ai-sandbox","browser-use","code-executor","computer-use","container","mcp","sandbox"],"created_at":"2026-01-06T04:12:41.362Z","updated_at":"2026-01-13T20:33:04.945Z","avatar_url":"https://github.com/agent-sandbox.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cpicture \u003e\n  \u003cimg alt=\"agent-sandbox\" src=\"./docs/agentsandbox.png\" width=\"240px\" height=\"280px\"\u003e\n  \u003c/picture\u003e\n\n  \u003cp align=\"center\"\u003e\u003cb\u003e Agent-Sandbox is an open-sourced \u003ca href=\"https://docs.blaxel.ai/Sandboxes/Overview\"\u003eBlaxel Sandbox\u003c/a\u003e or \u003ca href=\"https://e2b.dev/\"\u003eE2B\u003c/a\u003e like solution! \u003c/b\u003e\n\u003c/p\u003e\n\u003cbr/\u003e\n  \u003cp align=\"center\"\u003eAgent-Sandbox is an enterprise-grade ai-first, cloud-native, high-performance runtime environment designed for AI Agents. It combines the Kubernetes\nwith container isolation. Allows Agents to securely run untrusted LLM-generated Code, Browser use, Computer use, and\nShell commands etc. with stateful, long-running, multi-session and multi-tenant.\u003c/p\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003cpicture \u003e\n  \u003cimg alt=\"agent-sandbox\" src=\"https://github.com/user-attachments/assets/00c80583-8372-42cb-8cf0-8ae9e83f1454\"\u003e\n\u003c/picture\u003e\n\u003c/div\u003e\n\n---\n\n# Why Agent-Sandbox?\n\nWhen we are developing AI Agents, one of the critical challenges is providing an Enterprise-Grade\u0026Production-Grade environment for executing untrusted code and performing various tasks, that is **Multi-Session and Multi-Tenant**.\n\nSandbox must be isolated on a **Per-Agent** even **Per-User** basis to ensure security and prevent interference **between different conversation or task**. Additionally, the sandbox environment should support state persistence, allowing agents to maintain context and data across multiple interactions or multi agents etc.\n\nTherefore, **Multi-Session and Multi-Tenant** is very critical,  Each sandbox is isolated on a per-agent or per-user basis, ensuring security and preventing interference between different conversations or tasks.\n\nI found [kubernetes-sigs/agent-sandbox](https://github.com/kubernetes-sigs/agent-sandbox) leverages [AIO Sandbox](https://github.com/agent-infra/sandbox) and Kubernetes to provide a similar solution. But it seems not friendly for AI Agents to manage the sandbox lifecycle and not friendly for commonly users to use it, because it faces to Kubernetes directly.\n\nSo, We decide created this **Agent-Sandbox** project, which provides a RESTful API and MCP(Model Context Protocol) server to manage the sandbox lifecycle easily. It abstracts the complexity of Kubernetes and provides a simple interface for AI Agents and users to create, access, and delete sandboxes as needed. And we refer to some design ideas from [Blaxel Sandbox](https://docs.blaxel.ai/Sandboxes/Overview) and [E2B](https://e2b.dev/) provide similar features like lifecycle management and API design. Making it more suitable for AI Agents to use, but is opensource and self-hosted.\n\n## Full sandbox lifecycle manage by Agent-Sandbox MCP Server\n![full-lifecycle-demo.png](docs/full-lifecycle-demo.png)\n\n## Architecture\n```mermaid\nflowchart TD\n    A1([Agent A]):::agent --\u003e|Execute Code| ASB\n    A2([Agent B]):::agent --\u003e|Browse Web| ASB\n    A3([Agent C]):::agent --\u003e|Terminal Access| ASB(Agent-Sandbox \u003cbr/\u003e Auto CRUD Sandboxes)\n    A4([Agent ...]):::agent --\u003e|...| ASB\n    \n    ASB --\u003eSB1{{Code Sandbox}}\n    ASB --\u003eSB2{{Browser Sandbox}}\n    ASB --\u003eSB3{{Computer Sandbox}}\n    ASB --\u003eSB4{{Customized Sandbox}}\n    \n    SB1 \u003c--\u003e|File R/W| V\n    SB2 \u003c--\u003e|State Persistence| V\n    SB3 \u003c--\u003e|Shared Storage| V\n    SB4 \u003c--\u003e V[Unified Storage \u003cbr/\u003e NAS / OSS / S3]\n    \n    V --- K[Kubernetes Cluster]\n    \n    style ASB fill:#bd3cfe,stroke:#333,stroke-width:0,color:#fff;\n    classDef agent fill:#f9f,stroke:#333,stroke-width:3px;\n```\n\n# Features\n- **Ai-First** - Agents automatically manage whole Sandbox's lifecycle by the MCP( Model Context Protocol ) , making it easy to manage various Sandbox environments and access them automatically.\n- **AI-Agent Runtimes** - Supports various AI agent runtimes, including code execution, browser automation, computer use, and shell command execution and easy to customize more runtimes.\n- **Enterprise-Grade** - Support multiple Sandbox lifecycle manage for each tenant or session, allowing Agents to run different tasks simultaneously without interference for different tenant or session.\n- **Cloud-Native** - Leverages Kubernetes built to run in cloud environments, leveraging the benefits of cloud infrastructure such as scalability, flexibility, resilience and efficient resource management.\n- **Fast and Lightweight** - Designed to be lightweight and fast, minimizing Kubernetes's objects to deploy. easy to use and maintain.\n\n# Quick Start\n\n## 1, Installation\nYou can install Agent-Sandbox by applying the provided [install.yaml](https://github.com/agent-sandbox/agent-sandbox/blob/main/install.yaml) file to your Kubernetes cluster.  \n\nrequires **Kubernetes version 1.26** or higher.\n```bash\nkubectl create namespace agent-sandbox\nkubectl apply -nagent-sandbox -f install.yaml\n```\nYou can create an ingress or port-forward to access the Agent-Sandbox API server. Ingress like this:\n```yaml\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: agent-sandbox\n  namespace: agent-sandbox\nspec:\n  ingressClassName: ingress-nginx\n  rules:\n  - host: agent-sandbox.your-host.com\n    http:\n      paths:\n      - backend:\n          service:\n            name: agent-sandbox\n            port:\n              number: 80\n        path: /(.*)\n```\nNow you can access the Agent-Sandbox API server at `http://agent-sandbox.your-host.com`.\n\n## 2, Usage\nThe Agent-Sandbox provides a RESTful API or MCP to manage sandboxes. The typical workflow involves creating a sandbox, accessing it, and then deleting it when no longer needed.\n```mermaid\nflowchart LR\n\nA[Create Sandbox] --\u003e|mcp ro restful api| B(Access Sandbox)--\u003e|mcp or timeout or restful api| C[Delete Sandbox]\n```\n\n\n### 2.1, Use Agent-Sandbox MCP Server\nYou can manage sandboxes using the Model Context Protocol (MCP) with your AI Agents. The MCP server allows Agents to create, access, and delete sandboxes automatically.\n\nMCP Server Address: `http://agent-sandbox.your-host.com/mcp`. Now support SSE(Streamable-http).\n\n#### MCP Demos:\n\n##### 1, Code Execution\n\nAgents automatically create a sandbox when code needs to be executed and delete it when execution completes, ensuring isolated and secure code runs.\n\n[code execution](https://github.com/user-attachments/assets/d6ee410f-e12c-4c40-9dcc-f16b3b1abade)\n\n\n##### 2, Browser Use\n\nAgents automatically create a sandbox when website access is needed and delete it when the task is finished, providing isolated browser sessions for web interactions.\n\n[browser use](https://github.com/user-attachments/assets/e75daeb0-2bce-4144-9c2e-9c7979c21a05)\n\n\nThis MCP integration enables agents to manage sandbox resources without manual intervention, supporting multi-session and multi-tenant operations with automatic cleanup.\n\n---\n\n### 2.2, Use RESTful API\nYou can also manage sandboxes manually using the RESTful API provided by Agent-Sandbox.\n\n#### I, Create a Sandbox\nYou can create a new sandbox by sending a POST request to the `/api/v1/sandbox` endpoint with the desired configuration. For example, to create an `aio` environment sandbox and name it `sandbox-01`, you can use the following curl command or programmatically call the API:\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd valign=\"top\"\u003e\n\n**Shell**\n```shell\ncurl --location '/api/v1/sandbox' \\\n--header 'Content-Type: application/json' \\\n--data '{\"name\":\"sandbox-01\"}'\n```\nfor China user, please specify the local aio image registry to improve the pull speed:\n```shell\ncurl --location '/api/v1/sandbox' \\\n--header 'Content-Type: application/json' \\\n--data '{\"name\":\"sandbox-01\",\"image\":\"enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest\"}'\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n**Python**\n```python\nimport requests\nimport json\n\nurl = \"/api/v1/sandbox\"\n\npayload = json.dumps({\n  \"name\": \"sandbox-01\"\n})\nheaders = {\n  'Content-Type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n```\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n**Result**\n```json\n{\n    \"code\": \"0\",\n    \"data\": \"Sandbox sandbox-01 created successfully\"\n}\n```\n\n#### II, Access to Sandbox\n`/sandbox/{sandbox_name}` endpoint to get the access of the sandbox, including the connection details such as URL, WebSocket URL, VNC URL, or other relevant information based on the sandbox environment type.\n\nNow you can access to the previously created **sandbox-01** sandbox using `/sandbox/sandbox-01`.\n\n**You will see:**\n![aio-demo.jpg](docs/aio-demo.jpg)\n\n**Use agent sandbox SDK access this sandbox:**\n```python\nfrom agent_sandbox import Sandbox\n\n# Initialize client\nclient = Sandbox(base_url=\"http://agent-sandbox.your-host.com/sandbox/sandbox-01\")\nhome_dir = client.sandbox.get_context().home_dir\n\n# Execute shell commands\nresult = client.shell.exec_command(command=\"ls -la\")\nprint(result.data.output)\n\n# File operations\ncontent = client.file.read_file(file=f\"{home_dir}/.bashrc\")\nprint(content.data.content)\n\n# Browser automation\nscreenshot = client.browser.screenshot()\n```\n\nAnd this created Sandbox's MCP Server address is: `/sandbox/sandbox-01/mcp`. you can use this MCP Server with your AI Agent to access this sandbox.\n\nFor more usage, please refer to: https://github.com/agent-infra/sandbox\n\n#### III, Delete a Sandbox\nYou can delete a sandbox by sending a DELETE request to the `/api/v1/sandbox/{sandbox_name}` endpoint. For example, to delete the `sandbox-01` sandbox, you can use the following curl command or programmatically call the API:\n\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd valign=\"top\"\u003e\n\n**Shell**\n```shell\ncurl --location --request DELETE '/api/v1/sandbox/sandbox-01'\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n**Python**\n```python\nimport requests\n\nurl = \"/api/v1/sandbox/sandbox-01\"\n\nheaders = {\n  'Content-Type': 'application/json'\n}\n\nresponse = requests.request(\"DELETE\", url, headers=headers)\n\nprint(response.text)\n```\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n**Result:**\n\n```json\n{\n    \"code\": \"0\",\n    \"data\": \"Sandbox sandbox-01 deleted successfully\"\n}\n```\n\n# License\n\n[Apache License](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagent-sandbox%2Fagent-sandbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagent-sandbox%2Fagent-sandbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagent-sandbox%2Fagent-sandbox/lists"}