Skip to main content

​
Installation

Install the Sandbox SDK using your preferred package manager: 
npm install @simplesandbox/sdk

​
Authentication

Set your API key as an environment variable: 
export SANDBOX_API_KEY=your-api-key-here
Or pass it directly when initializing the client: 
import { Sandbox } from "@simplesandbox/sdk";

const client = Sandbox({
  apiKey: "your-api-key-here"
});

​
Basic Usage

​
Create a Sandbox

Create a new sandbox with a Docker image: 
const sandbox = await client.sandboxes.create({
  image: "node:lts-alpine"
});
With custom timeout (defaults to 10 minutes): 
const sandbox = await client.sandboxes.create({
  image: "node:lts-alpine",
  timeoutMs: 600000 // 10 minutes
});

​
Execute Commands

Execute commands using string syntax (shell execution): 
const result = await sandbox.exec("echo 'Hello World'");
console.log(result.stdout); // "Hello World\n"
console.log(result.exitCode); // 0
Commands support shell features like pipes, variables, and globs: 
const result = await sandbox.exec("npm install && npm test");

​
Get Sandbox Info

Fetch current sandbox state: 
const info = await sandbox.info();
console.log(info.state); // "started"
console.log(info.name); // "sandbox-node-1"

​
List Sandboxes

List all sandboxes in your organization: 
const sandboxes = await client.sandboxes.list();
for (const sb of sandboxes) {
  console.log(`${sb.id}: ${sb.data.state}`);
}

​
Refresh State

Refresh sandbox data from the server: 
const updated = await sandbox.refresh();
console.log(updated.state);

​
Delete Sandbox

Clean up when you’re done: 
await sandbox.kill();

​
Complete Example

import { Sandbox } from "@simplesandbox/sdk";

const client = Sandbox();

// Create sandbox
const sandbox = await client.sandboxes.create({
  image: "node:lts-alpine"
});

// Execute commands
const result = await sandbox.exec("node --version");
console.log(result.stdout); // v20.x.x

// Clean up
await sandbox.kill();

​
Key Concepts

​
Timeouts

Sandboxes auto-stop after 10 minutes by default. Extend the timeout: 
await sandbox.setTimeout(30 * 60_000); // 30 minutes
See Sandbox Management for details.

​
Files

Read and write files (text and binary, up to 10 MB): 
// Write
await sandbox.files.write("/app/config.json", JSON.stringify({ key: "value" }));

// Read
const content = await sandbox.files.read("/app/config.json");
See File Operations for binary examples and patterns.

​
Background Processes

Run servers without blocking: 
await sandbox.exec("python server.py >/tmp/server.log 2>&1", {
  background: true
});
See Command Execution for process management.

​
Exposing Services

Your server must bind to IPv6 (::): 
# Flask
app.run(host='::', port=5000)

const host = sandbox.expose(5000);
console.log(`https://${host}`);
See Networking for framework examples.

​
Next Steps

Sandbox Management

Manage lifecycle, timeouts, and state

File Operations

Read and write text and binary files

Command Execution

Run commands and background processes

Networking

Expose services via public URLs

Pricing

Understand billing and costs

Troubleshooting

Common issues and solutions