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

# Run Your Test Suite with Crabbox

> Crabbox's Tensorlake provider drops any command into a Firecracker microVM — warm a sandbox, sync your working tree, and run your tests with one command.

[Crabbox](https://crabbox.sh) is an open-source CLI from OpenClaw whose whole loop is *warm a box, sync the diff, run the suite*. Its [Tensorlake provider](https://crabbox.sh/providers/tensorlake.html) delegates the sandbox to the `tensorlake` CLI, so one command puts your test run in an isolated Firecracker microVM:

```sh theme={null}
crabbox run --provider tensorlake --tensorlake-image tl-crabbox -- pnpm test
```

`tl-crabbox` is a public image we publish for Crabbox — the standard Ubuntu base plus a writable `/workspace` (Crabbox's default workdir) and pnpm preinstalled.

Crabbox owns the local workflow — config, repo claims, sync manifests, and guardrails. Tensorlake owns the microVM and command transport: under the hood, Crabbox shells out to `tensorlake sbx create`, `cp`, `exec`, and `terminate`. See [Sandbox lifecycle](/sandboxes/lifecycle) for what happens on the Tensorlake side.

## Prerequisites

* A Tensorlake account and API key — sign up at [cloud.tensorlake.ai](https://cloud.tensorlake.ai).
* Run Crabbox from inside a git repository. It builds its sync file list from `git ls-files`, so a plain directory fails with `build sync file list: exit status 128`.

## Setup

<Steps>
  <Step title="Install Crabbox and the Tensorlake CLI">
    ```sh theme={null}
    brew install openclaw/tap/crabbox
    curl -fsSL https://tensorlake.ai/install | sh
    ```

    No Homebrew? Grab a release archive from [Crabbox's GitHub releases](https://github.com/openclaw/crabbox/releases). The `tensorlake` CLI must be on your `PATH`, or point Crabbox at it with `--tensorlake-cli`.
  </Step>

  <Step title="Set your API key">
    ```sh theme={null}
    export TENSORLAKE_API_KEY=tl_apiKey_...
    ```

    Crabbox passes the key to the CLI through the environment — it never appears on the command line. If your account spans multiple organizations or projects, also set `TENSORLAKE_ORGANIZATION_ID` and `TENSORLAKE_PROJECT_ID`.
  </Step>

  <Step title="Configure the provider">
    Add a `.crabbox.yaml` at your repo root:

    ```yaml theme={null}
    provider: tensorlake
    tensorlake:
      image: tl-crabbox
    ```

    Pinning `tl-crabbox` here means every run and warmup picks it up — no `--tensorlake-image` flag to retype.

    <Warning>
      The `image` line matters. Crabbox's default workdir is `/workspace/crabbox`, and in Tensorlake's standard images commands run as `tl-user`, which cannot create `/workspace` — without the pin, every run fails with `tensorlake exec "mkdir -p '/workspace/crabbox'" exited 1`. Prefer a standard image anyway? Set `tensorlake.workdir: /home/tl-user/crabbox` instead.
    </Warning>
  </Step>

  <Step title="Warm up a sandbox">
    ```sh theme={null}
    crabbox warmup --provider tensorlake --tensorlake-cpus 2 --tensorlake-memory-mb 2048
    ```

    Crabbox creates a named sandbox and prints a friendly slug (like `harbor-barnacle`) you can reuse across runs with `--id <slug>`. Every `tensorlake.*` config field has a matching `--tensorlake-*` flag and `CRABBOX_TENSORLAKE_*` environment override.
  </Step>

  <Step title="Run your tests">
    ```sh theme={null}
    crabbox run --provider tensorlake -- pnpm test
    ```

    Crabbox syncs your **git-tracked files** into the sandbox and streams output back as the command runs. For shell pipelines, use `--shell`:

    ```sh theme={null}
    crabbox run --provider tensorlake --shell 'pnpm install && pnpm test'
    ```

    `tl-crabbox` ships with `node`, `npm`, `pnpm`, `corepack`, `python3`, and `git`. Need more toolchain? Register your own image with [`tensorlake sbx image create`](/sandboxes/images) and pin it via `tensorlake.image` instead. To forward secrets from your shell, allowlist them with `--allow-env API_TOKEN` — values are injected for the command and removed after.
  </Step>

  <Step title="Release the sandbox">
    One-off runs lease a sandbox and terminate it automatically. Warmed sandboxes stick around until you release them:

    ```sh theme={null}
    crabbox stop --provider tensorlake harbor-barnacle
    ```

    Add `--keep-on-failure` to a run to keep the sandbox alive after a failing command.
  </Step>
</Steps>

## Troubleshooting

| Error                                                             | Cause                                                                                                                              | Fix                                                                                                                    |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `build sync file list: exit status 128`                           | You're not inside a git repository — Crabbox builds its sync list from `git ls-files`.                                             | Run from a repo root (`git init` if needed).                                                                           |
| `tensorlake exec "mkdir -p '/workspace/crabbox'" exited 1`        | The default workdir isn't writable by `tl-user` in Tensorlake's standard images.                                                   | Set `tensorlake.image: tl-crabbox` in `.crabbox.yaml` (or override `tensorlake.workdir` to `/home/tl-user/crabbox`).   |
| `Failed to spawn process in <workdir>: No such file or directory` | The command's executable (e.g. `pnpm`) isn't in the sandbox image — the message blames the directory, but it's the missing binary. | Pin `tl-crabbox` (ships pnpm), use a tool the image has (`npm`, `corepack`), or register an image with your toolchain. |

For every flag, gotcha, and lifecycle detail, see [Crabbox's Tensorlake provider reference](https://crabbox.sh/providers/tensorlake.html).