sandbox-agent/docs/quickstart.mdx

---
title: "Quickstart"
description: "Start the server and send your first message."
icon: "rocket"
---

<Steps>
  <Step title="Install skill (optional)">
    ```bash
    npx skills add rivet-dev/skills -s sandbox-agent
    ```
  </Step>

  <Step title="Set environment variables">
    Each coding agent requires API keys to connect to their respective LLM providers.

    <Tabs>
      <Tab title="Local shell">
        ```bash
        export ANTHROPIC_API_KEY="sk-ant-..."
        export OPENAI_API_KEY="sk-..."
        ```
      </Tab>

      <Tab title="E2B">
        ```typescript
        import { Sandbox } from "@e2b/code-interpreter";

        const envs: Record<string, string> = {};
        if (process.env.ANTHROPIC_API_KEY) envs.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
        if (process.env.OPENAI_API_KEY) envs.OPENAI_API_KEY = process.env.OPENAI_API_KEY;

        const sandbox = await Sandbox.create({ envs });
        ```
      </Tab>

      <Tab title="Daytona">
        ```typescript
        import { Daytona } from "@daytonaio/sdk";

        const envVars: Record<string, string> = {};
        if (process.env.ANTHROPIC_API_KEY) envVars.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
        if (process.env.OPENAI_API_KEY) envVars.OPENAI_API_KEY = process.env.OPENAI_API_KEY;

        const daytona = new Daytona();
        const sandbox = await daytona.create({
          snapshot: "sandbox-agent-ready",
          envVars,
        });
        ```
      </Tab>

      <Tab title="Docker">
        ```bash
        docker run -e ANTHROPIC_API_KEY="sk-ant-..." \
          -e OPENAI_API_KEY="sk-..." \
          your-image
        ```
      </Tab>
    </Tabs>

	<AccordionGroup>
		<Accordion title="Extracting API keys from current machine">
		  Use `sandbox-agent credentials extract-env --export` to extract your existing API keys (Anthropic, OpenAI, etc.) from your existing Claude Code or Codex config files on your machine.
		</Accordion>
		<Accordion title="Testing without API keys">
			If you want to test Sandbox Agent without API keys, use the `mock` agent to test the SDK without any credentials. It simulates agent responses for development and testing.
		</Accordion>
	</AccordionGroup>
  </Step>

  <Step title="Run the server">
    <Tabs>
      <Tab title="curl">
        Install and run the binary directly.

        ```bash
        curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh
        sandbox-agent server --no-token --host 0.0.0.0 --port 2468
        ```
      </Tab>

      <Tab title="npx">
        Run without installing globally.

        ```bash
        npx @sandbox-agent/cli server --no-token --host 0.0.0.0 --port 2468
        ```
      </Tab>

      <Tab title="npm i -g">
        Install globally, then run.

        ```bash
        npm install -g @sandbox-agent/cli
        sandbox-agent server --no-token --host 0.0.0.0 --port 2468
        ```
      </Tab>

      <Tab title="Build from source">
        If you're running from source instead of the installed CLI.

        ```bash
        cargo run -p sandbox-agent -- server --no-token --host 0.0.0.0 --port 2468
        ```
      </Tab>

      <Tab title="TypeScript (local)">
        For local development, use `SandboxAgent.start()` to automatically spawn and manage the server as a subprocess.

        ```typescript
        import { SandboxAgent } from "sandbox-agent";

        const client = await SandboxAgent.start();
        ```

        This installs the binary and starts the server for you. No manual setup required.
      </Tab>
    </Tabs>

	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.

	<AccordionGroup>
		<Accordion title="Configuring token">
			Tokens are usually not required. Most sandbox providers (E2B, Daytona, etc.) already secure their networking at the infrastructure level, so the server endpoint is never publicly accessible. For local development, binding to `127.0.0.1` ensures only local connections are accepted.

			If you need to expose the server on a public endpoint, use `--token "$SANDBOX_TOKEN"` to require authentication on all requests:

			```bash
			sandbox-agent server --token "$SANDBOX_TOKEN" --host 0.0.0.0 --port 2468
			```

			Then pass the token when connecting:

			<Tabs>
				<Tab title="TypeScript">
					```typescript
					const client = await SandboxAgent.connect({
					  baseUrl: "http://your-server:2468",
					  token: process.env.SANDBOX_TOKEN,
					});
					```
				</Tab>

				<Tab title="curl">
					```bash
					curl "http://your-server:2468/v1/sessions" \
					  -H "Authorization: Bearer $SANDBOX_TOKEN"
					```
				</Tab>

				<Tab title="CLI">
					```bash
					sandbox-agent api sessions list \
					  --endpoint http://your-server:2468 \
					  --token "$SANDBOX_TOKEN"
					```
				</Tab>
			</Tabs>
		</Accordion>
		<Accordion title="CORS">
			If you're calling the server from a browser, see the [CORS configuration guide](/docs/cors).
		</Accordion>
	</AccordionGroup>
  </Step>

  <Step title="Install agents (optional)">
    To preinstall agents:

    ```bash
    sandbox-agent install-agent claude
    sandbox-agent install-agent codex
    sandbox-agent install-agent opencode
    sandbox-agent install-agent amp
    ```

	If agents are not installed up front, they will be lazily installed when creating a session. It's recommended to pre-install agents then take a snapshot of the sandbox for faster coldstarts.
  </Step>

  <Step title="Create a session">
    <Tabs>
      <Tab title="TypeScript">
        ```typescript
        import { SandboxAgent } from "sandbox-agent";

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

        await client.createSession("my-session", {
          agent: "claude",
          agentMode: "build",
          permissionMode: "default",
        });
        ```
      </Tab>

      <Tab title="curl">
        ```bash
        curl -X POST "http://127.0.0.1:2468/v1/sessions/my-session" \
          -H "Content-Type: application/json" \
          -d '{"agent":"claude","agentMode":"build","permissionMode":"default"}'
        ```
      </Tab>

      <Tab title="CLI">
        ```bash
        sandbox-agent api sessions create my-session \
          --agent claude \
          --endpoint http://127.0.0.1:2468
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Send a message">
    <Tabs>
      <Tab title="TypeScript">
        ```typescript
        await client.postMessage("my-session", {
          message: "Summarize the repository and suggest next steps.",
        });
        ```
      </Tab>

      <Tab title="curl">
        ```bash
        curl -X POST "http://127.0.0.1:2468/v1/sessions/my-session/messages" \
          -H "Content-Type: application/json" \
          -d '{"message":"Summarize the repository and suggest next steps."}'
        ```
      </Tab>

      <Tab title="CLI">
        ```bash
        sandbox-agent api sessions send-message my-session \
          --message "Summarize the repository and suggest next steps." \
          --endpoint http://127.0.0.1:2468
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Read events">
    <Tabs>
      <Tab title="TypeScript">
        ```typescript
        // Poll for events
        const events = await client.getEvents("my-session", { offset: 0, limit: 50 });

        // Or stream events
        for await (const event of client.streamEvents("my-session", { offset: 0 })) {
          console.log(event.type, event.data);
        }
        ```
      </Tab>

      <Tab title="curl">
        ```bash
        # Poll for events
        curl "http://127.0.0.1:2468/v1/sessions/my-session/events?offset=0&limit=50"

        # Stream events via SSE
        curl "http://127.0.0.1:2468/v1/sessions/my-session/events/sse?offset=0"

        # Single-turn stream (post message and get streamed response)
        curl -N -X POST "http://127.0.0.1:2468/v1/sessions/my-session/messages/stream" \
          -H "Content-Type: application/json" \
          -d '{"message":"Hello"}'
        ```
      </Tab>

      <Tab title="CLI">
        ```bash
        # Poll for events
        sandbox-agent api sessions events my-session \
          --endpoint http://127.0.0.1:2468

        # Stream events via SSE
        sandbox-agent api sessions events-sse my-session \
          --endpoint http://127.0.0.1:2468

        # Single-turn stream
        sandbox-agent api sessions send-message-stream my-session \
          --message "Hello" \
          --endpoint http://127.0.0.1:2468
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Test with Inspector">
    Open the Inspector UI at `/ui/` on your server (e.g., `http://localhost:2468/ui/`) to inspect session state using a GUI.

    <Frame>
      <img src="/images/inspector.png" alt="Sandbox Agent Inspector" />
    </Frame>
  </Step>
</Steps>

## Next steps

<CardGroup cols={3}>
  <Card title="Build a Chat UI" icon="comments" href="/building-chat-ui">
    Learn how to build a chat interface for your agent.
  </Card>
  <Card title="Manage Sessions" icon="database" href="/manage-sessions">
    Persist and replay agent transcripts.
  </Card>
  <Card title="Deploy to a Sandbox" icon="box" href="/deploy">
    Deploy your agent to E2B, Daytona, or Vercel Sandboxes.
  </Card>
</CardGroup>