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

# Sixb

> Run a Sixb agent's commands in a boxd machine: a fresh machine per run, or one per conversation that hibernates between runs.

![The Sixb logo mark and wordmark inside the boxd card.](https://mintcdn.com/azin/GUvqATY0IhPdUBtf/images/boxd-x-sixb.png?fit=max\&auto=format\&n=GUvqATY0IhPdUBtf\&q=85\&s=e69b2cad38fecb96d274e932046db411)

[Sixb](https://docs.sixb.ai) is a TypeScript framework for apps and AI built on one model of your business data. Its agents run commands and work with files in a sandbox, and Sixb lets you pick the sandbox provider.

`@sixb/sandboxes-boxd` makes that sandbox a boxd machine. Each agent run gets a fresh machine that is deleted after the run. A conversation that keeps its files gets one machine per thread, which hibernates between runs with its memory and disk. The provider is part of Sixb ([pull request](https://github.com/sixb-ai/sixb/pull/1114)), and Sixb's docs list it with its [sandbox providers](https://docs.sixb.ai/sandboxes).

> [!NOTE]
>
> The provider is merged into Sixb's main branch and is not on npm yet. It ships with Sixb's next release. Until then, use it from a checkout of [sixb-ai/sixb](https://github.com/sixb-ai/sixb).

## Set up

**1. Install the provider**

In a Sixb project, with Bun 1.4.2 or later:

```bash theme={"theme":"github-dark"}
bun add @sixb/sandboxes-boxd
```

**2. Create an API key**

```bash theme={"theme":"github-dark"}
boxd auth keys create sixb-worker --org <your-org>
```

```bash .env.local theme={"theme":"github-dark"}
BOXD_API_KEY=bxd_...
```

Machines are created and billed in the key's organization. The factory reads `BOXD_API_KEY` when you don't pass `apiKey`.

**3. Add the factory to Sixb**

```ts sandbox.ts theme={"theme":"github-dark"}
import { BoxdSandboxFactory } from "@sixb/sandboxes-boxd"

export const sandboxes = new BoxdSandboxFactory({
  org: "<your-org>",
  region: "fra",
  timeout: 30_000,
})
```

Pass it as `sandboxes` to `createSixb` in `sixb.config.ts`, next to your existing storage and models.

**4. Make the Sixb API reachable**

Commands in the machine call your Sixb API server, so the API needs a public HTTPS URL. For local development, start a tunnel to the API port and pass its origin:

```bash theme={"theme":"github-dark"}
bun sixb dev --api-port 3002 --api-public-origin https://your-tunnel.example.dev
```

The agent worker adds that origin to the machine's network, installs the Sixb CLI in it, and destroys the machine after the run.

## Use a machine directly

The factory also works outside an agent run:

```ts theme={"theme":"github-dark"}
import { sandboxes } from "./sandbox"

const sandbox = await sandboxes.create()
try {
  await sandbox.writeFiles([
    { path: "hello.txt", contents: "Hello from Sixb\n" },
    { path: "scripts/run.sh", contents: "#!/bin/bash\ncat hello.txt\nuname -sm\n", mode: 0o755 },
  ])
  const result = await sandbox.runCommand("bash", ["scripts/run.sh"], { timeout: 10_000 })
  console.log(result.exitCode, result.stdout)
} finally {
  await sandbox.destroy()
}
```

```text theme={"theme":"github-dark"}
0 Hello from Sixb
Linux x86_64
```

## Keep a workspace between runs

A named sandbox is one machine. `stop()` [hibernates](https://docs.boxd.sh/guides/suspend-resume.md) it with its memory and disk, and `resume()` wakes it with its files, installed packages and running processes:

```ts theme={"theme":"github-dark"}
const sandbox = await sandboxes.create({ persistence: { name: "my-workspace" } })
await sandbox.writeFiles([{ path: "draft.txt", contents: "Work in progress" }])
await sandbox.stop()

const resumed = await sandboxes.resume("my-workspace")
console.log((await resumed.runCommand("cat", ["draft.txt"])).stdout)
await resumed.stop()
```

```text theme={"theme":"github-dark"}
Work in progress
```

Sixb's conversation sandbox bindings use this to keep a thread's workspace between runs. `destroy()` deletes the machine for good. The machine is labelled `sixb-sandbox=<name>`.

## Network

New machines reach nothing, DNS included, until you allow it:

```ts theme={"theme":"github-dark"}
const restricted = await sandboxes.create({
  network: {
    mode: "restricted",
    allow: [{ name: "sixb-api", origin: "https://api.example.com" }],
  },
})
```

| Policy | What the machine reaches |
| - | - |
| `{ mode: "none" }` (default) | Nothing, DNS included |
| `{ mode: "restricted", allow: [...] }` | Only the listed origins' hosts, through a boxd [egress allowlist](https://docs.boxd.sh/guides/egress-allowlist.md) |
| `{ mode: "all" }` | The whole internet |

The machine runs remotely, so loopback and private addresses are refused. Allow a public origin instead.

## Configuration

| Factory option | Default |
| - | - |
| `apiKey` | `BOXD_API_KEY` |
| `org` | The API key's organization |
| `region` | The API's default [region](https://docs.boxd.sh/guides/regions.md); `fra` or `nyc` |
| `size` | The organization's default; `1x4`, `2x8`, `4x16` or `8x32` (vCPU x GiB) |
| `snapshot` | boxd's default image; a [snapshot](https://docs.boxd.sh/guides/snapshots.md) needs `sudo`, `setpriv` and Bun or Node |
| `namePrefix` | `sixb-` |
| `labels` | None; added to every machine |
| `workingDirectory` | `/workspace` |
| `env` | None |
| `network` | `{ mode: "none" }` |
| `timeout` | No per-command timeout |
| `readyTimeoutMs` | `120_000` ms for a new or resumed machine to accept commands |

`create()` and `resume()` can override `workingDirectory`, `env`, `network` and `timeout`.

## What each machine gets

* **Isolation:** every machine is [isolated](https://docs.boxd.sh/use-cases/sandboxes.md#cut-off-from-your-fleet-by-design), with no route to your other machines and no boxd credentials inside.
* **An unprivileged command user:** commands run as UID 65534 without `sudo`, so `setup` can't install system packages. Put them in a snapshot and pass `snapshot`.
* **Credentials the commands can't read:** the run token for the Sixb API sits in a root-only file in the machine, and a forwarder adds it to requests to the API.
* **The default image:** Ubuntu 24.04 with Bun, Node, Python, Git and curl.
* **Cleanup:** call `destroy()` for ephemeral work. A machine left behind hibernates after its idle timeout and stays until you delete it, so set `labels` to find your workers' machines.

## Read more

* [The provider's README](https://github.com/sixb-ai/sixb/tree/main/sandboxes/boxd#readme): the full sandbox API, request credentials, and the live tests
* [Sandbox providers](https://docs.sixb.ai/sandboxes) in Sixb's docs
* [Sixb on GitHub](https://github.com/sixb-ai/sixb)
* [Sandboxes on boxd](https://docs.boxd.sh/use-cases/sandboxes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.