Skip to main content
The actrail SDK connects your agent to Actrail: it records each action (metadata only) and checks actions against your 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

​
Commands

​
actrail init

Run from your project directory. Verifies the key, wires the Claude Code hooks (capture, check, session-end), writes the config, and starts the daemon in shadow mode.

​
actrail status

​
actrail doctor

Diagnoses config, hooks, the daemon, and whether policy is being consulted.

​
actrail enforce

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

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

Saves just the API key to ~/.actrail/config.toml (without 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).

​
Environment variables

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

​
How it works with Claude Code

init writes hooks to ./.claude/settings.json:
  • PostToolUse → captures each action after it runs.
  • PreToolUse → checks an action against policy before it runs (added by enforce on).
  • SessionEnd → closes the trail so detection runs promptly.
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.
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 control this per policy 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.