Actrail

Runtime policies for AI agents — the open-source edge SDK

Govern what your agents do, not just what they say. Actrail captures every agent action as metadata-only telemetry and enforces deterministic policies before a risky action runs — a human-readable rule, never an LLM, in the binding decision.

PyPI Python License Ruff mypy: strict

Why Actrail

AI agents don't just generate text — they take actions: refund a customer, delete a row, deploy to prod, send data to an external LLM. Content guardrails don't see any of that. Actrail governs the actions:

  • Deterministic enforcement. Policies are plain rules (refund > $500 without approval → require_approval) evaluated in < 50ms, fail-open. No model in the verdict.
  • Metadata-only by construction. The SDK never sends raw arguments or results. It emits a redacted, per-field skeleton — keys kept, values stripped or transformed — built from scratch, never copied.
  • An always-on secrets floor. API keys, tokens, private keys, passwords, connection strings are never emitted, and it can't be turned off.

Install

pip install actrail

Requirements

  • Python 3.11+. The system Python on macOS is 3.9 and will not work — use a 3.11/3.12 environment.
  • macOS 12+ (Apple Silicon or Intel) or Linux x86_64. Prebuilt wheels bundle the native shim — no toolchain needed.

Optional extras for deeper local scanning:

pip install "actrail[ner]"    # + Presidio / spaCy for names & unstructured PII
pip install "actrail[full]"   # + transformers

Verify:

actrail --help                                        # bundled CLI on PATH
python -c "import actrail; print(actrail.__version__)"

not a supported wheel on this platform? Almost always your Python isn't 3.11/3.12 (macOS ships 3.9). Create a 3.11/3.12 env — e.g. uv venv --python 3.12 — and reinstall.

Quickstart

Claude Code (zero-code onboarding)

actrail init --key ak_live_...     # wires the hook, starts the daemon in shadow mode
actrail enforce on                 # arm PreToolUse enforcement when you're ready
actrail doctor                     # verify config · hooks · daemon

Any agent (the library)

import actrail

actrail.init(key="ak_live_...", agent="support-bot")

# Before a risky action — get a deterministic verdict (fail-open, < 50ms).
verdict = actrail.check(
    trail_id="sess_42",
    tool="pay.api",
    action="refund",
    payload={"order": {"amount": 2500, "currency": "USD"}, "table": "prod.customers"},
)
if not verdict.allow:
    raise PermissionError(verdict.reason)   # require_approval / deny

# After it runs — capture the action as metadata-only telemetry (fire-and-forget).
actrail.capture(
    trail_id="sess_42",
    tool="pay.api",
    action="refund",
    payload={"order": {"amount": 2500}, "customer": {"email": "alice@example.com"}},
)

payload is the structured tool-call args. Actrail walks it into a governed fields[] envelope — it never leaves your machine as raw data.

The telemetry contract

Every field passes through a transform ladder, least → most revealing, and the customer governs it per field (default-deny):

Rung What's emitted Example
drop nothing (skeleton only) unknown fields
type_only just the type customer.email → (type: email)
derived a safe derivation email → domain:example.com
bucket a coarse bucket amount: 2500 → 1000_10000
token a one-way HMAC pseudonym join without revealing
raw the value verbatim only for non-secret, opted-in fields

Three guarantees stack, in order:

  1. Default-deny — an un-contracted field gets a conservative per-type default.
  2. Secrets floor — a secret-typed field, or any value that looks secret, is forced to drop. Non-overridable — a contract can never lift a secret onto the wire.
  3. Outbound validator (fail-closed) — every emitted value is re-scanned and scrubbed if it still looks secret, the last line before anything leaves.

A seeded fuzz test asserts the invariant under the worst case — every field forced to raw: no secret ever appears in an emitted value.

What leaves the machine

{
  "tool": "pay.api", "action": "refund", "destination": "internal",
  "data_classes": ["financial", "pii"],          // derived from the envelope
  "fields": [                                     // the redacted skeleton
    {"path": "order.amount", "semantic_type": "amount", "handling": "bucket", "value": "1000_10000"},
    {"path": "customer.email", "semantic_type": "email", "handling": "type_only"},
    {"path": "auth.api_key", "semantic_type": "api_key", "handling": "drop"}   // floored — no value
  ],
  "amount": 2500,                                 // a first-class grammar fact
  "taint_sources": [{"table": "prod.customers"}], // enables "data from prod.customers" policies
  "taint": ["email:v1:9f3a…"],                    // one-way fingerprints (flow, not values)
  "sdk_version": "1.0.0", "contract_version": "v1"
}

No args. No result. No raw values. Ever.

Architecture

tool call ──► capture()/check() ──► enrich (taint) ──► contract pipeline ──────► backend
              payload · content       HMAC fingerprints  build ▸ govern ▸ validate  /spans · /check
                                                         fields[] · amount · sources
  • Deterministic outside, fail-open at /check, fail-safe at ingest.
  • BYO scanner — the enrichment scanners implement a simple Scanner protocol.
  • Optional NER (pip install actrail[ner]) for richer PII detection; the default path stays lightweight (regex + entropy + detect-secrets).

Security & privacy

The metadata-only guarantee is by construction, not detection — see SECURITY.md. Short version: raw payloads never leave the machine, secrets are floored non-overridably, taint is one-way HMAC, and the wire is fail-closed validated.

Development

uv venv && uv pip install -e ".[dev]"
uv run pytest          # tests (+ safety-invariant fuzz)
uv run ruff check .    # lint
uv run mypy            # strict types

License

Apache 2.0

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.2.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for actrail from gravatar.com actrail

Credits

Author: Actrail

License

Apache Software License (Apache License)

Requires

Python >=3.11

Provides Extra

dev full ner

Tags

agents ai governance guardrails llm security

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

actrail-1.0.0.tar.gz (2.3 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

actrail-1.0.0-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64manylinux: glibc 2.5+ x86-64

actrail-1.0.0-cp312-cp312-macosx_12_0_arm64.whl (2.3 MB view details)

Uploaded CPython 3.12macOS 12.0+ ARM64

actrail-1.0.0-cp311-cp311-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64manylinux: glibc 2.5+ x86-64

actrail-1.0.0-cp311-cp311-macosx_12_0_arm64.whl (2.3 MB view details)

Uploaded CPython 3.11macOS 12.0+ ARM64

File details

Details for the file actrail-1.0.0.tar.gz.

File metadata

  • Download URL: actrail-1.0.0.tar.gz
  • Upload date:
  • Size: 2.3 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for actrail-1.0.0.tar.gz
Algorithm Hash digest
SHA256 b4609e4873f35104186379a61b13ebe3f5d93b19db0ff8ef5a27a57ab41d1140
MD5 5fbef5fbcd0526fc465879a705f1ccc8
BLAKE2b-256 2b263500309c5fb6aadb5e3908e92e97d68e9bc7ebc80117dd14c952c157593a

See more details on using hashes here.

Provenance

The following attestation bundles were made for actrail-1.0.0.tar.gz:

Publisher: release.yml on actrailhq/actrail-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file actrail-1.0.0-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for actrail-1.0.0-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 fbf160545636144805f196ff80db8b695b414553521b175de2ff513b662173b2
MD5 6a3e5906096e0c081d137498c1d38597
BLAKE2b-256 144311ac53ee9bca73ad7c905939c53b37f7e8409b41032bfeffaebd73edbfbf

See more details on using hashes here.

Provenance

The following attestation bundles were made for actrail-1.0.0-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on actrailhq/actrail-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file actrail-1.0.0-cp312-cp312-macosx_12_0_arm64.whl.

File metadata

File hashes

Hashes for actrail-1.0.0-cp312-cp312-macosx_12_0_arm64.whl
Algorithm Hash digest
SHA256 1ae93eb6425810e76892c1fe7da0603d292c73d5f9695857c0f099db6f4d4d60
MD5 d1fa7ebcd816b0fc13556ef29970f8e6
BLAKE2b-256 54ce2b0788bbfcce9b42d853522f41cb1393693b0d8c732acc73c75e3edbc88a

See more details on using hashes here.

Provenance

The following attestation bundles were made for actrail-1.0.0-cp312-cp312-macosx_12_0_arm64.whl:

Publisher: release.yml on actrailhq/actrail-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file actrail-1.0.0-cp311-cp311-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for actrail-1.0.0-cp311-cp311-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 cf1a20f83420e416d9d558d10dbc5aa5867374059d8f1e4f4dc7668d7a361234
MD5 6395df005eb72cda102bf6b766acbb0f
BLAKE2b-256 cc9144d6f052ef25dc8ffb584438051d4470a98769482b6dd02415c657901c20

See more details on using hashes here.

Provenance

The following attestation bundles were made for actrail-1.0.0-cp311-cp311-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on actrailhq/actrail-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file actrail-1.0.0-cp311-cp311-macosx_12_0_arm64.whl.

File metadata

File hashes

Hashes for actrail-1.0.0-cp311-cp311-macosx_12_0_arm64.whl
Algorithm Hash digest
SHA256 be94a78390a4098dbd00aa11ed62fc4abaf0b0a0d0612152b8a488be255767e1
MD5 c989890a6f65d31369adb20ffa556bd7
BLAKE2b-256 d8e3b919338d34afeaf45c135c5ec9ac7f8d6f870c8acecda90cc57ba78a9a3c

See more details on using hashes here.

Provenance

The following attestation bundles were made for actrail-1.0.0-cp311-cp311-macosx_12_0_arm64.whl:

Publisher: release.yml on actrailhq/actrail-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page