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 → Settings → API Tokens and create a new token.

2. Install the SDK

$
npm install modbox-sdk

3. Provision a sandbox

1
import { ModboxClient } from "modbox-sdk";
2
3
const client = new ModboxClient({ token: "YOUR_API_TOKEN" });
4
5
// Provision a sandbox
6
const { sandboxId } = await client.provisionSandbox({
7
  taskId: "my-first-sandbox",
8
});
9
10
// Wait until it's running
11
const sandbox = await client.waitForSandbox({ taskId: "my-first-sandbox" });
12
13
console.log("Sandbox is live at:", sandbox.sandboxUrl);
14
// → https://my-first-sandbox.sandbox.modbox.run

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.

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

5. Destroy the sandbox

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

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

Next steps