When something is wrong.

If you can sign in but /onboarding/setup-status never turns green, recover the existing install instead of creating another account or exposing an API key in chat.

1. Open the Step 5 recovery guide and run its checks from the same shell, tmux session, or launcher that starts your agent.
2. Run orbit-hook whoami. It should show your account, Agent Policy, API endpoint, credential source, and API key prefix. If it does not, fix the key storage before testing the hook again.
3. Trigger one harmless test escalation, then return to /onboarding/setup-status. Both rows should turn green: first hook contact and first test escalation verdict.

If whoami works and the test escalation ran but the page still waits, send support the local time of the test and the key prefix only. Never send the full API key.

setupclaw runs four things in order: download the orbit-hook binary, store your API key in the OS keychain, write the Claude Code hook config, run a self-test. A failure in any of the four is reported plainly, with the next command to run.

The two failures we see most:

• Download fails. Usually a network policy or a corporate proxy.curl and wget both work. If both are restricted in your environment, email support@orbitauthority.com and we will get you the binary URL and checksum directly so you can pull it through your own proxy.
• Keychain write fails. Common on stripped-down server installs without a desktop keychain service. setupclaw assumes a keychain. For server or headless installs, email support@orbitauthority.com. We have an env-var setup path we will walk you through.

Guardian surfaces an approval in your ORBIT browser session whenever a rule matches Ask me first, and alerts you there if notifications are enabled. If approval requests are not reaching you, walk this list:

1. Confirm browser alerts are enabled at /settings/notifications on the device you are watching. Browser notifications are per-device and per-browser, so turning them on once does not cover a device or browser you never enabled.
2. Confirm the action matched an Ask me first rule. Open /audit for the recent action; the row shows which rule matched and its mode. Guardian only sends an approval alert when the matched rule is Ask me first. If the matched rule is Allow or Block, no alert was sent. Guardian had a definitive verdict and did not need to ask you.
3. Re-check notification permission for orbitauthority.com in your browser and operating system. A revoked or OS-muted permission silences alerts even while the approval is waiting on your approvals screen.
4. Act on the request directly. Every pending request also appears on the approvals screen regardless of alert delivery, so you can approve or deny it there even if a notification was missed.

If the audit shows Ask me first actions and no alert is reaching you, email support with the action ID; we can look at the delivery logs.

Three things have to be true for a Claude Code action to land in your dashboard: the hook is installed, the hook can find your API key, and the hook can reach the ORBIT API. Test each:

orbit-hook whoami

Prints the account the hook authenticated as. If you get an account name, the hook is installed, the API key is reachable, and the network path is open. The dashboard should start receiving actions on the next Claude Code call.

If whoami errors:

• “command not found”. The orbit-hook binary is not on your PATH. setupclaw puts it at ~/.local/bin/orbit-hook by default; confirm that directory is in your shell PATH.
• “no API key”. The hook cannot find the key. setupclaw stores it in the OS keychain; if the keychain failed silently or the key was deleted, reissue a key at /keys and re-run setupclaw.
• “unauthorized”. The key the hook is sending is not recognized by the API. Most often this means the key was rotated and the hook still has the old one. Reissue at /keys; setupclaw refresh stores the new one.
• “network unreachable”. Firewall or proxy in the way. The hook talks to https://api.orbitauthority.com over HTTPS. Allow that hostname.

An API key’s plaintext is shown once, at issue time, and never again. After that the /keys page shows a prefix only.

There is no recovery path. Issue a new key from the same page and update the hook (re-run setupclaw, or for manual installs update the env var or keychain entry). The old key keeps working until you explicitly revoke it, so you do not have to coordinate the rotation perfectly.

Guardian only blocks an action if the matching rule is set to Block. If you expected a specific action to be stopped and it was not:

What audit can and cannot prove: /audit shows what ORBIT observed and how it decided on the actions it saw. Absence of a row is not proof the agent did nothing. If Guardian was offline, the hook was not loaded, or the action took a path Guardian does not intercept, the action will not appear here.

1. Find the action in /audit. Note the rule that matched (or that no rule matched).
2. Open Rules, find that rule, and check its current verdict. If it is Allow, that is by design. Change it to Ask me first or Block; the next call follows the new rule.
3. If no rule matched, the action falls outside the 50 default rules. Either add a custom rule for that action shape from the cockpit, or accept that this risk class is not in the catalog yet (file a request at support).

Symmetric to the above. The same coverage caveat applies: /audit records what ORBIT observed; it is not a canonical log of every agent attempt. The most common path:

1. Find the action in /audit. The verdict will say Block; the rule that triggered is named.
2. If the rule’s verdict is Block but you wanted Ask me first, change it in Rules.
3. If the verdict was Block because an Ask-me-first rule timed out, you missed the approval alert. See the No approval alert arriving section above; the timeout default is Block by design (fail-closed).
4. If the action was blocked by a custom rule you forgot you wrote, the audit row links to that rule; open it and adjust.

The free Guard tier caps governed actions per month and burst rate per minute. The exact numbers are on /orgunder Plan & Limits.

If your hook is getting 429 Too Many Requestsresponses, you have hit the per-minute burst cap. The hook backs off and retries; if you hit the cap repeatedly, the monthly cap is approaching. Check Plan & Limits.

If you hit the monthly cap, every governed action returns 429 until the first of the next month. Upgrade to Guard from /billing to lift the cap. Receipts for the rate-limited actions are not generated; the actions did not enter the governance loop.

Check your installed version:

orbit-hook --version

The hook prints a one-line warning if it detects a newer published version. The warning does not block; the hook keeps working. Update on your schedule by re-running the setupclaw binary you already have locally:

setupclaw

setupclaw is idempotent: re-running it overwrites the orbit-hook binary in place, leaves your API key and Claude Code config alone, and runs the self-test again. We do not recommend re-fetching the install script over the network as an update path; the orbit-hook binary mediates agent actions, so the update path should not introduce a new unverified network fetch. If your local setupclaw is also out of date or missing, email support@orbitauthority.com for the signed binary URL and sha256 checksum.

The offline verifier checks a .orbitprooffile’s signature against ORBIT’s pinned public key. A mismatch means one of three things:

• The receipt was edited after ORBIT signed it. Even a single byte change breaks the signature. Re-download the receipt from your /audit page; that copy will verify.
• The pinned public key on your machine is older than the receipt. ORBIT rotates the signing key periodically. The CLI reports the signer ID it expected and the signer ID on the receipt. If they differ, fetch the current public key from /verify (the page shows it inline) and update your pin.
• The file is not actually a .orbitproof. Schema check fails before the signature check. The CLI prints the schema reason; the file may be JSON but not match the receipt schema.

If the file is a real ORBIT receipt and verification still fails after fetching the current public key, that is unexpected. Email support@orbitauthority.com with the receipt ID (visible in the audit), the CLI signer ID it expected, and the signer ID on the receipt. Do not attach the .orbitproof file by email. Receipts are private to the owning account; we will request the file through a secure path if needed.

Email support@orbitauthority.com when:

• The audit shows Ask me first actions but no approval alert is arriving.
• orbit-hook whoami succeeds, your agent is making calls, and the dashboard still shows nothing.
• A real .orbitproof from your audit fails to verify offline after you fetched the current public key.
• You hit a 5xx response from the API that does not clear on retry.
• Anything that looks like a security issue. Use the same address.

Include the action ID or receipt ID where relevant. Reply latency is human-fast at launch volume.