mirror of
https://github.com/harivansh-afk/sandbox-agent.git
synced 2026-04-15 18:01:30 +00:00
02bb992b11
* fix: fix bun install bug * refactor: consolidate executable check into assertExecutable helper - Add assertExecutable() to cli-shared that checks and attempts chmod - Simplify CLI and SDK spawn code to use the shared helper - Fix cli-shared package.json exports (.js not .mjs) - Add global install instructions to SDK error message * chore(release): update version to 0.1.6-rc.1 * fix: add cli-shared package to Dockerfiles * chore(release): update version to 0.1.6-rc.1 * fix: add cli-shared publishing to release workflow * chore(release): update version to 0.1.6-rc.1 * fix: handle already-exists error during crate publish * chore(release): update version to 0.1.6-rc.1
362 lines
11 KiB
Text
362 lines
11 KiB
Text
---
|
|
title: "Quickstart"
|
|
description: "Start the server and send your first message."
|
|
icon: "rocket"
|
|
---
|
|
|
|
<Steps>
|
|
<Step title="Install skill (optional)">
|
|
<Tabs>
|
|
<Tab title="npx">
|
|
```bash
|
|
npx skills add rivet-dev/skills -s sandbox-agent
|
|
```
|
|
</Tab>
|
|
<Tab title="bunx">
|
|
```bash
|
|
bunx skills add rivet-dev/skills -s sandbox-agent
|
|
```
|
|
</Tab>
|
|
</Tabs>
|
|
</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="bunx">
|
|
Run without installing globally.
|
|
|
|
```bash
|
|
bunx @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="bun add -g">
|
|
Install globally, then run.
|
|
|
|
```bash
|
|
bun add -g @sandbox-agent/cli
|
|
# Allow Bun to run postinstall scripts for native binaries (required for SandboxAgent.start()).
|
|
bun pm -g trust @sandbox-agent/cli-linux-x64 @sandbox-agent/cli-darwin-arm64 @sandbox-agent/cli-darwin-x64 @sandbox-agent/cli-win32-x64
|
|
sandbox-agent server --no-token --host 0.0.0.0 --port 2468
|
|
```
|
|
|
|
</Tab>
|
|
|
|
<Tab title="Node.js (local)">
|
|
For local development, use `SandboxAgent.start()` to automatically spawn and manage the server as a subprocess.
|
|
|
|
```bash
|
|
npm install sandbox-agent
|
|
```
|
|
|
|
```typescript
|
|
import { SandboxAgent } from "sandbox-agent";
|
|
|
|
const client = await SandboxAgent.start();
|
|
```
|
|
</Tab>
|
|
|
|
<Tab title="Bun (local)">
|
|
For local development, use `SandboxAgent.start()` to automatically spawn and manage the server as a subprocess.
|
|
|
|
```bash
|
|
bun add sandbox-agent
|
|
# Allow Bun to run postinstall scripts for native binaries (required for SandboxAgent.start()).
|
|
bun pm trust @sandbox-agent/cli-linux-x64 @sandbox-agent/cli-darwin-arm64 @sandbox-agent/cli-darwin-x64 @sandbox-agent/cli-win32-x64
|
|
```
|
|
|
|
```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>
|
|
|
|
<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>
|
|
</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>
|