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.

referencesagent-sessions.md

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

Agent Sessions

Source: sandbox-agent/docs/content/docs/agent-sessions.mdx Canonical URL: https://rivet.dev/sandbox-agent/docs/agent-sessions Description: Create sessions, prompt agents, and inspect event history.


Sessions are the unit of interaction with an agent. Create one session per task, send prompts, and consume event history.

For SDK-based flows, sessions can be restored after runtime/session loss when persistence is enabled. See Session Restoration.

Create a session

import { SandboxAgent } from "sandbox-agent";

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

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

console.log(session.id, session.agentSessionId);

Send a prompt

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

console.log(response.stopReason);

Subscribe to live events

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

await session.prompt([
  { type: "text", text: "Explain the main entrypoints." },
]);

unsubscribe();

Event types

Each event's payload contains a session update. The sessionUpdate field identifies the type.

agent_message_chunk

Streamed text or content from the agent's response.

{
  "sessionUpdate": "agent_message_chunk",
  "content": { "type": "text", "text": "Here's how the repository is structured..." }
}
agent_thought_chunk

Internal reasoning from the agent (chain-of-thought / extended thinking).

{
  "sessionUpdate": "agent_thought_chunk",
  "content": { "type": "text", "text": "I should start by looking at the project structure..." }
}
user_message_chunk

Echo of the user's prompt being processed.

{
  "sessionUpdate": "user_message_chunk",
  "content": { "type": "text", "text": "Summarize the repository structure." }
}
tool_call

The agent invoked a tool (file edit, terminal command, etc.).

{
  "sessionUpdate": "tool_call",
  "toolCallId": "tc_abc123",
  "title": "Read file",
  "status": "in_progress",
  "rawInput": { "path": "/src/index.ts" }
}
tool_call_update

Progress or result update for an in-progress tool call.

{
  "sessionUpdate": "tool_call_update",
  "toolCallId": "tc_abc123",
  "status": "completed",
  "content": [{ "type": "text", "text": "import express from 'express';\n..." }]
}
plan

The agent's execution plan for the current task.

{
  "sessionUpdate": "plan",
  "entries": [
    { "content": "Read the project structure", "status": "completed" },
    { "content": "Identify main entrypoints", "status": "in_progress" },
    { "content": "Write summary", "status": "pending" }
  ]
}
usage_update

Token usage metrics for the current turn.

{
  "sessionUpdate": "usage_update"
}
session_info_update

Session metadata changed (e.g. agent-generated title).

{
  "sessionUpdate": "session_info_update",
  "title": "Repository structure analysis"
}

Fetch persisted event history

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

for (const event of page.items) {
  console.log(event.id, event.createdAt, event.sender);
}

List and load sessions

const sessions = await sdk.listSessions({ limit: 20 });

for (const item of sessions.items) {
  console.log(item.id, item.agent, item.createdAt);
}

if (sessions.items.length > 0) {
  const loaded = await sdk.resumeSession(sessions.items[0]!.id);
  await loaded.prompt([{ type: "text", text: "Continue." }]);
}

Configure model, mode, and thought level

Set the model, mode, or thought level on a session at creation time or after:

// At creation time
const session = await sdk.createSession({
  agent: "codex",
  model: "gpt-5.3-codex",
  mode: "auto",
  thoughtLevel: "high",
});
// After creation
await session.setModel("gpt-5.2-codex");
await session.setMode("full-access");
await session.setThoughtLevel("medium");

Query available modes:

const modes = await session.getModes();
console.log(modes?.currentModeId, modes?.availableModes);

Advanced config options

For config options beyond model, mode, and thought level, use getConfigOptions to discover what the agent supports and setConfigOption to set any option by ID:

const options = await session.getConfigOptions();
for (const opt of options) {
  console.log(opt.id, opt.category, opt.type);
}
await session.setConfigOption("some-agent-option", "value");

Handle permission requests

For agents that request tool-use permissions, register a permission listener and reply with once, always, or reject:

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

session.onPermissionRequest((request) => {
  console.log(request.toolCall.title, request.availableReplies);
  void session.respondPermission(request.id, "once");
});

await session.prompt([
  { type: "text", text: "Create ./permission-example.txt with the text hello." },
]);

Auto-approving permissions

To auto-approve all permission requests, respond with "once" or "always" in your listener:

session.onPermissionRequest((request) => {
  void session.respondPermission(request.id, "always");
});

See examples/permissions/src/index.ts for a complete permissions example that works with Claude and Codex.

Some agents like Claude allow configuring permission behavior through modes (e.g. bypassPermissions, acceptEdits). We recommend leaving the mode as default and handling permission decisions explicitly in onPermissionRequest instead.

Destroy a session

await sdk.destroySession(session.id);

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.