rivet-dev/sandbox-agentExécutez des agents de codage dans des sandbox. Contrôlez-les via HTTP. Prend en charge Claude Code, Codex, OpenCode et Amp.
Un serveur qui s'exécute dans votre sandbox. Votre application se connecte à distance pour contrôler Claude Code, Codex, OpenCode, Cursor, Amp ou Pi — diffusion des événements en continu, gestion des permissions, gestion des sessions.
Documentation — Référence API — Discord
Expérimental : Gigacode — utilisez l'interface TUI d'OpenCode avec n'importe quel agent de codage.
Exécuter des agents de codage à distance est difficile. Les SDK existants supposent une exécution locale, SSH casse la gestion TTY et le streaming, et chaque agent a une API différente. Construire à partir de zéro signifie réimplémenter tout pour chaque agent de codage.
Sandbox Agent résout trois problèmes :
Les agents de codage ont besoin de sandbox — Vous ne pouvez pas laisser l'IA exécuter du code arbitraire sur vos serveurs de production. Les agents de codage ont besoin d'environnements isolés, mais les SDK existants supposent une exécution locale. Sandbox Agent est un serveur qui s'exécute à l'intérieur de la sandbox et expose HTTP/SSE.
Chaque agent de codage est différent — Claude Code, Codex, OpenCode, Cursor, Amp et Pi ont chacun des API, des formats d'événements et des comportements propriétaires. Changer d'agent signifie réécrire votre intégration. Sandbox Agent fournit une API HTTP unique — écrivez votre code une fois, changez d'agent avec une modification de configuration.
Les sessions sont éphémères — Les transcriptions des agents vivent dans la sandbox. Lorsque le processus se termine, vous perdez tout. Sandbox Agent diffuse les événements dans un schéma universel vers votre stockage. Persistez vers Postgres, ClickHouse ou Rivet. Rejouez plus tard, auditez tout.
Le Sandbox Agent agit comme un adaptateur universel entre votre application cliente et divers agents de codage. Chaque agent possède son propre adaptateur qui gère la traduction entre l'API universelle et l'interface spécifique à l'agent.
Documentation sur l'architecture
Choisissez la méthode d'installation qui correspond le mieux à votre cas d'utilisation.
Installez skill avec :
npx skills add rivet-dev/skills -s sandbox-agent
bunx skills add rivet-dev/skills -s sandbox-agent
Importez le SDK directement dans votre application Node ou navigateur. Sécurité de type complète et support du streaming.
Installation
npm install [email protected]
bun add [email protected]
# Optional: allow Bun to run postinstall scripts for native binaries (required for 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
Configuration
Local (mode intégré) :
import { SandboxAgent } from "sandbox-agent";
const client = await SandboxAgent.start();
Distant (mode serveur) :
import { SandboxAgent } from "sandbox-agent";
const client = await SandboxAgent.connect({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
});
Aperçu de l'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);
}
Documentation du SDK — Gestion des sessions
Exécutez en tant que serveur HTTP et connectez-vous depuis n'importe quel langage. Déployez sur E2B, Daytona, Vercel ou votre propre infrastructure.
# Install it
curl -fsSL https://releases.rivet.dev/sandbox-agent/0.4.x/install.sh | sh
# Run it
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
Optionnel : préinstallez les binaires des agents (aucun serveur requis ; ils seront installés paresseusement lors de la première utilisation si vous sautez cette étape) :
sandbox-agent install-agent --all
Pour désactiver l'authentification en local :
sandbox-agent server --no-token --host 127.0.0.1 --port 2468
Démarrage rapide — Guides de déploiement
Installez le wrapper CLI (optionnel mais pratique) :
npm install -g @sandbox-agent/[email protected]
# Allow Bun to run postinstall scripts for native binaries.
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
Créez une session et envoyez un message :
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"
Vous pouvez aussi utiliser npx comme suit :
npx @sandbox-agent/[email protected] --help
bunx @sandbox-agent/[email protected] --help
Déboguez les sessions et événements avec l'interface Inspecteur intégrée (par exemple, http://localhost:2468/ui/).
Explorer l'API — Voir la spécification
Souvent, vous devez utiliser vos jetons API personnels pour tester les agents sur les sandbox :
sandbox-agent credentials extract-env --export
Non, ils sont complémentaires. AI SDK est conçu pour construire des interfaces de chat et appeler des LLM. Ce SDK est destiné à contrôler des agents de codage autonomes qui écrivent du code et exécutent des commandes. Utilisez AI SDK pour votre interface utilisateur, utilisez celui-ci lorsque vous avez besoin qu'un agent code réellement.
Claude Code, Codex, OpenCode, Cursor, Amp et Pi. Le SDK normalise leurs API afin que vous puissiez basculer entre eux sans modifier votre code.
Ce SDK ne gère pas la persistance des données de session. Les événements sont diffusés dans un schéma JSON universel que vous pouvez persister n'importe où. Consultez Gestion des sessions pour des modèles utilisant Postgres ou Rivet Actors.
Les deux. Exécutez localement pour le développement, déployez sur E2B, Daytona ou Vercel Sandboxes pour la production.
Le serveur est un binaire Rust unique qui s'exécute partout avec une simple commande curl. Si votre plateforme peut exécuter des binaires Linux (Docker, VM, etc.), cela fonctionne. Consultez les guides de déploiement pour E2B, Daytona et Vercel Sandboxes.
Oui. Utilisez sandbox-agent credentials extract-env pour extraire les clés API de vos configurations d'agents locales (Claude Code, Codex, OpenCode, Amp, Pi) et transmettez-les à l'environnement sandbox.
Rust nous offre un seul binaire statique, un démarrage rapide et une utilisation mémoire prévisible. Cela facilite l'exécution dans des sandbox ou en CI sans avoir à expédier un runtime volumineux comme Node.js.
Vous le pouvez pour le développement. Mais en production, vous avez besoin d'isolation. Les agents de codage exécutent du code arbitraire — cela ne peut pas se produire sur vos serveurs. Les sandbox fournissent l'isolation ; ce SDK fournit l'API HTTP pour contrôler les agents de codage à distance.
Les SDK officiels supposent une exécution locale. Ils créent des processus et attendent des terminaux interactifs. Ce SDK exécute un serveur dans une sandbox auquel vous vous connectez via HTTP — conçu dès le départ pour le contrôle à distance.
Les agents de codage attendent des terminaux interactifs avec une gestion TTY appropriée. SSH avec des commandes via pipe casse les confirmations d'outils, le streaming de sortie et les flux avec humain dans la boucle. Le SDK gère tout cela via une API HTTP propre.
| Composant | Description |
|---|
| Serveur | Démon Rust (sandbox-agent server) exposant l'API HTTP + SSE |
| SDK | Client TypeScript avec modes intégré et serveur |
| Inspecteur | Interface utilisateur intégrée pour inspecter les sessions et les événements |
| CLI | sandbox-agent (même binaire, plus wrapper npm) reflète les points de terminaison HTTP |