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.

referencesllm-credentials.md

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

LLM Credentials

Source: sandbox-agent/docs/content/docs/llm-credentials.mdx Canonical URL: https://rivet.dev/sandbox-agent/docs/llm-credentials Description: Strategies for providing LLM provider credentials to agents.


Sandbox Agent needs LLM provider credentials (Anthropic, OpenAI, etc.) to run agent sessions.

Configuration

Pass credentials via spawn.env when starting a sandbox. Each call to SandboxAgent.start() can use different credentials:

import { SandboxAgent } from "sandbox-agent";

const sdk = await SandboxAgent.start({
  spawn: {
    env: {
      ANTHROPIC_API_KEY: "sk-ant-...",
      OPENAI_API_KEY: "sk-...",
    },
  },
});

Each agent requires credentials from a specific provider. Sandbox Agent checks environment variables (including those passed via spawn.env) and host config files:

Agent Provider Environment variables Config files
Claude Code Anthropic ANTHROPIC_API_KEY, CLAUDE_API_KEY ~/.claude.json, ~/.claude/.credentials.json
Amp Anthropic ANTHROPIC_API_KEY, CLAUDE_API_KEY ~/.amp/config.json
Codex OpenAI OPENAI_API_KEY, CODEX_API_KEY ~/.codex/auth.json
OpenCode Anthropic or OpenAI ANTHROPIC_API_KEY, OPENAI_API_KEY ~/.local/share/opencode/auth.json
Mock None - -

Credential strategies

LLM credentials are passed into the sandbox as environment variables. The agent and everything inside the sandbox has access to the token, so it's important to choose the right strategy for how you provision and scope these credentials.

Strategy Who pays Cost attribution Best for
Per-tenant gateway (recommended) Your organization, billed back per tenant Per-tenant keys with budgets Multi-tenant SaaS, usage-based billing
Bring your own key Each user (usage-based) Per-user by default Dev environments, internal tools
Shared API key Your organization None (single bill) Single-tenant apps, internal platforms
Personal subscription Each user (existing subscription) Per-user by default Local dev, internal tools where users have Claude or Codex subscriptions

Per-tenant gateway (recommended)

Route LLM traffic through a gateway that mints per-tenant API keys, each with its own spend tracking and budget limits.

graph LR
    B[Your Backend] -->|tenant key| S[Sandbox]
    S -->|LLM requests| G[Gateway]
    G -->|scoped key| P[LLM Provider]

Your backend issues a scoped key per tenant, then passes it to the sandbox. This is the typical pattern when using sandbox providers (E2B, Daytona, Docker).

import { SandboxAgent } from "sandbox-agent";

async function createTenantSandbox(tenantId: string) {
  // Issue a scoped key for this tenant via OpenRouter
  const res = await fetch("https://openrouter.ai/api/v1/keys", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.OPENROUTER_PROVISIONING_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: `tenant-${tenantId}`,
      limit: 50,
      limitResetType: "monthly",
    }),
  });
  const { key } = await res.json();

  // Start a sandbox with the tenant's scoped key
  const sdk = await SandboxAgent.start({
    spawn: {
      env: {
        OPENAI_API_KEY: key, // OpenRouter uses OpenAI-compatible endpoints
      },
    },
  });

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

  return { sdk, session };
}
Security

Recommended for multi-tenant applications. Each tenant gets a scoped key with its own budget, so exfiltration only exposes that tenant's allowance.

Use cases
  • Multi-tenant SaaS: per-tenant spend tracking and budget limits
  • Production apps: exposed to end users who need isolated credentials
  • Usage-based billing: each tenant pays for their own consumption
Choosing a gateway
OpenRouter provisioned keys

Managed service, zero infrastructure. OpenRouter provides per-tenant API keys with spend tracking and budget limits via their Provisioning API. Pass the tenant key to Sandbox Agent as OPENAI_API_KEY (OpenRouter uses OpenAI-compatible endpoints).

# Create a key for a tenant with a $50/month budget
curl https://openrouter.ai/api/v1/keys \
  -H "Authorization: Bearer $PROVISIONING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "tenant-acme",
    "limit": 50,
    "limitResetType": "monthly"
  }'

Easiest to set up but not open-source. See OpenRouter pricing for details.

LiteLLM proxy

Self-hosted, open-source (MIT). LiteLLM is an OpenAI-compatible proxy with hierarchical budgets (org, team, user, key), virtual keys, and spend tracking. Requires Python + PostgreSQL.

# Create a team (tenant) with a $500 budget
curl http://litellm:4000/team/new \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_alias": "tenant-acme",
    "max_budget": 500
  }'

# Generate a key for that team
curl http://litellm:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "team-abc123",
    "max_budget": 100
  }'

Full control with no vendor lock-in. Organization-level features require an enterprise license.

Portkey gateway

Self-hosted, open-source (Apache 2.0). Portkey is a lightweight OpenAI-compatible gateway supporting 200+ providers. Single binary, no database required. Create virtual keys with per-tenant budget limits and pass them to Sandbox Agent.

Lightest operational footprint of the self-hosted options. Observability and analytics require the managed platform or your own tooling.

To bill tenants for LLM usage, use Stripe token billing (integrates natively with OpenRouter) or query your gateway's spend API and feed usage into your billing system.

Bring your own key

Each user provides their own API key. Users are billed directly by the LLM provider with no additional infrastructure needed.

Pass the user's key via spawn.env:

const sdk = await SandboxAgent.start({
  spawn: {
    env: {
      ANTHROPIC_API_KEY: userProvidedKey,
    },
  },
});
Security

API keys are typically long-lived. The key is visible to the agent and anything running inside the sandbox, so exfiltration is possible. This is usually acceptable for developer-facing tools where the user owns the key.

Use cases
  • Developer tools: each user manages their own API key
  • Internal platforms: users already have LLM provider accounts
  • Per-user billing: no extra infrastructure needed

Shared credentials

A single organization-wide API key is used for all sessions. All token usage appears on one bill with no per-user or per-tenant cost attribution.

const sdk = await SandboxAgent.start({
  spawn: {
    env: {
      ANTHROPIC_API_KEY: process.env.ORG_ANTHROPIC_KEY!,
      OPENAI_API_KEY: process.env.ORG_OPENAI_KEY!,
    },
  },
});

If you need to track or limit spend per tenant, use a per-tenant gateway instead.

Security

Not recommended for anything other than internal tooling. A single exfiltrated key exposes your organization's entire LLM budget. If you need org-paid credentials for external users, use a per-tenant gateway with scoped keys instead.

Use cases
  • Single-tenant apps: small number of users, one bill
  • Prototyping: cost attribution not needed yet
  • Simplicity over security: acceptable when exfiltration risk is low

Personal subscription

If the user is signed into Claude Code or Codex on the host machine, Sandbox Agent automatically picks up their OAuth tokens. No configuration is needed.

Remote sandboxes

Extract credentials locally and pass them to a remote sandbox via spawn.env:

$ sandbox-agent credentials extract-env
ANTHROPIC_API_KEY=sk-ant-...
CLAUDE_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
CODEX_API_KEY=sk-...

Use -e to prefix with export for shell sourcing.

Security

Personal subscriptions use OAuth tokens with a limited lifespan. These are the same credentials used when running an agent normally on the host. If a token is exfiltrated from the sandbox, the exposure window is short.

Use cases
  • Local development: users are already signed into Claude Code or Codex
  • Internal tools: every user has their own subscription
  • Prototyping: no key management needed

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.