Crabbox 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#
2. Get Your API Key#
Go to the Upstash Console and create a Box API key. In your terminal, go to the project folder you want to test and export the key:
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.
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.
You can use any package manager or test runner:
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.
5. Stop the Box#
A warmed-up box stays up until you stop it:
For the full list of commands and options, see the Upstash Box provider reference.