> 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.

# SDKs

Modbox provides official SDKs generated directly from the API spec. They are strongly typed and include auto-complete support in most editors.

## TypeScript / Node.js

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

```bash
yarn add modbox-sdk
```

```bash
pnpm add modbox-sdk
```

### Basic usage

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

const client = new ModboxClient({
  token: process.env.MODBOX_API_TOKEN,
});

// Provision and wait for a sandbox
const { sandboxId } = await client.provisionSandbox({
  taskId: crypto.randomUUID(),
  imageId: "your-image-id",
  ttlSeconds: 300,
  envVars: {
    OPENAI_API_KEY: process.env.OPENAI_API_KEY,
  },
});

await client.waitForSandbox({ taskId: sandboxId, timeout: 60 });

const sandbox = await client.getSandbox(sandboxId);
console.log(sandbox.sandboxUrl); // https://...
```

***

## Python

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

### Basic usage

```python
from modbox import ModboxClient
import os, uuid

client = ModboxClient(token=os.environ["MODBOX_API_TOKEN"])

task_id = str(uuid.uuid4())

# Provision
client.provision_sandbox(
    task_id=task_id,
    image_id="your-image-id",
    ttl_seconds=300,
    env_vars={"OPENAI_API_KEY": os.environ["OPENAI_API_KEY"]},
)

# Wait until running
client.wait_for_sandbox(task_id=task_id, timeout=60)

sandbox = client.get_sandbox(task_id)
print(sandbox.sandbox_url)
```

***

## REST API

You can always use the raw REST API directly. All endpoints are documented in the [API Reference](/api-reference).

```bash
# Base URL
https://api.modbox.run

# Every request needs:
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json        # for POST/PUT requests
X-Workspace-Id: your-workspace-uuid   # optional, for workspace-scoped resources
```

All SDKs are auto-generated from the OpenAPI spec using [Fern](https://buildwithfern.com). They are always in sync with the latest API version.