sandbox-agent

Ejecuta Agentes de Codificación en Entornos Aislados. Contrólalos a través de HTTP.

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.

¿Por qué Sandbox Agent?

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:

1. 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.

2. 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.

3. 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.

Características

• API de agente universal: Interfaz única para controlar Claude Code, Codex, OpenCode, Cursor, Amp y Pi con cobertura completa de funcionalidades
• Esquema de sesión universal: Esquema estandarizado que normaliza todos los formatos de eventos de agentes para almacenamiento y reproducción
• Se ejecuta dentro de cualquier sandbox: Binario ligero estático de Rust. Un solo comando curl para instalarlo dentro de E2B, Daytona, Modal, Cloudflare Containers, Agent Computer o Docker
• Modo servidor o SDK: Ejecútalo como servidor HTTP o intégralo con el SDK de TypeScript
• Especificación OpenAPI: Bien documentada y fácil de integrar desde cualquier lenguaje
• SDK y soporte de UI de OpenCode (Experimental): Conecta la CLI, SDK o interfaz web de OpenCode para controlar agentes a través de herramientas familiares de OpenCode

Arquitectura

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.

• Modo Embebido: Ejecuta agentes localmente como subprocesos
• Modo Servidor: Se ejecuta como servidor HTTP desde cualquier proveedor de sandbox

Documentación de arquitectura

Componentes

Comienza

Elige el método de instalación que mejor se adapte a tu caso de uso.

Skill

Instala skill con:

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

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

SDK TypeScript

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

Servidor HTTP

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

CLI

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

Documentación de la CLI

Inspector

Depura sesiones y eventos con la UI integrada del Inspector (ej., http://localhost:2468/ui/).

Documentación del Inspector

Especificación OpenAPI

Explora la API — Ver especificación

Consejo: Extraer credenciales

A menudo necesitas usar tus tokens API personales para probar agentes en sandboxes:

sandbox-agent credentials extract-env --export

Esto imprime variables de entorno para tus claves API de OpenAI/Anthropic/etc para probar con el SDK de Sandbox Agent.

FAQ

Fuera del Alcance

• Almacenamiento de sesiones en disco: Las sesiones ya son almacenadas por los respectivos agentes de codificación en el disco. Se asume que el consumidor está transmitiendo datos desde esta máquina hacia un almacenamiento externo, como Postgres, ClickHouse o Rivet.
• Envoltorios directos de LLM: Usa el Vercel AI SDK si quieres implementar tu propio agente desde cero.
• Gestión de repositorios Git: Simplemente usa comandos git o las características proporcionadas por el proveedor de sandbox de tu elección.
• API del proveedor de sandbox: Los proveedores de sandbox tienen muchas diferencias matizadas en su API; no tiene sentido para nosotros intentar proporcionar una capa personalizada. En su lugar, optamos por proporcionar guías que te permitan integrar este repositorio con proveedores de sandbox.

Hoja de Ruta

• SDK Python
• Configuración automática de MCP, skills y hooks
• Listas de tareas pendientes