[ sandbox api · rest + sdk ]
The sandbox API for running AI-generated and untrusted code
Create an isolated Linux sandbox, run a command, stream its output, move files, expose an authenticated preview, and collect the artifacts you care about. One REST API, with typed SDK and CLI clients on top.
[ the surface ]
Six resources, one HTTP API
Sandboxes
Create an isolated environment from a template. It gets a /workspace, a TTL, and nothing it did not ask for.
POST /v1/sandboxesCommands
Run or stream any process. Exit codes, stdout, stderr, and cancellation are recorded as Command records.
POST /v1/sandboxes/{id}/commandsFiles
Read, write, upload, and move files inside /workspace. Large reads and writes use staged signed URLs.
PUT /v1/sandboxes/{id}/filesPreviews
Expose a port as an authenticated URL. One active Preview per sandbox and port in the first beta.
POST /v1/sandboxes/{id}/previewsArtifacts
Promote the outputs that matter into durable, indexed storage that outlives the sandbox.
GET /v1/sandboxes/{id}/artifactsScoped keys
Issue API keys with singular resource:action scopes, optionally restricted to a project. Keys cannot mint keys.
x-api-key: cn_live_…[ end to end ]
A request, from create to kill
The SDK is a thin client over the REST API. The same calls exist as raw HTTP and as CLI commands, so you can prototype in a terminal and ship the same flow in production.
import { createCrowNestClient } from "@crownest/sdk";
const client = createCrowNestClient(); // reads CROWNEST_API_KEY
const sandbox = await client.sandboxes.create({ template: "python" });
const result = await sandbox.commands.run("python3 main.py", {
collect: [{ path: "/workspace/report.html", name: "report.html" }],
onStdout: (chunk) => process.stdout.write(chunk),
});
console.log(result.exitCode);
await sandbox.kill();[ production ]
Made to put in front of real traffic
Per-second metering
Usage is metered in compute_unit_seconds and pinned to your pricing version, so short sandboxes cost less.
Idempotency keys
Retry a create or run with the same key and get the same result for 24 hours instead of double work.
Scoped credentials
API keys carry singular resource:action scopes and can be restricted to a single project.
Audit events
Every create, run, revoke, and kill is recorded, tombstones included, so you can reconstruct a run.
[ questions ]
Sandbox API FAQ
- What is a sandbox API?
- A sandbox API lets your code create isolated Linux environments on demand and control them over HTTP. With CrowNest you call one endpoint to create a sandbox, then run commands, read and write files in /workspace, expose a preview, and collect artifacts before the sandbox is torn down.
- Which languages can I run in a sandbox?
- Anything that runs on Linux. A command is just a process, so you can run Python, Node, shell scripts, or compiled binaries. The starting environment comes from a template you pick at create time.
- How is the sandbox API billed?
- Compute is metered in compute_unit_seconds and billed per second of sandbox runtime, so an idle or short-lived sandbox costs less. The free tier starts with a one-time $10 credit and no card.
- Can I expose a web server running inside a sandbox?
- Yes. Create a Preview for a port and CrowNest returns an authenticated URL on preview.crownest.dev. Access requires an API key or a token-mode browser session; there are no public unauthenticated preview links in v1.
- Are mutating requests safe to retry?
- Yes. Mutating requests accept a Stripe-style idempotency key, so a retried create or run resolves to the same result for 24 hours instead of doing the work twice.
Put a sandbox behind your next endpoint
Start with the free $10 credit. No card, no sales call: create a sandbox and run your first command in minutes.