Skip to main content
When you’re done, every Claude Code session on your machine streams its actions into the console automatically — and a catalog of managed policies is already watching in shadow.
You’ll need an Actrail account and Python 3.11 or 3.12. The system Python on macOS is 3.9 and won’t work — install a 3.11/3.12 (e.g. uv python install 3.12, Homebrew, or python.org) and run the steps below with it.
1

Get an API key

In the console, open Settings → API keys and create one. It starts with ak_ and is shown in full once — copy it now.
2

Install the SDK

Confirm the command is available:
Install into a Python that stays on your PATH — the Claude Code hooks call actrail by name in every session. If actrail only works inside one virtualenv, see Troubleshooting.
3

Connect Claude Code — every session

--global wires the hooks into your user-level ~/.claude/settings.json, so every Claude Code session — in any folder — is governed. init also verifies the key, registers the SDK and installs the managed policies it can enforce (in shadow), and starts the daemon. You should see:
Want to govern just one repo instead? Run actrail init --key ak_your_key without --global inside that project — it wires ./.claude/settings.json for that repo only.
4

Verify

hooks: ok (global) confirms every session is wired. The managed: line is just a note that enterprise-managed settings — if your org uses them — live in sources a CLI can’t inspect; for an individual setup there’s nothing to do.
5

Use Claude Code

Start a new Claude Code session — Claude reads its settings at launch, so hooks apply to sessions opened after init. Then work as usual; every action is captured as metadata only.
You’re set up. Open Trails to watch actions arrive, and Runtime Policy to see the managed rules now watching in shadow.
You’re in shadow mode: Actrail watches and flags, but nothing is blocked until you graduate a policy to enforce.

​
Troubleshooting

The install directory isn’t on your PATH. Find the binary — python3 -m pip show -f actrail | grep actrail$ or uv tool dir — and add its bin directory to PATH, then restart your shell. Installing into a Python that’s already on your PATH avoids this.
The actrail command is a small launcher that runs python3 -m actrail.cli. If your PATH python3 isn’t the interpreter you installed into (common with pipx, uv tool, or an inactive virtualenv), point the launcher at the right one:
Add it to your shell profile (~/.zshrc) so the Claude Code hooks inherit it too.
doctor reports the scope you’re in. If you installed with --global but run doctor inside a project that has its own older Actrail hooks, fix that project with actrail init --key ak_... (or delete its .claude/settings.json to rely on the global install). A healthy global setup reads hooks: ok (global).
Claude Code loads settings at session start — open a new session after init. Then actrail status should show daemon: running; if not, run actrail restart.

See it work

Graduate a policy to enforce, or turn a flag into one.

SDK reference

Every command, all config options, and how the SDK works.