Agent runbook
Works locallyWorks in the local build today.
Find the symptom, run the check, apply the fix. Start with harebox doctor ID --json, which runs most of these checks.
| Symptom | Check | Likely cause | Fix |
|---|---|---|---|
harebox says not signed in |
harebox whoami |
No credentials | harebox login --agent, then give the human the claim link |
402 card_required |
harebox limits --json |
The trial hasn't got a card yet | Give your human the claim link, and ask them to run harebox billing card. You cannot do this for them. |
402 billing_required |
harebox limits --json |
No plan, or an extra start the wallet can't pay | Wait for the start window, use --queue, or ask a human to start a plan or add funds |
402 payment_required |
harebox wallet --json |
No credit | Ask a human to add funds. You cannot do this for them. |
402 budget_exceeded |
harebox budget list --json |
A budget fired | Ask the owner. Do not raise a budget without permission. |
429 start_rate_limited |
harebox limits --json |
Past the most starts this plan can buy | Wait retry_after_seconds, or use --queue |
429 trial_compute_limit_reached |
harebox limits --json |
The trial used its 25 hours | Ask a human to start a plan |
| A sandbox stopped by itself | harebox events ID --type sandbox.stopped |
Its auto-stop came, an hour by default | harebox resume ID, then set --ttl to fit the job |
429 concurrency_limited |
harebox list --state ready |
Too many running | Stop what you started, or ask for a plan change |
503 no_capacity |
harebox regions |
No EU host free right now | Retry after retry_after_seconds, or use --queue |
| Command says wrong state | harebox info ID --json |
Stopped or sleeping | harebox resume ID or harebox wake ID |
| VM will not sleep | harebox info ID --json |
Session, command, turn or nested VM active | Find it with harebox ps ID and end it, if it is yours |
| VM slept unexpectedly | harebox events ID --type 'sandbox.sleep*' |
Idle by the rules | harebox set ID --sleep never or use a harebox schedule |
| Cron did not run | Was it sleeping? |
Timers do not fire in sleep | harebox schedule new |
| Slow CPU | harebox metrics ID --json, check cpu_steal_percent |
Noisy host | HareBox migrates automatically. If it persists, harebox recover ID, or use xlarge, which has whole threads. |
| Files read slowly after resume | hydration field |
Still hydrating | Wait for sandbox.hydrated |
degraded |
condition_details in harebox info, and harebox firewall ID |
Usually a guest change that blocked the agent | Undo it, or harebox recover ID |
| Lost recent writes after a failure | sandbox.recovered, data_loss_seconds |
Host failure; RPO applies | Restore from your source of truth, and replicate at application level if this matters. |
| Public URL returns 401 | harebox host list ID |
Token or auth mode | harebox host rotate ID ENDPOINT or change auth |
| Public URL returns 502 | harebox exec ID -- ss -ltnp |
App not listening on the port | Start it, and bind to 0.0.0.0 |
| Prompt fails with no credential | harebox ai profiles --json |
No key on the profile, or no_env |
Ask a human to connect one |
| Prompt stopped early | prompt.budget_exceeded |
Per-prompt budget | Ask, or raise --budget if allowed |
| Memory snapshot refused | capabilities.memory_snapshot |
Nested guests running | Stop them, or take a disk snapshot |
| Cannot resume | 409 data_expired |
Past retention | Cannot be recovered. Start from a template. |
Stop and ask before: adding money, raising a budget, deleting anything you did not create, sharing a template outside the account, opening an endpoint with --auth public, or copying data out of the EU.
Include request_id from the error, the sandbox ID and the time. Check harebox regions and the status page first.