# Running Tests with Crabbox

[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. Then export it in your terminal:

```bash
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
```

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. Use `--env-from-profile` to load environment variables from a local `.env` file — they'll be injected into the box without being stored anywhere.

```bash
crabbox run --provider upstash-box --env-from-profile .env -- pnpm test
```

You can use any package manager or test runner:

```bash
# npm
crabbox run --provider upstash-box --env-from-profile .env -- npm test

# bun
crabbox run --provider upstash-box --env-from-profile .env -- bun test
```

---

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