---
name: harebox
description: Run commands, agents, desktops and fleets in HareBox VMs, and keep their cost under control. Use when the user wants a cloud machine, sandbox, VM, parallel agents, or to manage HareBox sandboxes, snapshots, templates, budgets or endpoints.
---

# HareBox

This build runs locally. Unless real VMs are configured, machines are a labelled simulator.

A sandbox is a full Ubuntu VM with root, systemd, Docker and `/dev/kvm`. Billing is per second from machine assignment until a stop begins; sleeping is billed like running.

## Before acting

```bash
harebox whoami || harebox login --agent     # prints a claim link for a human if needed
harebox limits --json                    # what remains
harebox rates --json                     # live prices
```

## Choosing a tier

| Work | Tier |
|---|---|
| Normal agent, dev, CI or batch work | `--tier shared` (default) |
| Can restart if interrupted, same price as Shared | `--tier spot` |
| Latency-sensitive, or needs whole CPU threads | `--size xlarge` (1:1, Team plan and up) |

## Common tasks

```bash
harebox new --size default --label task=fix-123 --json
harebox exec ID -- npm test                 # exit code is the command's own
harebox prompt ID "Fix the failing test" --budget 2
harebox fork ID --count 3                   # try three approaches
harebox sleep ID                            # keep memory; billed like running
harebox stop ID                             # end the bill
harebox host ID 3000 --auth oidc            # expose a port
```

## Rules

- Stop a VM when its work ends: that ends the bill. Sleep keeps memory and processes for a quick wake, but is billed like running.
- `sleep` does not happen while a nested VM, session, command or harness turn is active. Check conditions with `harebox info ID --json`.
- Treat `harebox delete` as irreversible. Confirm with the user unless they asked for it.
- Never paste a real API key into a sandbox. Use `harebox proxy rule add`.
- JSON appears automatically when output is piped. Streaming commands emit JSON Lines with an `event` field.
- On an error, follow `fix`. Exit codes: 3 auth, 4 not found, 5 wrong state, 6 limit or budget, 7 capacity, 8 network.

## When stuck

Read https://harebox.com/docs/guides/agent-runbook.md, then run `harebox doctor ID --json`.