> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simplesandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Get started with the Sandbox SDK in minutes
## Installation
Install the Sandbox SDK using your preferred package manager:
```bash npm theme={null}
npm install @simplesandbox/sdk
```
```bash yarn theme={null}
yarn add @simplesandbox/sdk
```
```bash pnpm theme={null}
pnpm add @simplesandbox/sdk
```
```bash bun theme={null}
bun add @simplesandbox/sdk
```
## Authentication
Set your API key as an environment variable:
```bash theme={null}
export SANDBOX_API_KEY=your-api-key-here
```
Or pass it directly when initializing the client:
```typescript theme={null}
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:
```typescript theme={null}
const sandbox = await client.sandboxes.create({
image: "node:lts-alpine"
});
```
With custom timeout (defaults to 10 minutes):
```typescript theme={null}
const sandbox = await client.sandboxes.create({
image: "node:lts-alpine",
timeoutMs: 600000 // 10 minutes
});
```
### Execute Commands
Execute commands using string syntax (shell execution):
```typescript theme={null}
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:
```typescript theme={null}
const result = await sandbox.exec("npm install && npm test");
```
### Get Sandbox Info
Fetch current sandbox state:
```typescript theme={null}
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:
```typescript theme={null}
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:
```typescript theme={null}
const updated = await sandbox.refresh();
console.log(updated.state);
```
### Delete Sandbox
Clean up when you're done:
```typescript theme={null}
await sandbox.kill();
```
## Complete Example
```typescript theme={null}
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:
```typescript theme={null}
await sandbox.setTimeout(30 * 60_000); // 30 minutes
```
See [Sandbox Management](sandbox-management) for details.
### Files
Read and write files (text and binary, up to 10 MB):
```typescript theme={null}
// 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](files) for binary examples and patterns.
### Background Processes
Run servers without blocking:
```typescript theme={null}
await sandbox.exec("python server.py >/tmp/server.log 2>&1", {
background: true
});
```
See [Command Execution](command-execution) for process management.
### Exposing Services
Your server must bind to IPv6 (`::`):
```python theme={null}
# Flask
app.run(host='::', port=5000)
```
```typescript theme={null}
const host = sandbox.expose(5000);
console.log(`https://${host}`);
```
See [Networking](networking) for framework examples.
## Next Steps
Manage lifecycle, timeouts, and state
Read and write text and binary files
Run commands and background processes
Expose services via public URLs
Understand billing and costs
Common issues and solutions