Manual installation guide

Guardian for Agents has two parts:

1. orbit-hook: a small local binary that Claude Code calls before tool execution.
2. An ORBIT API key, used by the hook to fetch your account, active Agent Policy, escalation rules, and approval state.

When Claude wants to run a tool, orbit-hook reads the proposed tool call, checks your signed ORBIT rules, and either lets it pass, blocks it, or asks you for approval. Normal commands should stay boring. Dangerous commands should not be exciting by accident.

This guide uses the manual path. The setupclaw flow performs the same checks from the product workflow.

You need:

• An ORBIT account.
• A generated ORBIT API key. Copy it when it is shown. ORBIT should not show the same key again.
• Claude Code installed on the machine where your agent runs.
• Permission to install a binary somewhere on your PATH, usually /usr/local/bin.

If you are using a work machine, check your local policy before installing anything into /usr/local/bin. Yes, even if an AI told you to. Especially then.

You are helping me manually install ORBIT Guardian. Read this page first. Do not expose API keys. Download only from the approved ORBIT release or onboarding packet I provide, verify the digest before install, and stop before sudo install unless I confirm. Return the exact artifact URL, digest check result, install path, whoami output shape, and first hook smoke result.

Human steps: choose the artifact for your machine, download the matching checksum, verify it, and only then install. Do not run a random installer from a chat transcript.

Ask-your-AI steps: your agent can detect your platform, download the files, run the checksum command, and prepare the install command. It must stop before privileged install if your machine requires sudo.

Supported v1 artifacts are published from the ORBIT site under /releases/:

• orbit-hook-darwin-amd64 + checksum
• orbit-hook-darwin-arm64 + checksum
• orbit-hook-linux-amd64 + checksum
• orbit-hook-linux-arm64 + checksum

Example download flow:

PLATFORM=linux-arm64   # linux-amd64, linux-arm64, darwin-amd64, or darwin-arm64
curl -fsSLO https://orbitauthority.com/releases/orbit-hook-${PLATFORM}
curl -fsSLO https://orbitauthority.com/releases/orbit-hook-${PLATFORM}.sha256
sha256sum -c orbit-hook-${PLATFORM}.sha256

After the checksum passes, install the binary:

install -m 0755 orbit-hook-${PLATFORM} ~/.local/bin/orbit-hook
# Or, if you explicitly want a system path and approve sudo:
# sudo install -m 0755 orbit-hook-${PLATFORM} /usr/local/bin/orbit-hook

Once verified and installed, check the binary is available:

orbit-hook --version

You should see a version and commit. If your shell says command not found, the binary is not on your PATH or was installed somewhere else.

You are about to put a binary into a path Claude Code will execute as you, on every tool call. Treat it like any other trusted-path install: verify before running.

For the manual path, compare the SHA-256 of the binary against the digest published beside the exact artifact:

sha256sum -c orbit-hook-${PLATFORM}.sha256
# Expected: "orbit-hook-${PLATFORM}: OK". If it does not match,
# do not install.

About the curl ... | sh shape: that command alone only proves your machine reached a host serving an installer. It does not prove the host, the script, or the binary it fetches is the one ORBIT published. For a security tool you are about to install, that distinction matters.

The safer pattern is:

• Prefer downloading the release artifact and its published digest over piping an installer into your shell.
• If you use the installer command, save it first (curl -fsSL ... -o install.sh), read what it will do, and only then run it.
• Do not run an installer or binary that an agent or chat transcript handed you without independently confirming the digest against an ORBIT-published source.

Never paste the raw API key into chat, logs, issue comments, screenshots, or shell transcripts. A good report includes the artifact URL, digest result, install path, whoami output shape, setup-status proof, and receipt IDs only.

The hook currently reads the API key from ORBIT_API_KEY. Keep the key out of shell history when you can.

For a quick test in the current terminal:

export ORBIT_API_KEY='orbit_xxxxxxx'

For a persistent local setup, use your shell profile or a small private env file that your agent session loads. Keep it readable only by your user:

mkdir -p ~/.config/orbit
cat > ~/.config/orbit/env <<'EOF_ENV'
export ORBIT_API_KEY='orbit_xxxxxxx'
EOF_ENV
chmod 0600 ~/.config/orbit/env

Then load it before starting Claude Code:

source ~/.config/orbit/env

Optional for non-production/dev environments:

export ORBIT_GATEWAY_URL='https://api.orbitauthority.com'

If ORBIT_GATEWAY_URL is not set, orbit-hook defaults to https://api.orbitauthority.com.

Run:

orbit-hook whoami

A healthy response shows these fields; the values will differ by account:

• hook version
• authenticated account/org name
• tier
• active Agent Policy name and rule count
• endpoint
• credential source
• API key prefix

If you see ORBIT_API_KEY not set, load the environment variable in the same shell that will start Claude Code.

If you see an HTTP error, check that the key is correct and the machine can reach the ORBIT API.

Claude Code reads hooks from ~/.claude/settings.json.

Add a PreToolUse hook that calls orbit-hook pre:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/local/bin/orbit-hook pre",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Important: the timeout value is in seconds, not milliseconds. Use 120 for the launch approval window. Do not write 120000 unless your goal is to accidentally create a very patient computer.

If you already have Claude hooks, merge this entry carefully instead of replacing the whole file. Invalid JSON means Claude will not read the settings.

Start Claude Code from a shell where ORBIT_API_KEY is available:

source ~/.config/orbit/env
claude

If you use another launcher, service, tmux session, or desktop shortcut, make sure that environment also receives ORBIT_API_KEY. Environment variables do not magically follow you between shells. They are loyal, but only locally.

orbit-hook includes a factory test:

orbit-hook test

The test runs a synthetic dangerous command through the hook. In enforce mode, it should deny with exit code 2. In advisory/free mode, exit 0 may be expected depending on your account tier and current rules.

For a direct pre-hook smoke test:

cat <<'EOF_JSON' | orbit-hook pre
{
  "tool_name": "Bash",
  "tool_input": {"command": "sudo ls /tmp"},
  "hook_event_name": "PreToolUse",
  "session_id": "manual-test",
  "permission_mode": "default",
  "tool_use_id": "manual-test-1"
}
EOF_JSON

echo "Exit: $?"

Expected behavior depends on your active Agent Policy:

• Allow (no rule match, or the rule allows the command): exits 0
• Block: exits 2 and returns Claude hook decision JSON
• Ask me first: prompts for approval, then allows or blocks based on your response / timeout

Timeout is fail-closed: if approval does not arrive in time, the action is denied.

If Step 5 is still waiting and your account already has approval alerts turned on, do not go back to /onboarding. Completed users can be sent through the normal app gate and land in the cockpit instead of seeing the Step 4 prompt again. Use this non-secret recovery path instead.

1. Re-run the agent prompt without exposing the key. Ask your agent to verify the existing ORBIT hook install, reload its environment, and run the hook checks below. Do not paste an API key into chat or logs.
2. Confirm API key storage. Make sure ORBIT_API_KEY is available in the same shell, service, tmux session, or launcher that starts the agent. If you use the private env-file pattern from step 3, run source ~/.config/orbit/env before starting the agent.
3. Run whoami. Use orbit-hook whoami. A healthy response should show your account/org, tier, active Agent Policy, endpoint, credential source, and API key prefix.
4. Trigger the free first test escalation. Ask your agent to attempt a harmless sudo-shaped command such as sudo whoami, or run the direct pre-hook smoke test in step 7. The first test escalation is the setup proof path.
5. Return to Step 5. Open /onboarding/setup-status. Success means both rows are green: the hook reached ORBIT and the first test escalation received a verdict.

If whoami works but Step 5 never turns green, capture the local time you ran the test escalation and send it to support. That timestamp lets ORBIT compare the UI status, hook API calls, and escalation log without asking for your API key.

When a new version ships, repeat the same platform-specific download and digest check before replacing the old binary:

PLATFORM=linux-arm64   # linux-amd64, linux-arm64, darwin-amd64, or darwin-arm64
curl -fsSLO https://orbitauthority.com/releases/orbit-hook-${PLATFORM}
curl -fsSLO https://orbitauthority.com/releases/orbit-hook-${PLATFORM}.sha256
sha256sum -c orbit-hook-${PLATFORM}.sha256
sudo install -m 0755 orbit-hook-${PLATFORM} /usr/local/bin/orbit-hook
orbit-hook --version

The hook and ORBIT config are self-protected surfaces. If you already have ORBIT running, changing the hook binary or config may trigger an approval path. That is intentional. Security tools that silently allow themselves to be disabled are mostly decorative.

orbit-hook is not firing

• ~/.claude/settings.json is valid JSON.
• The hook command path is correct: /usr/local/bin/orbit-hook pre.
• Claude Code was restarted after editing settings.
• Claude Code is new enough to support the hook behavior ORBIT expects.

ORBIT_API_KEY not set

The key is not in the environment where the hook runs. Load your env file before starting Claude Code:

source ~/.config/orbit/env
claude

whoami cannot reach ORBIT

Check network access and ORBIT_GATEWAY_URL. If you are behind a corporate proxy or firewall, the hook needs outbound HTTPS access to the ORBIT API.

Approval alert does not arrive

Check that browser notifications are enabled at /settings/notifications and that your browser is allowed to show them. Approvals are always available in your signed-in ORBIT browser session. If the action times out, ORBIT denies by default.

Agent Policy changes do not apply

The hook fetches account and Agent Policy state from ORBIT and may cache some data briefly. Restart Claude Code and run orbit-hook whoami. If the active Agent Policy or rule count looks wrong, the Agent Policy editor/API/hook round-trip needs verification.

A guided setup flow can do more of this later. The manual guide remains the right path when you want to see each install and verification step before anything changes.

Use this manual path for users who want to see exactly what is being installed.