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 agent-driven setupclaw flow will eventually do most of this for you.

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.

The final public install URL is still being wired. For launch, setupclaw/install hosting is tracked separately.

Expected shape once published:

curl -fsSL https://orbitgrc.com/install.sh | sh

Manual shape if you have a release artifact or locally built binary:

sudo install -m 0755 orbit-hook /usr/local/bin/orbit-hook

Before you run anything you just downloaded, see the next section. The install step is the root of trust for everything ORBIT does afterward, so verification is not optional.

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 with the same ORBIT release:

sha256sum orbit-hook
# Compare against the expected digest published alongside the
# release artifact. Match byte-for-byte. 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 signed. For a security tool you are about to install with elevated privileges, that distinction matters.

Until the signed-release path is live, 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.

Signed releases (artifact signatures and a published ORBIT public key) are tracked separately. Once that path ships, this section will name the verification command and the expected key fingerprint, and that will become the recommended check.

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.orbitgrc.com'

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

Run:

orbit-hook whoami

A healthy response shows:

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

When a new version ships, verify the new artifact against the published digest (see step 2), then install over the old one:

sha256sum orbit-hook   # compare to expected
sudo install -m 0755 orbit-hook /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 SMS does not arrive

Check that your phone is verified in ORBIT. Also check quota and account state. 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.

The upcoming setupclaw flow should let you paste one instruction into your agent. The agent will fetch setup instructions, install the hook, configure the API key, run verification, and trigger the first test escalation.

Until then, this manual guide is the path for users who want to see exactly what is being installed.