harivansh-afk/sandbox-agent
1
0
Fork 0
mirror of https://github.com/harivansh-afk/sandbox-agent.git synced 2026-04-15 10:05:18 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
sandbox-agent/docs/quickstart.mdx
Nathan Flurry 82ac0b3880
chore: update skill install command to use rivet-dev/skills (#20) 
* chore: update skill install command to use rivet-dev/skills

* chore: improve skill structure per skill-creator guidelines

* chore: add bug report section and simplify description

* chore: add Discord link to bug report section
2026-01-29 06:04:07 -08:00

288 lines
8.7 KiB
Text
Raw Blame History

---
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 --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
```
</Tab>
<Tab title="npx">
Run without installing globally.
```bash
npx sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
```
</Tab>
<Tab title="npm i -g">
Install globally, then run.
```bash
npm install -g @sandbox-agent/cli
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --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 --token "$SANDBOX_TOKEN" --host 127.0.0.1 --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>
<AccordionGroup>
<Accordion title="Running without tokens">
If endpoint is not public, use `--no-token` to disable authentication. Most sandbox providers already secure their networking, so tokens are not required.
</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",
token: process.env.SANDBOX_TOKEN,
});
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 "Authorization: Bearer $SANDBOX_TOKEN" \
-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 \
--token "$SANDBOX_TOKEN"
```
</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 "Authorization: Bearer $SANDBOX_TOKEN" \
-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 \
--token "$SANDBOX_TOKEN"
```
</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" \
-H "Authorization: Bearer $SANDBOX_TOKEN"
# Stream events via SSE
curl "http://127.0.0.1:2468/v1/sessions/my-session/events/sse?offset=0" \
-H "Authorization: Bearer $SANDBOX_TOKEN"
# 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 "Authorization: Bearer $SANDBOX_TOKEN" \
-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 \
--token "$SANDBOX_TOKEN"
# Stream events via SSE
sandbox-agent api sessions events-sse my-session \
--endpoint http://127.0.0.1:2468 \
--token "$SANDBOX_TOKEN"
# Single-turn stream
sandbox-agent api sessions send-message-stream my-session \
--message "Hello" \
--endpoint http://127.0.0.1:2468 \
--token "$SANDBOX_TOKEN"
```
</Tab>
</Tabs>
</Step>
<Step title="Test with Inspector">
Open the [Inspector UI](https://inspect.sandboxagent.dev) 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>
Reference in a new issue View git blame Copy permalink