SDK quickstart

Use the official SDK for application integrations. It handles authentication, typed API responses, binary file transfer, timeouts, cancellation, and structured errors for the public v2 API.

If you want to use BoxCompute from a terminal or a local coding agent, follow the CLI quickstart. For direct HTTP clients and generated tooling, see the HTTP API reference.

1. Register and create an API key

After approval, open the invitation link from your email, create your account, and sign in to the BoxCompute app. Then open API keys, create a key, and include workspace:create, sandbox:read, sandbox:create, sandbox:execute, and sandbox:delete.

Copy the bc_live_... secret immediately—it is displayed only once—and store it in your secret manager. For this local walkthrough:

read -rsp 'BoxCompute API key: ' BOXCOMPUTE_API_KEY && echo
export BOXCOMPUTE_API_KEY

See API keys for scope and revocation details. Never put this server-side key in a browser or mobile application.

2. Install an SDK

npm install @boxcompute/sdk
npm install --save-dev tsx

python -m pip install boxcompute

Both packages use https://api.boxcompute.ai by default. You do not need to build route URLs or authorization headers yourself.

New Sandboxes are VM-only: omit vmSandbox or send true. Sending false returns 400 INVALID_REQUEST; there is no fallback to gVisor. Operator-selected cooperative SSH and the selected-TCP access routes are not exposed by the current SDKs. The same is true of one-hour VM browser-preview controls; use the direct HTTP contract for those.

3. Create, execute, and clean up

The examples reuse the account’s first workspace or bootstrap one when the account is empty. Workspaces are persistent parents and are not deleted. Each example creates one Sandbox and deletes that exact instance in a finally block.

import { randomUUID } from "node:crypto";
import { BoxCompute } from "@boxcompute/sdk";

const apiKey = process.env.BOXCOMPUTE_API_KEY;
if (!apiKey) throw new Error("BOXCOMPUTE_API_KEY is required");

const boxcompute = new BoxCompute({ apiKey });
const [existingWorkspace] = await boxcompute.workspaces.list();
const workspace = existingWorkspace ?? await boxcompute.workspaces.create({
  name: "SDK quickstart",
  idempotencyKey: "sdk-quickstart-workspace-v1",
});

const sandbox = await boxcompute.sandboxes.create({
  workspaceId: workspace.id,
  name: "SDK quickstart",
  idempotencyKey: randomUUID(),
});

try {
  const result = await boxcompute.sandboxes.execute(sandbox.id, {
    argv: ["python3", "-c", "print(sum(range(100000)))"],
    cwd: "/workspace",
    timeoutSeconds: 120,
    maxOutputBytes: 262_144,
  });
  console.log(result.stdout);
  if (result.stderr) console.error(result.stderr);
  process.exitCode = result.exitCode;
} finally {
  await boxcompute.sandboxes.delete(sandbox.id);
}

import os
import sys
import uuid

from boxcompute import BoxCompute

with BoxCompute(api_key=os.environ["BOXCOMPUTE_API_KEY"]) as boxcompute:
    workspaces = boxcompute.workspaces.list()
    workspace = (
        workspaces[0]
        if workspaces
        else boxcompute.workspaces.create(
            name="SDK quickstart",
            idempotency_key="sdk-quickstart-workspace-v1",
        )
    )
    sandbox = boxcompute.sandboxes.create(
        workspace_id=workspace.id,
        name="SDK quickstart",
        idempotency_key=str(uuid.uuid4()),
    )
    try:
        result = boxcompute.sandboxes.execute(
            sandbox.id,
            argv=["python3", "-c", "print(sum(range(100000)))"],
            cwd="/workspace",
        )
        print(result.stdout, end="")
        if result.stderr:
            print(result.stderr, end="", file=sys.stderr)
    finally:
        boxcompute.sandboxes.delete(sandbox.id)

execute waits for completion and returns stdout, stderr, exit status, timeout, and truncation fields. A non-zero command exit is still a successful API response, so inspect exitCode / exit_code rather than treating it as a transport error.

For commands that must remain observable across an interrupted connection, use durable operations.

Next steps

• Manage workspaces and Sandboxes.
• Attribute Sandbox compute costs by creating API key, Sandbox, and charged run.
• Review execution inputs and durable operations.
• Read, write, edit, rename, list, and remove Sandbox files.
• Publish one VM HTTP/WebSocket port temporarily with a browser preview.
• Connect a supported agent framework with an integration guide.
• Use the HTTP API reference for direct HTTP clients and OpenAPI tooling.