Index of every page on this site: llms.txt
All skills
rivet-dev avatar

/sandbox-agent

@3b027b3 official
by Rivetrivet-dev/skills53 stars
14
Run it yourself

Deploy, configure, and integrate Sandbox Agent - a universal API for orchestrating AI coding agents (Claude Code, Codex, OpenCode, Amp) in sandboxed environments. Use when setting up sandbox-agent server locally or in cloud sandboxes (E2B, Daytona, Docker), creating and managing agent sessions via SDK or API, streaming agent events and handling human-in-the-loop interactions, building chat UIs for coding agents, or understanding the universal schema for agent responses.

Use this Skill: https://skilld.dev/gh/rivet-dev/skills/sandbox-agent

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencessdk-overview.md

≈1.9k tokens on demand. Your agent reads this file only when SKILL.md points to it.

SDK Overview

Source: sandbox-agent/docs/content/docs/sdk-overview.mdx Canonical URL: https://rivet.dev/sandbox-agent/docs/sdk-overview Description: Use the TypeScript SDK to manage Sandbox Agent sessions and APIs.


The TypeScript SDK is centered on sandbox-agent and its SandboxAgent class.

Install

npm
npm install sandbox-agent@0.5.x
bun
bun add sandbox-agent@0.5.x
# 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

Optional React components

npm install @sandbox-agent/react@0.5.x

Create a client

import { SandboxAgent } from "sandbox-agent";

const sdk = await SandboxAgent.connect({
  baseUrl: "http://127.0.0.1:2468",
});

SandboxAgent.connect(...) now waits for /v1/health by default before other SDK requests proceed. To disable that gate, pass waitForHealth: false. To keep the default gate but fail after a bounded wait, pass waitForHealth: { timeoutMs: 120_000 }. To cancel the startup wait early, pass signal: abortController.signal.

With a custom fetch handler (for example, proxying requests inside Workers):

const sdk = await SandboxAgent.connect({
  fetch: (input, init) => customFetch(input, init),
});

With an abort signal for the startup health gate:

const controller = new AbortController();

const sdk = await SandboxAgent.connect({
  baseUrl: "http://127.0.0.1:2468",
  signal: controller.signal,
});

controller.abort();

With persistence (see Persisting Sessions for driver options):

import { SandboxAgent, InMemorySessionPersistDriver } from "sandbox-agent";

const persist = new InMemorySessionPersistDriver();

const sdk = await SandboxAgent.connect({
  baseUrl: "http://127.0.0.1:2468",
  persist,
});

Local spawn with a sandbox provider:

import { SandboxAgent } from "sandbox-agent";
import { local } from "sandbox-agent/local";

const sdk = await SandboxAgent.start({
  sandbox: local(),
});

// sdk.sandboxId — prefixed provider ID (e.g. "local/127.0.0.1:2468")

await sdk.destroySandbox(); // provider-defined cleanup + disposes client

SandboxAgent.start(...) requires a sandbox provider. Built-in providers:

Import Provider
sandbox-agent/local Local subprocess
sandbox-agent/docker Docker container
sandbox-agent/e2b E2B sandbox
sandbox-agent/daytona Daytona workspace
sandbox-agent/agentcomputer Agent Computer managed worker
sandbox-agent/vercel Vercel Sandbox
sandbox-agent/cloudflare Cloudflare Sandbox

Use sdk.dispose() to disconnect without changing sandbox state, sdk.pauseSandbox() for graceful suspension when supported, or sdk.killSandbox() for permanent deletion.

Session flow

const session = await sdk.createSession({
  agent: "mock",
  cwd: "/",
});

const prompt = await session.prompt([
  { type: "text", text: "Summarize this repository." },
]);

console.log(prompt.stopReason);

Load and destroy:

const restored = await sdk.resumeSession(session.id);
await restored.prompt([{ type: "text", text: "Continue from previous context." }]);

await sdk.destroySession(restored.id);

Session configuration

Set model, mode, or thought level at creation or on an existing session:

const session = await sdk.createSession({
  agent: "codex",
  model: "gpt-5.3-codex",
});

await session.setModel("gpt-5.2-codex");
await session.setMode("auto");

const options = await session.getConfigOptions();
const modes = await session.getModes();

Handle permission requests from agents that ask before executing tools:

const claude = await sdk.createSession({
  agent: "claude",
  mode: "default",
});

claude.onPermissionRequest((request) => {
  void claude.respondPermission(request.id, "once");
});

See Agent Sessions for full details on config options and error handling.

Events

Subscribe to live events:

const unsubscribe = session.onEvent((event) => {
  console.log(event.eventIndex, event.sender, event.payload);
});

await session.prompt([{ type: "text", text: "Give me a short summary." }]);
unsubscribe();

Fetch persisted events:

const page = await sdk.getEvents({
  sessionId: session.id,
  limit: 100,
});

console.log(page.items.length);

Control-plane and HTTP helpers

const health = await sdk.getHealth();
const agents = await sdk.listAgents();
await sdk.installAgent("codex", { reinstall: true });

const entries = await sdk.listFsEntries({ path: "." });
const writeResult = await sdk.writeFsFile({ path: "./hello.txt" }, "hello");

console.log(health.status, agents.agents.length, entries.length, writeResult.path);

Desktop API

The SDK also wraps the desktop host/runtime HTTP API.

Install desktop dependencies first on Linux hosts:

sandbox-agent install desktop --yes

Then query status, surface remediation if needed, and start the runtime:

const status = await sdk.getDesktopStatus();

if (status.state === "install_required") {
  console.log(status.installCommand);
}

const started = await sdk.startDesktop({
  width: 1440,
  height: 900,
  dpi: 96,
});

const screenshot = await sdk.takeDesktopScreenshot();
const displayInfo = await sdk.getDesktopDisplayInfo();

await sdk.moveDesktopMouse({ x: 400, y: 300 });
await sdk.clickDesktop({ x: 400, y: 300, button: "left", clickCount: 1 });
await sdk.typeDesktopText({ text: "hello world", delayMs: 10 });
await sdk.pressDesktopKey({ key: "ctrl+l" });

await sdk.stopDesktop();

Screenshot helpers return Uint8Array PNG bytes. The SDK does not attempt to install OS packages remotely; callers should surface missingDependencies and installCommand from getDesktopStatus().

Error handling

import { SandboxAgentError } from "sandbox-agent";

try {
  await sdk.listAgents();
} catch (error) {
  if (error instanceof SandboxAgentError) {
    console.error(error.status, error.problem);
  }
}

Inspector URL

When you call SandboxAgent.start(...), prefer sdk.inspectorUrl. Some hosted providers return a browser-ready Inspector URL there.

import { buildInspectorUrl } from "sandbox-agent";

const url = buildInspectorUrl({
  baseUrl: "https://your-sandbox-agent.example.com",
  headers: { "X-Custom-Header": "value" },
});

console.log(url);

Parameters:

  • baseUrl (required unless fetch is provided): Sandbox Agent server URL
  • token (optional): Bearer token for authenticated servers
  • headers (optional): Additional request headers
  • fetch (optional): Custom fetch implementation used by SDK HTTP and session calls
  • skipHealthCheck (optional): set true to skip the startup /v1/health wait
  • waitForHealth (optional, defaults to enabled): waits for /v1/health before HTTP helpers and session setup proceed; pass false to disable or { timeoutMs } to bound the wait
  • signal (optional): aborts the startup /v1/health wait used by connect()

LLM credentials

Sandbox Agent supports personal API keys, shared organization keys, and per-tenant gateway keys with budget enforcement. See LLM Credentials for setup details.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

3 alerts1d5 checks · Risk HIGH
  • Gen Agent Trust Hub1d

    The skill provides a universal API for orchestrating coding agents in sandboxed environments. It includes instructions for installing its own server components and various development tools using piped shell execution (remote code execution). The tool possesses broad capabilities for arbitrary command execution, filesystem access, and desktop control, and it features mechanisms for the agent to extract and export LLM credentials from the local host environment.

  • Socket1d

    1 alert: gptAnomaly

  • Snyk1d

    Risk: CRITICAL · 2 issues

  • Runlayer8mo

    34/41 files flagged

  • ZeroLeaks7mo

    1 finding · Score: 82/100

Signed by skilld at 3b027b3. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 days ago
  • TypeScript
  • sandbox-agent
  • api-orchestration
  • ai-agents
  • claude
  • openai
  • e2b
  • daytona
  • docker
  • session-management

README badge

README badge for rivet-dev/skills/sandbox-agent

Provides a universal API and orchestration layer for running Claude, Codex, OpenCode, and Amp coding agents in sandboxed environments (E2B, Daytona, Docker). Covers server setup, session management, event streaming, and integration with chat UIs and LLM providers.

Generated from the current SKILL.md.

Which coding agents does Sandbox Agent support?
Sandbox Agent provides a universal API for Claude Code, Codex, OpenCode, and Amp. It also supports a mock agent for testing without provider credentials.
What sandbox providers can I deploy to?
Sandbox Agent runs on E2B, Daytona, Docker, local development, and cloud platforms like Vercel and Cloudflare. You can also run it as a local subprocess via Node.js or Bun.
Do I need API keys to test Sandbox Agent?
No. Use the mock agent for SDK and integration testing without Anthropic or OpenAI credentials. For real agents, you'll need to set ANTHROPIC_API_KEY and/or OPENAI_API_KEY.
Can I use this for per-user billing or multi-tenant setups?
Yes. Sandbox Agent supports LLM credential gateways like OpenRouter, LiteLLM, and Portkey for per-tenant token tracking, budget enforcement, and usage-based billing.
What persistence options are available for agent sessions?
Sessions can be persisted in-memory, to Rivet Actor state, IndexedDB, SQLite, or Postgres depending on your deployment target.

Generated from the current SKILL.md. These answers refresh after source changes.