# Agent runbook

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. |

## When to stop and ask a human

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.

## Reporting a platform problem

Include `request_id` from the error, the sandbox ID and the time. Check `harebox regions` and the status page first.