Quickstart

In about five minutes you'll install the CLI, sign in, start a full Ubuntu VM, run commands in it, move files, open a port, run an agent, stop and resume it, fork it, and clean up. Then you'll do the same from code. Every command on this page is run by HareBox's test suite against a live server.

You need a HareBox account with a plan, or the 7-day trial. The trial needs a card, charges nothing until day 7, and includes 25 hours of machine time. See Pricing and Free trial.

On Linux or macOS:

curl -fsSL https://harebox.com/install.sh | sh

The installer picks the build for your system, checks that HareBox signed it before installing anything, and puts harebox in ~/.local/bin without root. Set HAREBOX_INSTALL_DIR to install somewhere else, or HAREBOX_VERSION to pin a version. On Windows, download harebox_windows_amd64.zip from harebox.com/releases.

The installer and harebox self-update check that HareBox signed the release before anything is installed. The list of SHA-256 sums is signed with HareBox's release key (OpenSSH signature format, checked with ssh-keygen -Y verify), and so is the pointer to the latest version. The CLI never moves to an older release unless you pass --version. Set HAREBOX_SKIP_SIGNATURE=1 only if you can't install ssh-keygen and have checked the download some other way.

Keep it current with harebox self-update, which checks every download the same way. harebox version prints what you have.

Create an API key in the dashboard, under API keys, then give it to the CLI on stdin, so it never lands in your shell history:

harebox login --key-stdin

Paste the key and press Enter. The CLI saves it in its config file. You can also set HAREBOX_API_KEY instead, which wins over saved settings, as HAREBOX_API_URL does for the API address (https://api.harebox.com by default). Check who you are:

harebox whoami

Are you an agent? Run harebox login --agent. It signs you up and prints a claim_url for your human, who claims the account and adds a card. See Sign up from an agent.

harebox new --name first

harebox new returns when commands will work, and prints the machine's hourly price. It also remembers the sandbox as current in this folder, so the next commands don't need its ID.

Pick another size with --size small|default|large|xlarge, or any shape such as --size 6c12g.

harebox exec current -- uname -a
harebox exec current -- echo "hello from the VM"

harebox exec streams output as it arrives and exits with the command's own exit code, so it works in scripts and CI as is. A waiting command can run for up to an hour; for anything longer, detach it and check on it later:

CMD=$(harebox exec current --detach -- sleep 1 | jq -r .id)
harebox exec current "$CMD" --status

Every command is kept in the sandbox's history: harebox history current.

echo "notes for the agent" > notes.txt
harebox file write current --path /home/user/notes.txt --from notes.txt
harebox file read current --path /home/user/notes.txt

To copy a whole project, use harebox push current .. It skips .git and node_modules.

harebox host current 3000 --title Preview

This prints a private HTTPS URL for port 3000. Anyone with the full URL can open it, so treat it like a password; rotate it with harebox host rotate. If the sandbox is asleep, the first request wakes it. See Public endpoints.

Connect your model key once. It's stored outside your sandboxes: they only ever see a placeholder, and the credentials proxy adds the real key on the way out. See Credentials proxy.

harebox ai key set default anthropic-api-key --value "$ANTHROPIC_API_KEY"
harebox proxy rule add --secret-ref anthropic-api-key --host api.anthropic.com --header x-api-key --template "{secret}"

Then give an agent a task, with a spending cap. Events stream back as it works:

harebox prompt current "Clone github.com/acme/app, fix the failing test, and open a pull request" --harness claude --budget 3

The shell harness needs no key, so you can try the whole pipeline right now:

harebox prompt current "echo hello from a turn" --harness shell --budget 1

Add guidance mid-turn with harebox steer, or stop it with harebox interrupt. The next prompt continues the same conversation; --new starts another. See Harnesses.

harebox stop current
harebox resume current

Stop saves the whole disk and ends the bill. The disk is kept free for 14 days, then moves to paid cold storage instead of being deleted. Resume brings it back with your files, packages and enabled services.

To keep running programs and memory as well, put it to sleep instead. A sleeping sandbox is billed like a running one and still stops at its auto-stop, so use sleep for short breaks:

harebox sleep current
harebox wake current

harebox fork current --count 2

Each fork is an exact copy: files, installed packages and, from a running sandbox, its memory and programs. Each gets its own identity, IP and disk, so forks never share secrets or step on each other. Give each one a different task. See Parallel agents.

harebox list
harebox delete current

harebox delete erases the disk, memory and every snapshot by destroying the sandbox's encryption key. It can't be undone, so stop instead when you might come back. Set a budget so nothing runs away while you're learning:

harebox budget new --limit 25 --action stop

Every CLI command is an API call. The base URL is https://api.harebox.com/v1, and every request carries Authorization: Bearer $HAREBOX_API_KEY. Create a key for code with a narrow preset, such as harebox api-key new --name ci --preset ci. See API keys.

ID=$(curl -fsS -X POST "$HAREBOX_API_URL/v1/sandboxes" \
  -H "Authorization: Bearer $HAREBOX_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-$RANDOM-$RANDOM" \
  -d '{"name": "from-http", "ttl_seconds": 3600}' | jq -r .id)
curl -fsS -X POST "$HAREBOX_API_URL/v1/sandboxes/$ID/commands" \
  -H "Authorization: Bearer $HAREBOX_API_KEY" -H "Content-Type: application/json" \
  -d '{"command": "echo hello"}' | jq -r .stdout

A command waits for the sandbox to be ready, for up to 60 seconds. Send the same Idempotency-Key when you retry a create, and the retry never makes a second machine.

pip install harebox

from harebox import HareBox

hb = HareBox()  # reads HAREBOX_API_KEY, and HAREBOX_API_URL if set
box = hb.create(name="from-python", ttl_seconds=3600)
print(box.run("echo hello")["stdout"])
for event in box.prompt("echo hi", harness="shell"):
    print(event["type"])
box.stop()

npm install @harebox/sdk

import { HareBox } from "@harebox/sdk";

const hb = new HareBox(); // reads HAREBOX_API_KEY, and HAREBOX_API_URL if set
const box = await hb.create({ name: "from-typescript", ttl_seconds: 3600 });
console.log((await box.run("echo hello")).stdout);
for await (const e of box.prompt("echo hi", { harness: "shell" })) console.log(e.type);
await hb.stopSandbox(box.id);

Every API operation is also a typed method, such as hb.get_limits() in Python and hb.getLimits() in TypeScript. Errors carry a code and a fix. See SDKs.

Every error has a fix field that says what to do next, and a docs_url that links to its entry in the error reference. When in doubt, run harebox doctor current.

• Concepts: every word, defined once
• Lifecycle: every state, and what survives each change
• Environments: repositories, secrets and setup scripts for new sandboxes
• Templates: save a prepared machine and start from it in one call
• An agent on your repository and parallel agents
• One sandbox per end user: build a product on HareBox
• Use HareBox from your coding agent
• Limits and errors