> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.modbox.run/llms.txt.
> For full documentation content, see https://docs.modbox.run/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.modbox.run/_mcp/server.

# Quickstart

This guide takes you from zero to a running sandbox using the Modbox SDK or REST API.

## 1. Get your API token

Go to the [Modbox dashboard](https://app.modbox.run) → **Settings → API Tokens** and create a new token.

Keep your token safe. It grants full access to your workspaces and sandboxes.

## 2. Install the SDK

```bash
npm install modbox-sdk
```

```bash
pip install modbox-sdk
```

## 3. Provision a sandbox

```typescript
import { ModboxClient } from "modbox-sdk";

const client = new ModboxClient({ token: "YOUR_API_TOKEN" });

// Provision a sandbox
const { sandboxId } = await client.provisionSandbox({
  taskId: "my-first-sandbox",
});

// Wait until it's running
const sandbox = await client.waitForSandbox({ taskId: "my-first-sandbox" });

console.log("Sandbox is live at:", sandbox.sandboxUrl);
// → https://my-first-sandbox.sandbox.modbox.run
```

```python
from modbox import ModboxClient

client = ModboxClient(token="YOUR_API_TOKEN")

# Provision a sandbox
result = client.provision_sandbox(task_id="my-first-sandbox")

# Wait until it's running
sandbox = client.wait_for_sandbox(task_id="my-first-sandbox")

print("Sandbox is live at:", sandbox.sandbox_url)
# → https://my-first-sandbox.sandbox.modbox.run
```

```bash
# Provision
curl -X POST https://api.modbox.run/sandboxes/provision \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task_id": "my-first-sandbox"}'

# Poll until running
curl https://api.modbox.run/sandboxes/detail/{sandbox_id} \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## 4. Interact with the sandbox

Once `status` is `running`, the `sandbox_url` field contains a live HTTPS endpoint. What you can do depends on the image — a browser sandbox exposes CDP, a code execution sandbox exposes an HTTP API, etc.

```typescript
// Example: call a REST endpoint inside the sandbox
const response = await fetch(`${sandbox.sandboxUrl}/execute`, {
  method: "POST",
  body: JSON.stringify({ code: "print('hello world')", language: "python" }),
});
```

## 5. Destroy the sandbox

Always clean up after you're done, or set a TTL so it's automatic.

```typescript
await client.destroySandbox({ taskId: "my-first-sandbox" });
```

```python
client.destroy_sandbox(task_id="my-first-sandbox")
```

## Next steps

See real-world patterns for AI agents, browser automation and more

Bring your own Docker image or use a pre-built Modbox image

Organize sandboxes and invite your team

Full endpoint reference with live explorer