Skip to main content
Crabbox is an open-source command-line interface (CLI) from OpenClaw. It warms a sandbox, syncs your git diff, and runs your test suite. Its Tensorlake provider uses the tensorlake CLI to create and manage the sandbox. One command runs your tests in an isolated Firecracker microVM:
tl-crabbox is a public image we publish for Crabbox. It adds a writable /workspace directory (Crabbox’s default workdir) and pnpm to the standard Ubuntu base. Crabbox manages the local workflow: config, repo claims, sync manifests, and guardrails. Tensorlake runs the microVM and transports commands. Crabbox calls tensorlake sbx create, cp, exec, and terminate for you. See Sandbox lifecycle for what happens on the Tensorlake side.

​
Prerequisites

Before you start, you need:
  • A Tensorlake account and API key. Sign up at Tensorlake Cloud.
  • A git repository. Crabbox builds its sync file list from git ls-files, so a plain directory fails with build sync file list: exit status 128.

​
Setup

Install both CLIs, set your API key, pin the tl-crabbox image, then warm a sandbox and run your tests.
1

Install Crabbox and the Tensorlake CLI

Without Homebrew, download a release archive from Crabbox’s GitHub releases. The tensorlake CLI must be on your PATH. If it isn’t, pass its location with --tensorlake-cli.
2

Set your API key

Crabbox passes the key to the CLI through the environment, so it never appears on the command line. The key also selects the project. If you prefer, run tl login first. Crabbox then uses the CLI’s stored Personal Access Token and selected project.
3

Configure the provider

Add a .crabbox.yaml at your repo root:
With the image pinned here, every run and warmup uses it, and you don’t retype --tensorlake-image.
Don’t skip the image line. Crabbox’s default workdir is /workspace/crabbox. In Tensorlake’s standard images, commands run as tl-user, which can’t create /workspace. Without the pin, every run fails with tensorlake exec "mkdir -p '/workspace/crabbox'" exited 1. To use a standard image instead, set tensorlake.workdir: /home/tl-user/crabbox.
4

Warm up a sandbox

Crabbox creates a named sandbox and prints a slug such as harbor-barnacle. Pass --id harbor-barnacle on later runs to reuse it. Every tensorlake.* config field has a matching --tensorlake-* flag and a CRABBOX_TENSORLAKE_* environment variable.
5

Run your tests

Crabbox syncs your git-tracked files into the sandbox and streams output back as the command runs. For shell pipelines, use --shell:
tl-crabbox includes node, npm, pnpm, corepack, python3, and git. If your suite needs other tools, register your own image with tensorlake sbx image create and pin it in tensorlake.image. To forward secrets from your shell, allowlist them with --allow-env API_TOKEN. Crabbox injects the values for the command and removes them afterward.
6

Release the sandbox

One-off runs lease a sandbox and terminate it when the command exits. Warmed sandboxes stay alive until you release them:
Add --keep-on-failure to a run to keep the sandbox alive after a failing command.

​
Troubleshooting

The 3 errors below come from a missing git repository, an unwritable workdir, or a missing binary in the image. For every flag, caveat, and lifecycle detail, see Crabbox’s Tensorlake provider reference.