Skip to content
Sandbox Agent
GitHub Get Started
Getting Started

Quickstart

  1. Install skill (optional)

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

  2. Set environment variables

    Each coding agent requires API keys to connect to their respective LLM providers.

    Terminal window
    export ANTHROPIC_API_KEY="sk-ant-..."
    export OPENAI_API_KEY="sk-..."
    Extracting API keys from current machine

    Use sandbox-agent credentials extract-env --export to extract your existing API keys (Anthropic, OpenAI, etc.) from local Claude Code or Codex config files.

    Testing without API keys

    Use the mock agent for SDK and integration testing without provider credentials.

    Multi-tenant and per-user billing

    For per-tenant token tracking, budget enforcement, or usage-based billing, see LLM Credentials for gateway options like OpenRouter, LiteLLM, and Portkey.

  3. Run the server

    Install and run the binary directly.

    Terminal window
    curl -fsSL https://releases.rivet.dev/sandbox-agent/0.4.x/install.sh | sh
    sandbox-agent server --no-token --host 0.0.0.0 --port 2468

    Binding to 0.0.0.0 allows the server to accept connections from any network interface, which is required when running inside a sandbox where clients connect remotely.

    Configuring token

    Tokens are usually not required. Most sandbox providers (E2B, Daytona, etc.) already secure networking at the infrastructure layer.

    If you expose the server publicly, use --token "$SANDBOX_TOKEN" to require authentication:

    Terminal window
    sandbox-agent server --token "$SANDBOX_TOKEN" --host 0.0.0.0 --port 2468

    Then pass the token when connecting:

    import { SandboxAgent } from "sandbox-agent";
    

    const sdk = await SandboxAgent.connect({
      baseUrl: "http://your-server:2468",
      token: process.env.SANDBOX_TOKEN,
    });
    CORS

    If you’re calling the server from a browser, see the CORS configuration guide.

  4. Install agents (optional)

    To preinstall agents:

    Terminal window
    sandbox-agent install-agent --all

    If agents are not installed up front, they are lazily installed when creating a session.

  5. Install desktop dependencies (optional, Linux only)

    If you want to use /v1/desktop/*, install the desktop runtime packages first:

    Terminal window
    sandbox-agent install desktop --yes

    Then use GET /v1/desktop/status or sdk.getDesktopStatus() to verify the runtime is ready before calling desktop screenshot or input APIs.

  6. 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: "claude",
      sessionInit: {
        cwd: "/",
        mcpServers: [],
      },
    });
    

    console.log(session.id);

  7. Send a message

    const result = await session.prompt([
      { type: "text", text: "Summarize the repository and suggest next steps." },
    ]);
    

    console.log(result.stopReason);

  8. Read events

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

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

    console.log(page.items.length);
    off();

  9. Test with Inspector

    Open the Inspector UI at /ui/ on your server (for example, http://localhost:2468/ui/) to inspect sessions and events in a GUI.

    Sandbox Agent Inspector

Next steps

Section titled “Next steps”
Session Persistence Configure in-memory, Rivet Actor state, IndexedDB, SQLite, and Postgres persistence.
Deploy to a Sandbox Deploy your agent to E2B, Daytona, Docker, Vercel, or Cloudflare.
SDK Overview Use the latest TypeScript SDK API.