SDK reference

The actrail SDK connects your agent to Actrail: it records each action (metadata only), registers with Actrail so your managed policies install, and checks actions against those policies. It works with Claude Code out of the box.

Requirements

Python 3.11 or 3.12. The system Python on macOS is 3.9 and won’t work — use a 3.11/3.12 environment (e.g. uv venv --python 3.12).
macOS (Apple Silicon) or Linux (x86_64). On other platforms, install the source distribution (needs a Go toolchain).

Install

pip install actrail

uv pip install actrail

Install into a Python that stays on your PATH — the Claude Code hooks call actrail by name. The command is a small launcher that runs python3 -m actrail.cli; with an isolated install (pipx, uv tool, an inactive venv) point it at the right interpreter via ACTRAIL_PYTHON (see the Quickstart troubleshooting). Then connect your agent — see the Quickstart:

actrail init --key ak_your_key --global   # every session; omit --global for one project

Upgrade

Upgrading is not just pip install --upgrade. The SDK runs a warm daemon that keeps the old code loaded until you restart it, and each release can change the Claude Code hooks and how it registers. Run all four steps, in the same environment you installed into:

Upgrade the package

pip install --upgrade actrail

uv pip install --upgrade actrail

Pin a version if you need one, e.g. actrail==1.1.1.

Re-connect

actrail init --key ak_your_key --global   # match how you first installed (omit for a project)

Re-running init re-registers the SDK (refreshing which managed policies are available) and upgrades Actrail’s Claude Code hooks in place — it never touches your other hooks.

Restart the daemon

actrail restart

The running daemon holds the old code in memory; this reloads it on the new version.

Verify

actrail doctor

Confirms the hooks are current and the daemon is healthy.

Don’t skip actrail restart — it’s the most common reason an upgrade doesn’t take effect. And install into the same Python environment your Claude Code hooks use; upgrading a different environment leaves the old version wired in.

Start a new Claude Code session after upgrading. Claude reads .claude/settings.json at session start, so refreshed hooks apply to new sessions.

Commands

Command	Does
`actrail init`	Connect an agent: verify the key, register the SDK, install managed policies, wire hooks (this project, or `--global` for all sessions), start the daemon.
`actrail status`	Daemon and config at a glance.
`actrail doctor`	Full diagnostic across every settings scope.
`actrail enforce`	Turn policy checks on or off (add `--global` to target all sessions).
`actrail restart`	Restart the daemon after a config change.
`actrail login`	Save just the API key.

actrail init

actrail init --key ak_your_key [--global] [--agent <id>] [--endpoint <url>]

Verifies the key, registers this SDK release with Actrail (metadata only — integration, version, contract), installs the managed policies the release is certified to enforce (in shadow), wires the Claude Code hooks, writes the config, and starts the daemon. Scope — where the hooks are written:

--global → your user-level ~/.claude/settings.json — governs every Claude Code session on the machine. Recommended for a personal setup.
default (no --global) → the current directory’s ./.claude/settings.json — governs that project only. Run it from the repo you want to cover.

Flag
`--key`	Required. Your `ak_…` API key.
`--global` / `-g`	Wire hooks in `~/.claude/settings.json` (all sessions) instead of this project. Honors `CLAUDE_CONFIG_DIR`.
`--agent`	A label for this agent. Defaults to `claude-code@<host>@<project>`.
`--endpoint`	Actrail API base URL. Defaults to the hosted API.

✓ Actrail capturing (shadow, every session) — scopes: ingest, check. Open https://app.actrail.ai
  managed policies ready — 20 installed, 0 already present

A registration hiccup never blocks setup — it defers with a note, and re-running init re-projects your policies. If the line reads “not certified for managed policies”, you’re on an older SDK than Actrail certifies — upgrade and re-run init.

actrail status

actrail status

daemon:   running
config:   present
endpoint: https://api.actrail.ai

actrail doctor

actrail doctor

Diagnoses config, hooks, the daemon, and whether policy is being consulted. It resolves every settings scope Claude Code merges — user (global), project, local, and managed — so a global install reports healthy even with no project file.

config:   ok
hooks:    ok (global)
managed:  unverified — server/MDM/registry managed settings are not visible to the CLI
daemon:   ok
endpoint: https://api.actrail.ai
enforce:  on — policies are being consulted

hooks: ok (<scope>) — where the live install is: global, project, or project + global. DISABLED means the hooks are wired but a disableAllHooks / managed setting stops them from running.
managed: — the enterprise-managed layer. A CLI can read managed settings files and managed-settings.d drop-ins, but not MDM/registry/server-pushed policy, so it reports that layer as inspected-or-unverified rather than certifying it.

actrail enforce

actrail enforce on            # consult policy before each action (adds the check hook)
actrail enforce off           # capture only, no checks
actrail enforce on --global   # target ~/.claude/settings.json (all sessions)

Add --global / -g to toggle the enforce hook in your user-level settings instead of the current project. enforce off warns if another scope still has the hook, so it never reads as “off” while a global hook keeps enforcement active.

Whether an action is actually blocked depends on the matching policy’s mode in the console (shadow vs. enforce). enforce on just means the agent asks.

actrail restart

actrail restart

Stops the daemon and starts a fresh one. The daemon reads its config once at startup, so run this after a config change.

actrail login --key ak_your_key

Saves just the API key to ~/.actrail/config.toml (without registering, wiring hooks, or starting the daemon).

Configuration

Config lives at ~/.actrail/config.toml (permissions 0600). actrail init writes it for you; you can also edit it directly (then actrail restart).

key = "ak_your_key"
agent = "claude-dev"

[check]
timeout_ms = 1500

Key	Meaning	Default
`key`	API key (`ak_…`).	—
`agent`	Agent label.	`claude-code@<host>@<project>`
`endpoint`	Actrail API base URL.	`https://api.actrail.ai`
`check.timeout_ms`	Ceiling on a policy check before it fails open (allows).	`1500`

Environment variables

Override the file with ACTRAIL_KEY, ACTRAIL_AGENT, and ACTRAIL_ENDPOINT. Precedence, low to high: defaults → config file → environment → command flags.

How it works with Claude Code

Registration

On init the SDK tells Actrail which release it is (integration, version, contract — no customer data). Actrail certifies the release and installs the managed policies it can enforce. This is why your console has rules before the first trail — and why an uncertified SDK sees none until you upgrade.

Hooks

init writes hooks to ~/.claude/settings.json with --global (every session) or to the project’s ./.claude/settings.json without it — Claude Code merges both, plus local and managed settings. Existing hooks you have are preserved.

PostToolUse / PostToolUseFailure → captures each action (success and failure) after it runs.
PreToolUse → checks an action against policy before it runs (added by enforce on).
SessionEnd → closes the trail so detection runs promptly.

For a whole team, deploy the same hooks via Claude Code’s managed settings so every developer is governed without running init — see the Claude Code docs.

The daemon

A small background process holds a warm client (scanners stay loaded), so per-action overhead stays low. It starts on init (or on the first hook) and is managed with actrail status / restart.

Agent identity

Each action is attributed to claude-code@<host>@<project> by default, so the console can tell your agents apart. Override it with actrail init --agent <id>.

Shadow vs. enforce

Shadow (default) — actions are captured and evaluated; a matching policy reports what it would block, but nothing is blocked.
Enforce — a matching deny / require approval policy actually stops the action.

You graduate a policy from shadow to enforce in the console. actrail enforce on|off controls whether the agent consults policy at all.

What’s captured

Actrail is metadata only. Your raw arguments, results, and file contents never leave the machine — the SDK sends a redacted, per-field skeleton. An always-on secrets floor means API keys, tokens, and passwords are never emitted, and it can’t be turned off.

Get started

Using Actrail

Requirements

Install

Upgrade

Commands

actrail init

actrail status

actrail doctor

actrail enforce

actrail restart

Configuration

Environment variables

How it works with Claude Code

Shadow vs. enforce

What’s captured

​Requirements

​Install

​Upgrade

​Commands

​actrail init

​actrail status

​actrail doctor

​actrail enforce

​actrail restart

​actrail login

​Configuration

​Environment variables

​How it works with Claude Code

​Shadow vs. enforce

​What’s captured

Requirements

Install

Upgrade

Commands

actrail init

actrail status

actrail doctor

actrail enforce

actrail restart

actrail login

Configuration

Environment variables

How it works with Claude Code

Shadow vs. enforce

What’s captured