rivet-dev/sandbox-agentEjecuta agentes de codificación en entornos aislados. Contrólalos mediante HTTP. Compatible con Claude Code, Codex, OpenCode y Amp.
Un servidor que se ejecuta dentro de tu sandbox. Tu aplicación se conecta remotamente para controlar Claude Code, Codex, OpenCode, Cursor, Amp o Pi — transmitiendo eventos, manejando permisos, gestionando sesiones.
Documentación — Referencia de API — Discord
Experimental: Gigacode — usa la TUI de OpenCode con cualquier agente de codificación.
Ejecutar agentes de codificación de forma remota es difícil. Los SDK existentes asumen ejecución local, SSH rompe el manejo de TTY y la transmisión en tiempo real, y cada agente tiene una API diferente. Construir desde cero significa reimplementar todo para cada agente de codificación.
Sandbox Agent resuelve tres problemas:
Los agentes de codificación necesitan sandboxes — No puedes permitir que la IA ejecute código arbitrario en tus servidores de producción. Los agentes de codificación necesitan entornos aislados, pero los SDK existentes asumen ejecución local. Sandbox Agent es un servidor que se ejecuta dentro del sandbox y expone HTTP/SSE.
Cada agente de codificación es diferente — Claude Code, Codex, OpenCode, Cursor, Amp y Pi tienen APIs, formatos de eventos y comportamientos propietarios. Cambiar de agente significa reescribir tu integración. Sandbox Agent proporciona una API HTTP única: escribe tu código una vez, cambia de agente con un cambio de configuración.
Las sesiones son efímeras — Las transcripciones del agente viven en el sandbox. Cuando el proceso termina, pierdes todo. Sandbox Agent transmite eventos en un esquema universal hacia tu almacenamiento. Persiste en Postgres, ClickHouse o Rivet. Reproduce después, audita todo.
Sandbox Agent actúa como adaptador universal entre tu aplicación cliente y varios agentes de codificación. Cada agente tiene su propio adaptador que maneja la traducción entre la API universal y la interfaz específica del agente.
| Componente | Descripción |
|---|---|
| Servidor | Demonio Rust (sandbox-agent server) que expone la API HTTP + SSE |
| SDK | Cliente TypeScript con modos embebido y servidor |
| Inspector | UI integrada para inspeccionar sesiones y eventos |
| CLI | sandbox-agent (mismo binario, más envoltorio npm) que refleja los endpoints HTTP |
Elige el método de instalación que mejor se adapte a tu caso de uso.
Instala skill con:
npx skills add rivet-dev/skills -s sandbox-agent
bunx skills add rivet-dev/skills -s sandbox-agent
Importa el SDK directamente en tu aplicación Node o navegador. Tipado completo y soporte de streaming.
Instalación
npm install [email protected]
bun add [email protected]
# Opcional: permite a Bun ejecutar scripts postinstall para binarios nativos (necesario 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
Configuración
Local (modo embebido):
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,
});
Resumen de la 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);
}
Documentación del SDK — Gestión de Sesiones
Ejecútalo como servidor HTTP y conéctate desde cualquier lenguaje. Despliega en E2B, Daytona, Vercel o tu propia infraestructura.
# Instálalo
curl -fsSL https://releases.rivet.dev/sandbox-agent/0.4.x/install.sh | sh
# Ejecútalo
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
Opcional: preinstala binarios de agentes (no es necesario; se instalarán de forma diferida en el primer uso si omites esto):
sandbox-agent install-agent --all
Para deshabilitar la autenticación localmente:
sandbox-agent server --no-token --host 127.0.0.1 --port 2468
Inicio rápido — Guías de despliegue
Instala el envoltorio CLI (opcional pero conveniente):
npm install -g @sandbox-agent/[email protected]
# Permite a Bun ejecutar scripts postinstall para binarios 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
Crea una sesión y envía un mensaje:
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"
También puedes usar npx de la siguiente manera:
npx @sandbox-agent/[email protected] --help
bunx @sandbox-agent/[email protected] --help
Depura sesiones y eventos con la UI integrada del Inspector (ej., http://localhost:2468/ui/).
