SDKs | Modbox | Documentation

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

npm install modbox-sdk

Basic usage

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

pip install modbox-sdk

Basic usage

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.

# 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. They are always in sync with the latest API version.