{"id":42973519,"url":"https://github.com/rivet-dev/sandbox-agent","last_synced_at":"2026-02-06T14:30:09.848Z","repository":{"id":335056110,"uuid":"1141720197","full_name":"rivet-dev/sandbox-agent","owner":"rivet-dev","description":"Universal API for automatic coding agents in sandboxes. Supports Claude Code, Codex, OpenCode, and Amp.","archived":false,"fork":false,"pushed_at":"2026-01-30T23:33:37.000Z","size":3813,"stargazers_count":142,"open_issues_count":13,"forks_count":15,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-31T15:13:35.573Z","etag":null,"topics":["agent","ai","amp","claude","claude-code","codex","daytona","e2b","opencode","sandbox"],"latest_commit_sha":null,"homepage":"https://sandboxagent.dev","language":"Rust","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/rivet-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-25T10:03:02.000Z","updated_at":"2026-01-31T13:08:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"f5420399-8048-433f-a70c-105a75790fc0","html_url":"https://github.com/rivet-dev/sandbox-agent","commit_stats":null,"previous_names":["rivet-dev/sandbox-agent"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/rivet-dev/sandbox-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rivet-dev%2Fsandbox-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rivet-dev%2Fsandbox-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rivet-dev%2Fsandbox-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rivet-dev%2Fsandbox-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rivet-dev","download_url":"https://codeload.github.com/rivet-dev/sandbox-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rivet-dev%2Fsandbox-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28964387,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T01:25:30.373Z","status":"online","status_checked_at":"2026-02-01T02:00:08.102Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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","ai","amp","claude","claude-code","codex","daytona","e2b","opencode","sandbox"],"created_at":"2026-01-31T01:23:03.914Z","updated_at":"2026-02-01T02:00:48.886Z","avatar_url":"https://github.com/rivet-dev.png","language":"Rust","funding_links":[],"categories":["📦 Sandboxing and Isolation","TypeScript"],"sub_categories":["Anthropic Engineering \u0026 Blog"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/media/banner.png\" alt=\"Sandbox Agent SDK\" /\u003e\n\u003c/p\u003e\n\n\u003ch3 align=\"center\"\u003eRun Coding Agents in Sandboxes. Control Them Over HTTP.\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  A server that runs inside your sandbox. Your app connects remotely to control Claude Code, Codex, OpenCode, or Amp — streaming events, handling permissions, managing sessions.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://sandboxagent.dev/docs\"\u003eDocumentation\u003c/a\u003e — \u003ca href=\"https://sandboxagent.dev/docs/api-reference\"\u003eAPI Reference\u003c/a\u003e — \u003ca href=\"https://rivet.dev/discord\"\u003eDiscord\u003c/a\u003e\n\u003c/p\u003e\n\n## Why Sandbox Agent?\n\nRunning coding agents remotely is hard. Existing SDKs assume local execution, SSH breaks TTY handling and streaming, and every agent has a different API. Building from scratch means reimplementing everything for each coding agent.\n\nSandbox Agent solves three problems:\n\n1. **Coding agents need sandboxes** — You can't let AI execute arbitrary code on your production servers. Coding agents need isolated environments, but existing SDKs assume local execution. Sandbox Agent is a server that runs inside the sandbox and exposes HTTP/SSE.\n\n2. **Every coding agent is different** — Claude Code, Codex, OpenCode, and Amp each have proprietary APIs, event formats, and behaviors. Swapping agents means rewriting your integration. Sandbox Agent provides one HTTP API — write your code once, swap agents with a config change.\n\n3. **Sessions are ephemeral** — Agent transcripts live in the sandbox. When the process ends, you lose everything. Sandbox Agent streams events in a universal schema to your storage. Persist to Postgres, ClickHouse, or [Rivet](https://rivet.dev). Replay later, audit everything.\n\n## Features\n\n- **Universal Agent API**: Single interface to control Claude Code, Codex, OpenCode, and Amp with full feature coverage\n- **Streaming Events**: Real-time SSE stream of everything the agent does — tool calls, permission requests, file edits, and more\n- **Universal Session Schema**: [Standardized schema](https://sandboxagent.dev/docs/session-transcript-schema) that normalizes all agent event formats for storage and replay\n- **Human-in-the-Loop**: Approve or deny tool executions and answer agent questions remotely over HTTP\n- **Automatic Agent Installation**: Agents are installed on-demand when first used — no setup required\n- **Runs Inside Any Sandbox**: Lightweight static Rust binary. One curl command to install inside E2B, Daytona, Vercel Sandboxes, or Docker\n- **Server or SDK Mode**: Run as an HTTP server or embed with the TypeScript SDK\n- **OpenAPI Spec**: [Well documented](https://sandboxagent.dev/docs/api-reference) and easy to integrate from any language\n\n## Architecture\n\n![Agent Architecture Diagram](./.github/media/agent-diagram.gif)\n\nThe Sandbox Agent acts as a universal adapter between your client application and various coding agents. Each agent has its own adapter that handles the translation between the universal API and the agent-specific interface.\n\n- **Embedded Mode**: Runs agents locally as subprocesses\n- **Server Mode**: Runs as HTTP server from any sandbox provider\n\n[Architecture documentation](https://sandboxagent.dev/docs)\n\n## Components\n\n| Component | Description |\n|-----------|-------------|\n| **Server** | Rust daemon (`sandbox-agent server`) exposing the HTTP + SSE API |\n| **SDK** | TypeScript client with embedded and server modes |\n| **Inspector** | [inspect.sandboxagent.dev](https://inspect.sandboxagent.dev) for browsing sessions and events |\n| **CLI** | `sandbox-agent` (same binary, plus npm wrapper) mirrors the HTTP endpoints |\n\n## Get Started\n\nChoose the installation method that works best for your use case.\n\n### Skill\n\nInstall skill with:\n\n```\nnpx skills add rivet-dev/skills -s sandbox-agent\n```\n\n### TypeScript SDK\n\nImport the SDK directly into your Node or browser application. Full type safety and streaming support.\n\n**Install**\n\n```bash\nnpm install sandbox-agent\n```\n\n**Setup**\n\nLocal (embedded mode):\n\n```ts\nimport { SandboxAgent } from \"sandbox-agent\";\n\nconst client = await SandboxAgent.start();\n```\n\nRemote (server mode):\n\n```ts\nimport { SandboxAgent } from \"sandbox-agent\";\n\nconst client = await SandboxAgent.connect({\n  baseUrl: \"http://127.0.0.1:2468\",\n  token: process.env.SANDBOX_TOKEN,\n});\n```\n\n**API Overview**\n\n```ts\nconst agents = await client.listAgents();\n\nawait client.createSession(\"demo\", {\n  agent: \"codex\",\n  agentMode: \"default\",\n  permissionMode: \"plan\",\n});\n\nawait client.postMessage(\"demo\", { message: \"Hello from the SDK.\" });\n\nfor await (const event of client.streamEvents(\"demo\", { offset: 0 })) {\n  console.log(event.type, event.data);\n}\n```\n\n[SDK documentation](https://sandboxagent.dev/docs/sdks/typescript) — [Building a Chat UI](https://sandboxagent.dev/docs/building-chat-ui) — [Managing Sessions](https://sandboxagent.dev/docs/manage-sessions)\n\n### HTTP Server\n\nRun as an HTTP server and connect from any language. Deploy to E2B, Daytona, Vercel, or your own infrastructure.\n\n```bash\n# Install it\ncurl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh\n# Run it\nsandbox-agent server --token \"$SANDBOX_TOKEN\" --host 127.0.0.1 --port 2468\n```\n\nOptional: preinstall agent binaries (no server required; they will be installed lazily on first use if you skip this):\n\n```bash\nsandbox-agent install-agent claude\nsandbox-agent install-agent codex\nsandbox-agent install-agent opencode\nsandbox-agent install-agent amp\n```\n\nTo disable auth locally:\n\n```bash\nsandbox-agent server --no-token --host 127.0.0.1 --port 2468\n```\n\n[Quickstart](https://sandboxagent.dev/docs/quickstart) — [Deployment guides](https://sandboxagent.dev/docs/deploy)\n\n### CLI\n\nInstall the CLI wrapper (optional but convenient):\n\n```bash\nnpm install -g @sandbox-agent/cli\n```\n\nCreate a session and send a message:\n\n```bash\nsandbox-agent api sessions create my-session --agent codex --endpoint http://127.0.0.1:2468 --token \"$SANDBOX_TOKEN\"\nsandbox-agent api sessions send-message my-session --message \"Hello\" --endpoint http://127.0.0.1:2468 --token \"$SANDBOX_TOKEN\"\nsandbox-agent api sessions send-message-stream my-session --message \"Hello\" --endpoint http://127.0.0.1:2468 --token \"$SANDBOX_TOKEN\"\n```\n\nYou can also use npx like:\n\n```bash\nnpx sandbox-agent --help\n```\n\n[CLI documentation](https://sandboxagent.dev/docs/cli)\n\n### Inspector\n\nDebug sessions and events with the [Inspector UI](https://inspect.sandboxagent.dev).\n\n![Sandbox Agent Inspector](./.github/media/inspector.png)\n\n[Inspector documentation](https://sandboxagent.dev/docs/inspector)\n\n### OpenAPI Specification\n\n[Explore API](https://sandboxagent.dev/docs/api-reference) — [View Specification](https://github.com/rivet-dev/sandbox-agent/blob/main/docs/openapi.json)\n\n### Session Transcript Schema\n\nAll events follow a [session transcript schema](https://sandboxagent.dev/docs/session-transcript-schema) that normalizes differences between agents.\n\n### Tip: Extract credentials\n\nOften you need to use your personal API tokens to test agents on sandboxes:\n\n```bash\nsandbox-agent credentials extract-env --export\n```\n\nThis prints environment variables for your OpenAI/Anthropic/etc API keys to test with Sandbox Agent SDK.\n\n## Integrations\n\nWorks with your stack:\n\n| Sandbox Providers | AI Platforms | Infrastructure | Storage |\n|---|---|---|---|\n| [Daytona](https://sandboxagent.dev/docs/deploy/daytona) | Anthropic | Docker | Postgres |\n| [E2B](https://sandboxagent.dev/docs/deploy/e2b) | OpenAI | Fly.io | ClickHouse |\n| [Vercel Sandboxes](https://sandboxagent.dev/docs/deploy) | [AI SDK](https://ai-sdk.dev) | AWS Nitro | [Rivet](https://rivet.dev) |\n\nWant support for another agent or sandbox provider? [Open an issue](https://github.com/rivet-dev/sandbox-agent/issues/new) to request it.\n\n## FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDoes this replace the Vercel AI SDK?\u003c/strong\u003e\u003c/summary\u003e\n\nNo, they're complementary. AI SDK is for building chat interfaces and calling LLMs. This SDK is for controlling autonomous coding agents that write code and run commands. Use AI SDK for your UI, use this when you need an agent to actually code.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWhich coding agents are supported?\u003c/strong\u003e\u003c/summary\u003e\n\nClaude Code, Codex, OpenCode, and Amp. The SDK normalizes their APIs so you can swap between them without changing your code.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHow is session data persisted?\u003c/strong\u003e\u003c/summary\u003e\n\nThis SDK does not handle persisting session data. Events stream in a universal JSON schema that you can persist anywhere. See [Managing Sessions](https://sandboxagent.dev/docs/manage-sessions) for patterns using Postgres or [Rivet Actors](https://rivet.dev).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCan I run this locally or does it require a sandbox provider?\u003c/strong\u003e\u003c/summary\u003e\n\nBoth. Run locally for development, deploy to E2B, Daytona, or Vercel Sandboxes for production.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDoes it support [platform]?\u003c/strong\u003e\u003c/summary\u003e\n\nThe server is a single Rust binary that runs anywhere with a curl install. If your platform can run Linux binaries (Docker, VMs, etc.), it works. See the deployment guides for E2B, Daytona, and Vercel Sandboxes.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCan I use this with my personal API keys?\u003c/strong\u003e\u003c/summary\u003e\n\nYes. Use `sandbox-agent credentials extract-env` to extract API keys from your local agent configs (Claude Code, Codex, OpenCode, Amp) and pass them to the sandbox environment.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWhy Rust and not [language]?\u003c/strong\u003e\u003c/summary\u003e\n\nRust gives us a single static binary, fast startup, and predictable memory usage. That makes it easy to run inside sandboxes or in CI without shipping a large runtime, such as Node.js.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWhy can't I just run coding agents locally?\u003c/strong\u003e\u003c/summary\u003e\n\nYou can for development. But in production, you need isolation. Coding agents execute arbitrary code — that can't happen on your servers. Sandboxes provide the isolation; this SDK provides the HTTP API to control coding agents remotely.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHow is this different from the agent's official SDK?\u003c/strong\u003e\u003c/summary\u003e\n\nOfficial SDKs assume local execution. They spawn processes and expect interactive terminals. This SDK runs a server inside a sandbox that you connect to over HTTP — designed for remote control from the start.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWhy not just SSH into the sandbox?\u003c/strong\u003e\u003c/summary\u003e\n\nCoding agents expect interactive terminals with proper TTY handling. SSH with piped commands breaks tool confirmations, streaming output, and human-in-the-loop flows. The SDK handles all of this over a clean HTTP API.\n\u003c/details\u003e\n\n## Out of Scope\n\n- **Storage of sessions on disk**: Sessions are already stored by the respective coding agents on disk. It's assumed that the consumer is streaming data from this machine to an external storage, such as Postgres, ClickHouse, or Rivet.\n- **Direct LLM wrappers**: Use the [Vercel AI SDK](https://ai-sdk.dev/docs/introduction) if you want to implement your own agent from scratch.\n- **Git Repo Management**: Just use git commands or the features provided by your sandbox provider of choice.\n- **Sandbox Provider API**: Sandbox providers have many nuanced differences in their API, it does not make sense for us to try to provide a custom layer. Instead, we opt to provide guides that let you integrate this project with sandbox providers.\n\n## Roadmap\n\n- [ ] Python SDK\n- [ ] Automatic MCP \u0026 skill \u0026 hook configuration\n- [ ] Todo lists\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frivet-dev%2Fsandbox-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frivet-dev%2Fsandbox-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frivet-dev%2Fsandbox-agent/lists"}