harivansh-afk/sandbox-agent
1
0
Fork 0
mirror of https://github.com/harivansh-afk/sandbox-agent.git synced 2026-04-16 22:03:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add Modal and ComputeSDK built-in providers, update examples and docs

Browse source 
- Add `sandbox-agent/modal` provider using Modal SDK with node:22-slim image
- Add `sandbox-agent/computesdk` provider using ComputeSDK's unified sandbox API
- Update Modal and ComputeSDK examples to use new SDK providers
- Update Modal and ComputeSDK deploy docs with provider-based examples
- Add Modal to quickstart CodeGroup and docs.json navigation
- Add provider test entries for Modal and ComputeSDK
- Remove old standalone example files (modal.ts, computesdk.ts)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Nathan Flurry 2026-03-15 14:45:52 -07:00
parent 441083ea2a
commit 20202c45ee
18 changed files with 377 additions and 646 deletions
Download patch file Download diff file Expand all files Collapse all files

212
docs/deploy/computesdk.mdx
View file

@ -1,160 +1,61 @@
---
title: "ComputeSDK"
description: "Deploy the daemon using ComputeSDK's provider-agnostic sandbox API."
description: "Deploy Sandbox Agent using ComputeSDK's provider-agnostic sandbox API."
---
[ComputeSDK](https://computesdk.com) provides a unified interface for managing sandboxes across multiple providers. Write once, deploy anywhere—switch providers by changing environment variables.
[ComputeSDK](https://computesdk.com) provides a unified interface for managing sandboxes across multiple providers. Write once, deploy anywhere by changing environment variables.
## Prerequisites
- `COMPUTESDK_API_KEY` from [console.computesdk.com](https://console.computesdk.com)
- Provider API key (one of: `E2B_API_KEY`, `DAYTONA_API_KEY`, `VERCEL_TOKEN`, `MODAL_TOKEN_ID` + `MODAL_TOKEN_SECRET`, `BLAXEL_API_KEY`, `CSB_API_KEY`)
- `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` for the coding agents
- `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
## TypeScript Example
## TypeScript example
```bash
npm install sandbox-agent@0.3.x computesdk
```
```typescript
import {
compute,
detectProvider,
getMissingEnvVars,
getProviderConfigFromEnv,
isProviderAuthComplete,
isValidProvider,
PROVIDER_NAMES,
type ExplicitComputeConfig,
type ProviderName,
} from "computesdk";
import { SandboxAgent } from "sandbox-agent";
import { computesdk } from "sandbox-agent/computesdk";
const PORT = 3000;
const REQUEST_TIMEOUT_MS =
Number.parseInt(process.env.COMPUTESDK_TIMEOUT_MS || "", 10) || 120_000;
/**
* Detects and validates the provider to use.
* Priority: COMPUTESDK_PROVIDER env var > auto-detection from API keys
*/
function resolveProvider(): ProviderName {
const providerOverride = process.env.COMPUTESDK_PROVIDER;
if (providerOverride) {
if (!isValidProvider(providerOverride)) {
throw new Error(
`Unsupported provider "${providerOverride}". Supported: ${PROVIDER_NAMES.join(", ")}`
);
}
if (!isProviderAuthComplete(providerOverride)) {
const missing = getMissingEnvVars(providerOverride);
throw new Error(
`Missing credentials for "${providerOverride}". Set: ${missing.join(", ")}`
);
}
return providerOverride as ProviderName;
}
const detected = detectProvider();
if (!detected) {
throw new Error(
`No provider credentials found. Set one of: ${PROVIDER_NAMES.map((p) => getMissingEnvVars(p).join(", ")).join(" | ")}`
);
}
return detected as ProviderName;
}
function configureComputeSDK(): void {
const provider = resolveProvider();
const config: ExplicitComputeConfig = {
provider,
computesdkApiKey: process.env.COMPUTESDK_API_KEY,
requestTimeoutMs: REQUEST_TIMEOUT_MS,
};
// Add provider-specific config from environment
const providerConfig = getProviderConfigFromEnv(provider);
if (Object.keys(providerConfig).length > 0) {
(config as any)[provider] = providerConfig;
}
compute.setConfig(config);
}
configureComputeSDK();
// Build environment variables to pass to sandbox
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;
// Create sandbox
const sandbox = await compute.sandbox.create({
envs: Object.keys(envs).length > 0 ? envs : undefined,
const sdk = await SandboxAgent.start({
sandbox: computesdk({
create: { envs },
}),
});
// Helper to run commands with error handling
const run = async (cmd: string, options?: { background?: boolean }) => {
const result = await sandbox.runCommand(cmd, options);
if (typeof result?.exitCode === "number" && result.exitCode !== 0) {
throw new Error(`Command failed: ${cmd} (exit ${result.exitCode})\n${result.stderr || ""}`);
}
return result;
};
// Install sandbox-agent
await run("curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh");
// Install agents conditionally based on available API keys
if (envs.ANTHROPIC_API_KEY) {
await run("sandbox-agent install-agent claude");
try {
const session = await sdk.createSession({ agent: "claude" });
const response = await session.prompt([
{ type: "text", text: "Summarize this repository" },
]);
console.log(response.stopReason);
} finally {
await sdk.destroySandbox();
}
if (envs.OPENAI_API_KEY) {
await run("sandbox-agent install-agent codex");
}
// Start the server in the background
await run(`sandbox-agent server --no-token --host 0.0.0.0 --port ${PORT}`, { background: true });
// Get the public URL for the sandbox
const baseUrl = await sandbox.getUrl({ port: PORT });
// Wait for server to be ready
const deadline = Date.now() + REQUEST_TIMEOUT_MS;
while (Date.now() < deadline) {
try {
const response = await fetch(`${baseUrl}/v1/health`);
if (response.ok) {
const data = await response.json();
if (data?.status === "ok") break;
}
} catch {
// Server not ready yet
}
await new Promise((r) => setTimeout(r, 500));
}
// Connect to the server
const client = await SandboxAgent.connect({ baseUrl });
// Detect which agent to use based on available API keys
const agent = envs.ANTHROPIC_API_KEY ? "claude" : "codex";
// Create a session and start coding
await client.createSession("my-session", { agent });
await client.postMessage("my-session", {
message: "Summarize this repository",
});
for await (const event of client.streamEvents("my-session")) {
console.log(event.type, event.data);
}
// Cleanup
await sandbox.destroy();
```
## Supported Providers
The `computesdk` provider handles sandbox creation, Sandbox Agent installation, agent setup, and server startup automatically. ComputeSDK routes to your configured provider behind the scenes.
Before calling `SandboxAgent.start()`, configure ComputeSDK with your provider:
```typescript
import { compute } from "computesdk";
compute.setConfig({
provider: "e2b", // or auto-detect via detectProvider()
computesdkApiKey: process.env.COMPUTESDK_API_KEY,
});
```
## Supported providers
ComputeSDK auto-detects your provider from environment variables:
@ -169,46 +70,7 @@ ComputeSDK auto-detects your provider from environment variables:
## Notes
- **Provider resolution order**: `COMPUTESDK_PROVIDER` env var takes priority, otherwise auto-detection from API keys.
- **Conditional agent installation**: Only agents with available API keys are installed, reducing setup time.
- **Command error handling**: The example validates exit codes and throws on failures for easier debugging.
- **Provider resolution**: Set `COMPUTESDK_PROVIDER` to force a specific provider, or let ComputeSDK auto-detect from API keys.
- `sandbox.runCommand(..., { background: true })` keeps the server running while your app continues.
- `sandbox.getUrl({ port })` returns a public URL for the sandbox port.
- Always destroy the sandbox when you are done to avoid leaking resources.
- If sandbox creation times out, set `COMPUTESDK_TIMEOUT_MS` to a higher value (default: 120000ms).
## Explicit Provider Selection
To force a specific provider instead of auto-detection, set the `COMPUTESDK_PROVIDER` environment variable:
```bash
export COMPUTESDK_PROVIDER=e2b
```
Or configure programmatically using `getProviderConfigFromEnv()`:
```typescript
import { compute, getProviderConfigFromEnv, type ExplicitComputeConfig } from "computesdk";
const config: ExplicitComputeConfig = {
provider: "e2b",
computesdkApiKey: process.env.COMPUTESDK_API_KEY,
requestTimeoutMs: 120_000,
};
// Automatically populate provider-specific config from environment
const providerConfig = getProviderConfigFromEnv("e2b");
if (Object.keys(providerConfig).length > 0) {
(config as any).e2b = providerConfig;
}
compute.setConfig(config);
```
## Direct Mode (No ComputeSDK API Key)
To bypass the ComputeSDK gateway and use provider SDKs directly, see the provider-specific examples:
- [E2B](/deploy/e2b)
- [Daytona](/deploy/daytona)
- [Vercel](/deploy/vercel)
- Always destroy the sandbox when done to avoid leaking resources.

109
docs/deploy/modal.mdx
View file

@ -10,88 +10,43 @@ description: "Deploy Sandbox Agent inside a Modal sandbox."
## TypeScript example
```typescript
import { ModalClient } from "modal";
import { SandboxAgent } from "sandbox-agent";
const modal = new ModalClient();
const app = await modal.apps.fromName("sandbox-agent", { createIfMissing: true });
const image = modal.images
.fromRegistry("ubuntu:22.04")
.dockerfileCommands([
"RUN apt-get update && apt-get install -y curl ca-certificates",
"RUN curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh",
]);
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 secrets = Object.keys(envs).length > 0
? [await modal.secrets.fromObject(envs)]
: [];
const sb = await modal.sandboxes.create(app, image, {
encryptedPorts: [3000],
secrets,
});
const exec = async (cmd: string) => {
const p = await sb.exec(["bash", "-c", cmd], { stdout: "pipe", stderr: "pipe" });
const exitCode = await p.wait();
if (exitCode !== 0) {
const stderr = await p.stderr.readText();
throw new Error(`Command failed (exit ${exitCode}): ${cmd}\n${stderr}`);
}
};
await exec("sandbox-agent install-agent claude");
await exec("sandbox-agent install-agent codex");
await sb.exec(
["bash", "-c", "sandbox-agent server --no-token --host 0.0.0.0 --port 3000 &"],
);
const tunnels = await sb.tunnels();
const baseUrl = tunnels[3000].url;
const sdk = await SandboxAgent.connect({ baseUrl });
const session = await sdk.createSession({ agent: "claude" });
const off = session.onEvent((event) => {
console.log(event.sender, event.payload);
});
await session.prompt([{ type: "text", text: "Summarize this repository" }]);
off();
await sb.terminate();
```bash
npm install sandbox-agent@0.3.x modal
```
```typescript
import { SandboxAgent } from "sandbox-agent";
import { modal } from "sandbox-agent/modal";
const secrets: Record<string, string> = {};
if (process.env.ANTHROPIC_API_KEY) secrets.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
if (process.env.OPENAI_API_KEY) secrets.OPENAI_API_KEY = process.env.OPENAI_API_KEY;
const sdk = await SandboxAgent.start({
sandbox: modal({
create: { secrets },
}),
});
try {
const session = await sdk.createSession({ agent: "claude" });
const response = await session.prompt([
{ type: "text", text: "Summarize this repository" },
]);
console.log(response.stopReason);
} finally {
await sdk.destroySandbox();
}
```
The `modal` provider handles app creation, image building, sandbox provisioning, agent installation, server startup, and tunnel networking automatically.
## Faster cold starts
Modal caches image layers, so the `dockerfileCommands` that install `curl` and `sandbox-agent` only run on the first build. Subsequent sandbox creates reuse the cached image.
## Running the test
The example includes a health-check test. First, build the SDK:
```bash
pnpm --filter sandbox-agent build
```
Then run the test with your Modal credentials:
```bash
MODAL_TOKEN_ID=<your-token-id> MODAL_TOKEN_SECRET=<your-token-secret> npx vitest run
```
Run from `examples/modal/`. The test will skip if credentials are not set.
Modal caches image layers, so the Dockerfile commands that install `curl` and `sandbox-agent` only run on the first build. Subsequent sandbox creates reuse the cached image.
## Notes
- Modal sandboxes use [gVisor](https://gvisor.dev/) for strong isolation.
- Ports are exposed via encrypted tunnels (`encryptedPorts`). Use `sb.tunnels()` to get the public HTTPS URL.
- Environment variables (API keys) are passed as Modal [Secrets](https://modal.com/docs/guide/secrets) rather than plain env vars for security.
- Always call `sb.terminate()` when done to avoid leaking sandbox resources.
- Ports are exposed via encrypted tunnels (`encryptedPorts`). The provider uses `sb.tunnels()` to get the public HTTPS URL.
- Environment variables (API keys) are passed as Modal [Secrets](https://modal.com/docs/guide/secrets) for security.

1
docs/docs.json
View file

@ -63,6 +63,7 @@
"deploy/vercel",
"deploy/cloudflare",
"deploy/docker",
"deploy/modal",
"deploy/boxlite",
"deploy/computesdk"
]

17
docs/quickstart.mdx
View file

@ -86,6 +86,23 @@ icon: "rocket"
});
```
```typescript Modal
import { SandboxAgent } from "sandbox-agent";
import { modal } from "sandbox-agent/modal";
const sdk = await SandboxAgent.start({
sandbox: modal({
create: {
// Pass whichever keys your agent needs
secrets: {
ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
OPENAI_API_KEY: process.env.OPENAI_API_KEY,
},
},
}),
});
```
```typescript Cloudflare
import { SandboxAgent } from "sandbox-agent";
import { cloudflare } from "sandbox-agent/cloudflare";