sandbox-agent

Запускайте кодинг-агентов в песочницах. Управляйте ими через HTTP.

Сервер, работающий внутри вашей песочницы. Ваше приложение подключается удалённо для управления Claude Code, Codex, OpenCode, Cursor, Amp или Pi — передавая события, обрабатывая разрешения, управляя сессиями.

Документация — API Reference — Discord

Экспериментально: Gigacode — используйте TUI OpenCode с любым кодинг-агентом.

Зачем нужен Sandbox Agent?

Запускать кодинг-агентов удалённо сложно. Существующие SDK предполагают локальное выполнение, SSH ломает обработку TTY и стриминг, а у каждого агента свой API. Создание с нуля означает переписывание всего для каждого кодинг-агента.

Sandbox Agent решает три проблемы:

1. Кодинг-агентам нужны песочницы — Нельзя позволять ИИ выполнять произвольный код на ваших production-серверах. Кодинг-агентам нужны изолированные среды, но существующие SDK предполагают локальное выполнение. Sandbox Agent — это сервер, который работает внутри песочницы и предоставляет HTTP/SSE.

2. Каждый кодинг-агент уникален — Claude Code, Codex, OpenCode, Cursor, Amp и Pi имеют собственные проприетарные API, форматы событий и поведение. Смена агента означает переписывание интеграции. Sandbox Agent предоставляет единый HTTP API — пишите код один раз, меняйте агента изменением конфига.

3. Сессии эфемерны — Транскрипты агента живут в песочнице. Когда процесс завершается, вы всё теряете. Sandbox Agent передаёт события в универсальной схеме в ваше хранилище. Сохраняйте в Postgres, ClickHouse или Rivet. Воспроизводите позже, аудитируйте всё.

Возможности

• Универсальный API агента: Единый интерфейс для управления Claude Code, Codex, OpenCode, Cursor, Amp и Pi с полным покрытием функций
• Универсальная схема сессии: Стандартизированная схема, нормализующая все форматы событий агента для хранения и воспроизведения
• Работает внутри любой песочницы: Лёгкий статический Rust-бинарник. Одна команда curl для установки внутри E2B, Daytona, Modal, Cloudflare Containers, Agent Computer или Docker
• Режим сервера или SDK: Работа как HTTP-сервер или встраивание с помощью TypeScript SDK
• OpenAPI Spec: Хорошо документирован и легко интегрируется с любого языка
• Поддержка OpenCode SDK и UI (Экспериментально): Подключите OpenCode CLI, SDK или веб-UI для управления агентами через знакомые инструменты OpenCode

Архитектура

Sandbox Agent выступает как универсальный адаптер между вашим клиентским приложением и различными кодинг-агентами. У каждого агента есть свой адаптер, который обрабатывает преобразование между универсальным API и интерфейсом, специфичным для агента.

• Встроенный режим: Запускает агентов локально как подпроцессы
• Режим сервера: Работает как HTTP-сервер от любого провайдера песочниц

Документация по архитектуре

Компоненты

Начало работы

Выберите способ установки, подходящий для вашего сценария использования.

Скилл (Skill)

Установите скилл с помощью:

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

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

TypeScript SDK

Импортируйте SDK напрямую в своё Node или browser-приложение. Полная типобезопасность и поддержка стриминга.

Установка

npm install [email protected]

bun add [email protected]
# Опционально: разрешите Bun выполнять postinstall-скрипты для нативных бинарников (требуется для 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

Настройка

Локальный (встроенный режим):

import { SandboxAgent } from "sandbox-agent";

const client = await SandboxAgent.start();

Удалённый (режим сервера):

import { SandboxAgent } from "sandbox-agent";

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

Обзор 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);
}

Документация SDK — Управление сессиями

HTTP-сервер

Запустите как HTTP-сервер и подключайтесь с любого языка. Разверните на E2B, Daytona, Vercel или собственной инфраструктуре.

# Установка
curl -fsSL https://releases.rivet.dev/sandbox-agent/0.4.x/install.sh | sh
# Запуск
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468

Опционально: предустановите бинарники агентов (необязательно; они будут установлены лениво при первом использовании, если пропустить этот шаг):

sandbox-agent install-agent --all

Для отключения аутентификации локально:

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

Краткое руководство — Руководства по развёртыванию

CLI

Установите CLI-обёртку (опционально, но удобно):

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

# Разрешите Bun выполнять postinstall-скрипты для нативных бинарников.
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

Создайте сессию и отправьте сообщение:

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"

Также можно использовать npx:

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

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

Документация CLI

Инспектор (Inspector)

Отлаживайте сессии и события с помощью встроенного UI Inspector (например, http://localhost:2468/ui/).

Документация Inspector

OpenAPI Specification

Изучите API — Посмотреть спецификацию

Совет: извлеките учётные данные

Часто вам нужны личные API-токены для тестирования агентов в песочницах:

sandbox-agent credentials extract-env --export

Эта команда выводит переменные окружения для ваших ключей API OpenAI/Anthropic и т.д. для тестирования с Sandbox Agent SDK.

FAQ

Выход за рамки

• Хранение сессий на диске: Сессии уже хранятся на диске соответствующими кодинг-агентами. Предполагается, что потребитель передаёт данные с этой машины во внешнее хранилище, например, Postgres, ClickHouse или Rivet.
• Прямые обёртки LLM: Используйте Vercel AI SDK, если хотите реализовать собственного агента с нуля.
• Управление git-репозиториями: Просто используйте команды git или функции, предоставляемые вашим провайдером песочниц.
• API провайдера песочниц: Провайдеры песочниц имеют множество нюансов в своих API, нам не имеет смысла пытаться предоставлять собственный слой. Вместо этого мы предоставляем руководства, которые позволяют вам интегрировать этот репозиторий с провайдерами песочниц.

Дорожная карта

• Python SDK
• Автоматическая настройка MCP и скиллов и хуков
• Списки задач