---
title: "SDK quickstart"
description: "Register for BoxCompute, install an official SDK, run a command in a Sandbox, and clean up."
---

> Documentation Index
> Fetch the complete documentation index at: https://boxcompute.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/cli/quickstart/). For direct HTTP clients and generated tooling, see the
[HTTP API reference](/http-api).

> **Join the early-access waitlist**
>
> New customers can [join the waitlist](https://boxcompute.ai/#waitlist). If approved, BoxCompute emails a one-time invitation to register your account and receive $10 in promotional compute credit, valid for 14 days. Existing customers can sign in directly.

## 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](https://app.boxcompute.ai). Then open
[API keys](https://app.boxcompute.ai/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:

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

See [API keys](/api-keys) for scope and revocation details. Never put this server-side key in a
browser or mobile application.

## 2. Install an SDK

### TypeScript

```bash
npm install @boxcompute/sdk
npm install --save-dev tsx
```
### Python

```bash
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](/http-api#vm-browser-previews) 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.

### TypeScript

Create `quickstart.ts`:

```ts
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);
}
```

Run it with `npx tsx quickstart.ts`.
### Python

Create `quickstart.py`:

```python
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)
```

Run it with `python quickstart.py`.

`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](/execute#run-an-observable-operation).

## Next steps

- [Manage workspaces and Sandboxes](/sandboxes).
- Attribute [Sandbox compute costs](/costs) by creating API key, Sandbox, and charged run.
- Review [execution inputs and durable operations](/execute).
- Read, write, edit, rename, list, and remove [Sandbox files](/files).
- Publish one VM HTTP/WebSocket port temporarily with a [browser preview](/http-api#vm-browser-previews).
- Connect a supported agent framework with an [integration guide](/integrations/).
- Use the [HTTP API reference](/http-api) for direct HTTP clients and OpenAPI tooling.

Source: https://boxcompute.ai/docs/quickstart/index.mdx