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.1.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.1-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.1-cp312-cp312-macosx_12_0_arm64.whl (2.3 MB view details)

Uploaded CPython 3.12macOS 12.0+ ARM64

actrail-1.0.1-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.1-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.1.tar.gz.

File metadata

  • Download URL: actrail-1.0.1.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.1.tar.gz
Algorithm Hash digest
SHA256 e8f41a8e73a1de0abe1b9d02ac28ec3a46ee03639698571ccc15ac30992db7dc
MD5 aaca48ab1e3ad588a4b8dab16da2dcff
BLAKE2b-256 a5ffec42227e163086cbfb534ec03f7c0c5e6ed17cc1ba2262899e5f8f158f3d

See more details on using hashes here.

Provenance

The following attestation bundles were made for actrail-1.0.1.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.1-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.1-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 cb8167f0795f31217790fa1c9ce6a93e16b68f5e583e16c7bfb2f5e1befba658
MD5 dadd06664f11b3d80074043f6b64e3ee
BLAKE2b-256 19c4a897996bf058f4a687e5858733b2eb9793cc56824622256a3cd48250618f

See more details on using hashes here.

Provenance

The following attestation bundles were made for actrail-1.0.1-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.1-cp312-cp312-macosx_12_0_arm64.whl.

File metadata

File hashes

Hashes for actrail-1.0.1-cp312-cp312-macosx_12_0_arm64.whl
Algorithm Hash digest
SHA256 e89287e30d913540c96887d8ff3538980e092ba2603612dcb45d877fe518d551
MD5 500f1f5f4bf5d2bbd06aa7af927e9d6e
BLAKE2b-256 bcc35dad811343164ff2e0d1adf5771f958b7517f27f08753a098bbf33bfea72

See more details on using hashes here.

Provenance

The following attestation bundles were made for actrail-1.0.1-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.1-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.1-cp311-cp311-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 f8a1560ee6dea4a9b9287f52b339161a181bb3b4357d8c7e6240a0c4a7e63179
MD5 8220b521f18301be3a6192762e308990
BLAKE2b-256 28b1e79b81607d4ccf7a054b2565e32ca5c013bd440ba4bb01a29a625f1a18a1

See more details on using hashes here.

Provenance

The following attestation bundles were made for actrail-1.0.1-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.1-cp311-cp311-macosx_12_0_arm64.whl.

File metadata

File hashes

Hashes for actrail-1.0.1-cp311-cp311-macosx_12_0_arm64.whl
Algorithm Hash digest
SHA256 9e10106963b0a4b2ac37c9af9df9b83c19d3aa92dbd2b80900188392cb951188
MD5 047e4a2b7ee0b5d02b532a548ec06dda
BLAKE2b-256 349eaf31bfd5b91c8a717d9b4a500164b2b1d459e3a4fc19150b0aba73949a7d

See more details on using hashes here.

Provenance

The following attestation bundles were made for actrail-1.0.1-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