sandbox-agent

Execute Agentes de Codificação em Sandboxes. Controle-os via HTTP.

Um servidor que é executado dentro da sua sandbox. Sua aplicação se conecta remotamente para controlar Claude Code, Codex, OpenCode, Cursor, Amp ou Pi — transmitindo eventos, gerenciando permissões e sessões.

Documentação — Referência da API — Discord

Experimental: Gigacode — use a TUI do OpenCode com qualquer agente de codificação.

Por que Sandbox Agent?

Executar agentes de codificação remotamente é difícil. SDKs existentes assumem execução local, SSH quebra o manuseio de TTY e streaming, e cada agente tem uma API diferente. Construir do zero significa reimplementar tudo para cada agente de codificação.

Sandbox Agent resolve três problemas:

1. Agentes de codificação precisam de sandboxes — Você não pode deixar a IA executar código arbitrário em seus servidores de produção. Agentes de codificação precisam de ambientes isolados, mas SDKs existentes assumem execução local. Sandbox Agent é um servidor que é executado dentro da sandbox e expõe HTTP/SSE.

2. Cada agente de codificação é diferente — Claude Code, Codex, OpenCode, Cursor, Amp e Pi têm APIs, formatos de eventos e comportamentos proprietários. Trocar de agente significa reescrever sua integração. Sandbox Agent fornece uma API HTTP única — escreva seu código uma vez, troque de agente com uma mudança de configuração.

3. Sessões são efêmeras — Os registros dos agentes vivem na sandbox. Quando o processo termina, você perde tudo. Sandbox Agent transmite eventos em um esquema universal para seu armazenamento. Persista em Postgres, ClickHouse ou Rivet. Reproduza depois, audite tudo.

Recursos

• API Universal de Agentes: Interface única para controlar Claude Code, Codex, OpenCode, Cursor, Amp e Pi com cobertura completa de funcionalidades
• Esquema Universal de Sessões: Esquema padronizado que normaliza todos os formatos de eventos dos agentes para armazenamento e reprodução
• Executa Dentro de Qualquer Sandbox: Binário Rust estático e leve. Um comando curl para instalar dentro de E2B, Daytona, Modal, Cloudflare Containers, Agent Computer ou Docker
• Modo Servidor ou SDK: Execute como servidor HTTP ou incorpore com o SDK TypeScript
• Especificação OpenAPI: Bem documentada e fácil de integrar a partir de qualquer linguagem
• Suporte ao SDK e UI do OpenCode (Experimental): Conecte a CLI, SDK ou interface web do OpenCode para controlar agentes através das ferramentas familiares do OpenCode

Arquitetura

O Sandbox Agent atua como um adaptador universal entre sua aplicação cliente e vários agentes de codificação. Cada agente tem seu próprio adaptador que lida com a tradução entre a API universal e a interface específica do agente.

• Modo Incorporado: Executa agentes localmente como subprocessos
• Modo Servidor: Executa como servidor HTTP a partir de qualquer provedor de sandbox

Documentação da arquitetura

Componentes

Comece

Escolha o método de instalação que melhor se adequa ao seu caso de uso.

Skill

Instale a skill com:

npx skills add rivet-dev/skills -s sandbox-agent

bunx skills add rivet-dev/skills -s sandbox-agent

SDK TypeScript

Importe o SDK diretamente na sua aplicação Node ou navegador. Tipagem completa e suporte a streaming.

Instalação

npm install [email protected]

bun add [email protected]
# Opcional: permita que o Bun execute scripts de pós-instalação para binários nativos (necessário para SandboxAgent.start()).
bun pm trust @sandbox-agent/cli-linux-x64 @sandbox-agent/cli-linux-arm64 @sandbox-agent/cli-darwin-arm64 @sandbox-agent/cli-darwin-x64 @sandbox-agent/cli-win32-x64

Configuração

Local (modo incorporado):

import { SandboxAgent } from "sandbox-agent";

const client = await SandboxAgent.start();

Remoto (modo servidor):

import { SandboxAgent } from "sandbox-agent";

const client = await SandboxAgent.connect({
  baseUrl: "http://127.0.0.1:2468",
  token: process.env.SANDBOX_TOKEN,
});

Visão Geral da API

const agents = await client.listAgents();

await client.createSession("demo", {
  agent: "codex",
  agentMode: "default",
});

await client.postMessage("demo", { message: "Hello from the SDK." });

for await (const event of client.streamEvents("demo", { offset: 0 })) {
  console.log(event.type, event.data);
}

Documentação do SDK — Gerenciamento de Sessões

Servidor HTTP

Execute como servidor HTTP e conecte-se a partir de qualquer linguagem. Implante em E2B, Daytona, Vercel ou sua própria infraestrutura.

# Instale
curl -fsSL https://releases.rivet.dev/sandbox-agent/0.4.x/install.sh | sh
# Execute
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468

Opcional: pré-instale binários dos agentes (nenhum servidor necessário; eles serão instalados preguiçosamente no primeiro uso se você pular esta etapa):

sandbox-agent install-agent --all

Para desabilitar autenticação localmente:

sandbox-agent server --no-token --host 127.0.0.1 --port 2468

Guia rápido — Guias de implantação

CLI

Instale o wrapper CLI (opcional, mas conveniente):

npm install -g @sandbox-agent/[email protected]

# Permita que o Bun execute scripts de pós-instalação para binários nativos.
bun add -g @sandbox-agent/[email protected]
bun pm -g trust @sandbox-agent/cli-linux-x64 @sandbox-agent/cli-linux-arm64 @sandbox-agent/cli-darwin-arm64 @sandbox-agent/cli-darwin-x64 @sandbox-agent/cli-win32-x64

Crie uma sessão e envie uma mensagem:

sandbox-agent api sessions create my-session --agent codex --endpoint http://127.0.0.1:2468 --token "$SANDBOX_TOKEN"
sandbox-agent api sessions send-message my-session --message "Hello" --endpoint http://127.0.0.1:2468 --token "$SANDBOX_TOKEN"
sandbox-agent api sessions send-message-stream my-session --message "Hello" --endpoint http://127.0.0.1:2468 --token "$SANDBOX_TOKEN"

Você também pode usar npx como:

npx @sandbox-agent/[email protected] --help

bunx @sandbox-agent/[email protected] --help

Documentação da CLI

Inspetor

Depure sessões e eventos com a UI integrada do Inspetor (ex.: http://localhost:2468/ui/).

Documentação do Inspetor

Especificação OpenAPI

Explore a API — Veja a Especificação

Dica: Extraia credenciais

Frequentemente você precisa usar seus tokens de API pessoais para testar agentes em sandboxes:

sandbox-agent credentials extract-env --export

Isso imprime variáveis de ambiente para suas chaves de API OpenAI/Anthropic/etc para testar com o Sandbox Agent SDK.

FAQ

Fora do Escopo

• Armazenamento de sessões em disco: As sessões já são armazenadas em disco pelos respectivos agentes de codificação. Assume-se que o consumidor está transmitindo dados desta máquina para um armazenamento externo, como Postgres, ClickHouse ou Rivet.
• Wrappers diretos de LLM: Use o Vercel AI SDK se deseja implementar seu próprio agente do zero.
• Gerenciamento de Repositórios Git: Apenas use comandos git ou os recursos fornecidos pelo seu provedor de sandbox de sua escolha.
• API do Provedor de Sandbox: Provedores de sandbox têm muitas diferenças sutis em suas APIs, não faz sentido tentarmos fornecer uma camada personalizada. Em vez disso, optamos por fornecer guias que permitem integrar este repositório com provedores de sandbox.

Roadmap

• SDK Python
• Configuração automática de MCP, skills e hooks
• Listas de tarefas