> ## Documentation index
> Fetch the complete documentation index at: https://upstash.com/docs/llms.txt
> Ask it with GET https://upstash.com/docs/ask?q=<keywords or question>. Short keywords rank best.
> Use these to discover all available pages before exploring further.
> Feature requests: https://upstash.com/docs/common/help/feature-requests.md lists what users asked for and how to vote for a request or add one.
> Page rating: `GET https://upstash.com/docs/feedback?path=/docs/box/guides/crabbox-setup&helpful=true` (or `false`) records whether this page helped. An optional `comment` (URL-encoded, at most 500 characters) says what was missing or wrong. It is anonymous and needs no key. Comments hold no code, secrets or personal data.

# Run Your Test Suite in a Cloud Sandbox with Crabbox

> Use the Crabbox CLI to run your test suite in a clean Upstash Box from your local machine.

[Crabbox](https://crabbox.sh) is a CLI tool that runs commands inside a remote box from your local machine. This guide shows how to use it with Upstash Box to run your test suite in a clean cloud environment without touching your local setup.

---

## 1. Install Crabbox

```bash
brew install openclaw/tap/crabbox
```

---

## 2. Get Your API Key

Go to the [Upstash Console](https://console.upstash.com) and create a Box API key. In your terminal, go to the project folder you want to test and export the key:

```bash
cd path/to/your-project
export UPSTASH_BOX_API_KEY=your_api_key_here
```

---

## 3. Warm Up a Box

Create a box with the `warmup` command. This provisions the box ahead of time so it's ready when you need it.

```bash
crabbox warmup --provider upstash-box --upstash-box-runtime node --upstash-box-size small
```

The output includes the box ID (`box=<box-id>`). Use it to run commands on this box.

You can customize the box to match your project's needs:

| Flag | Description | Values |
|---|---|---|
| `--upstash-box-runtime` | Runtime environment | `node`, `python`, `golang`, `ruby`, `rust` (or `-alpine` variants) |
| `--upstash-box-size` | Box size | `small`, `medium`, `large` |
| `--upstash-box-workdir` | Working directory inside the box | Any path (default: `/workspace/home/crabbox`) |
| `--upstash-box-keep-alive` | Keep the box up and running at all times | `true` / `false` |

---

## 4. Run Your Tests

Run your test command inside the box. Crabbox syncs your working tree into the box, runs the command, and streams the output back.

```bash
crabbox run --provider upstash-box --id <box-id> -- pnpm test
```

You can use any package manager or test runner:

```bash
# npm
crabbox run --provider upstash-box --id <box-id> -- npm test

# bun
crabbox run --provider upstash-box --id <box-id> -- bun test
```

<Tip>
Without `--id`, `crabbox run` creates a new box for that run and deletes it when the command finishes. You can skip the warmup step if you don't need to reuse a box.
</Tip>

---

## 5. Stop the Box

A warmed-up box stays up until you stop it:

```bash
crabbox stop --provider upstash-box <box-id>
```

---

For the full list of commands and options, see the [Upstash Box provider reference](https://crabbox.sh/providers/upstash-box.html).