sandbox-agent

코딩 에이전트를 샌드박스에서 실행하고 HTTP로 제어하세요

샌드박스 내부에서 실행되는 서버입니다. 앱이 원격으로 연결하여 Claude Code, Codex, OpenCode, Cursor, Amp, Pi를 제어하며 이벤트 스트리밍, 권한 처리, 세션 관리를 수행합니다.

문서 — API 레퍼런스 — Discord

실험적: Gigacode — 모든 코딩 에이전트와 함께 OpenCode의 TUI를 사용합니다.

Sandbox Agent가 필요한 이유

코딩 에이전트를 원격으로 실행하는 것은 어렵습니다. 기존 SDK는 로컬 실행을 가정하고, SSH는 TTY 처리와 스트리밍을 망가뜨리며, 각 에이전트마다 다른 API를 가지고 있습니다. 처음부터 구축하려면 모든 코딩 에이전트에 대해 모든 것을 다시 구현해야 합니다.

Sandbox Agent는 세 가지 문제를 해결합니다:

1. 코딩 에이전트에는 샌드박스가 필요합니다 — AI가 프로덕션 서버에서 임의의 코드를 실행하도록 할 수 없습니다. 코딩 에이전트는 격리된 환경이 필요하지만 기존 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 바이너리. E2B, Daytona, Modal, Cloudflare Containers, Agent Computer 또는 Docker 내부에 설치하려면 curl 명령 하나면 됩니다
• 서버 또는 SDK 모드: HTTP 서버로 실행하거나 TypeScript SDK로 임베드
• OpenAPI 스펙: 잘 문서화되어 모든 언어에서 쉽게 통합 가능
• OpenCode SDK 및 UI 지원 (실험적): OpenCode CLI, SDK 또는 웹 UI를 연결하여 익숙한 OpenCode 도구를 통해 에이전트를 제어하세요

아키텍처

Sandbox Agent는 클라이언트 애플리케이션과 다양한 코딩 에이전트 사이의 범용 어댑터 역할을 합니다. 각 에이전트는 자체 어댑터를 가지고 있으며, 이 어댑터가 범용 API와 에이전트별 인터페이스 간의 변환을 처리합니다.

• 임베디드 모드: 로컬에서 에이전트를 하위 프로세스로 실행
• 서버 모드: 모든 샌드박스 제공자로부터 HTTP 서버로 실행

아키텍처 문서

구성 요소

시작하기

사용 사례에 가장 적합한 설치 방법을 선택하세요.

Skill

다음과 같이 skill을 설치하세요:

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

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

TypeScript SDK

SDK를 Node 또는 브라우저 애플리케이션으로 직접 가져오세요. 완전한 타입 안전성과 스트리밍 지원을 제공합니다.

설치

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: "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 문서

검사기

내장 검사기 UI로 세션 및 이벤트를 디버깅하세요 (예: http://localhost:2468/ui/).

검사기 문서

OpenAPI 명세

API 살펴보기 — 명세 보기

팁: 자격 증명 추출

종종 개인 API 토큰을 사용하여 샌드박스에서 에이전트를 테스트해야 합니다:

sandbox-agent credentials extract-env --export

이 명령은 Sandbox Agent SDK로 테스트하기 위해 OpenAI/Anthropic 등 API 키에 대한 환경 변수를 출력합니다.

FAQ

범위 외

• 디스크에 세션 저장: 각 코딩 에이전트가 이미 디스크에 세션을 저장합니다. 소비자가 이 머신에서 Postgres, ClickHouse 또는 Rivet과 같은 외부 저장소로 데이터를 스트리밍하고 있다고 가정합니다.
• 직접 LLM 래퍼: 처음부터 자체 에이전트를 구현하려면 Vercel AI SDK를 사용하십시오.
• Git 저장소 관리: git 명령어 또는 샌드박스 제공자가 제공하는 기능을 그대로 사용하십시오.
• 샌드박스 제공자 API: 샌드박스 제공자는 API에 많은 미묘한 차이가 있으므로, 자체 사용자 지정 계층을 제공하는 것은 의미가 없습니다. 대신 이 저장소를 샌드박스 제공자와 통합할 수 있는 가이드를 제공합니다.

로드맵

• Python SDK
• 자동 MCP, skill, hook 구성
• 할 일 목록