> ## Documentation Index
> Fetch the complete documentation index at: https://docs-beta.actrail.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK reference

> The actrail SDK — install, commands, and configuration.

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

<CodeGroup>
  ```bash pip theme={null}
  pip install actrail
  ```

  ```bash uv theme={null}
  uv pip install actrail
  ```
</CodeGroup>

## Commands

| Command                               | Does                                                            |
| ------------------------------------- | --------------------------------------------------------------- |
| [`actrail init`](#actrail-init)       | Connect an agent: verify the key, wire hooks, start the daemon. |
| [`actrail status`](#actrail-status)   | Daemon and config at a glance.                                  |
| [`actrail doctor`](#actrail-doctor)   | Full diagnostic.                                                |
| [`actrail enforce`](#actrail-enforce) | Turn policy checks on or off.                                   |
| [`actrail restart`](#actrail-restart) | Restart the daemon after a config change.                       |
| [`actrail login`](#actrail-login)     | Save just the API key.                                          |

### actrail init

```bash theme={null}
actrail init --key ak_your_key [--agent <id>]
```

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.

| Flag      |                                                                     |
| --------- | ------------------------------------------------------------------- |
| `--key`   | **Required.** Your `ak_…` API key.                                  |
| `--agent` | A label for this agent. Defaults to `claude-code@<host>@<project>`. |

```
✓ Actrail capturing (shadow) — scopes: ingest, check. Open https://app.actrail.ai
```

### actrail status

```bash theme={null}
actrail status
```

```
daemon:   running
config:   present
```

### actrail doctor

```bash theme={null}
actrail doctor
```

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

```
config:   ok
hooks:    ok
daemon:   ok
enforce:  on — policies are being consulted
```

### actrail enforce

```bash theme={null}
actrail enforce on    # consult policy before each action (adds the check hook)
actrail enforce off   # capture only, no checks
```

<Note>
  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.
</Note>

### actrail restart

```bash theme={null}
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

```bash theme={null}
actrail login --key ak_your_key
```

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`).

```toml theme={null}
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>` |
| `check.timeout_ms` | Ceiling on a policy check before it fails open (allows). | `1500`                         |

### 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

<AccordionGroup>
  <Accordion title="Hooks" icon="plug">
    `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.
  </Accordion>

  <Accordion title="The daemon" icon="server">
    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`.
  </Accordion>

  <Accordion title="Agent identity" icon="id-badge">
    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>`.
  </Accordion>
</AccordionGroup>

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