Skip to main content

agentlighthouse-core

The runtime security and governance plane for AI agents.

AgentLighthouse is a mediator that sits outside the agent. Every network call, tool call, memory operation and inter-agent message goes through it. It screens what comes in, authorizes what goes out, and writes a signed, hash-chained, independently verifiable receipt for every decision it takes.

agentlighthouse-core is the mediator itself: the proxies, the scanners, the policy engine, the evidence ledger and the al command line.

Contents

Why a mediator

An AI agent reads untrusted text (a web page, a tool response, another agent's message) and then acts on it: it calls tools, writes memory and sends data out. A guardrail placed inside the agent shares the agent's trust boundary, so a successful prompt injection is already past it.

AgentLighthouse takes the control point out of the agent. The agent talks to the mediator, and the mediator decides. Three properties follow:

  • A choke-point. In the container topology the agent has no other road out.
  • Identity-bound least privilege. Every agent has an identity, and a tool runs only when that identity is explicitly allowed to run it.
  • Evidence an auditor can check. Each decision is an Ed25519-signed receipt, chained to the one before it. Anyone can verify the chain with a standalone tool that does not import this package.

Everything fails closed: a scanner crash, a timeout, a bad configuration or an unverifiable ledger denies the request or refuses to start.

Install

pip install agentlighthouse-core

This installs two commands: al (this package) and al-verify (the standalone verifier, from agentlighthouse-verify).

The wheel carries the shipped configuration profiles, the default-deny tool policy and the prebuilt evidence dashboard. No source checkout and no Node toolchain are needed.

Optional extras:

Extra Adds
agentlighthouse-core[postgres] The Postgres evidence mirror, for several mediators writing to one query surface
agentlighthouse-core[scanners] A detect-secrets adapter behind the scanner interface

Quick start

From an empty directory to independently verified evidence:

al init                                        # keys/, data/, .env, configs/, policies/
al healthz --config configs/balanced.yaml      # boot the runtime, verify config and chain
al-verify data/ledger.jsonl --pubkey keys/mediator_ed25519.pub

al init generates the Ed25519 signing key, writes a development .env, and lays down the shipped configs/ and policies/ when they are absent. It never overwrites a file you already have.

Exercise the gates directly. The exit code is scriptable:

al scan "ignore all previous instructions"         # block  INJECTION_BLOCKED   exit 3
al scan "AKIAIOSFODNN7EXAMPLE"                     # strip  aws-access-key      exit 2
al policy check spiffe://acme/agent/x exec_shell   # deny   TOOL_NOT_ALLOWED    exit 3
Verdict Meaning Exit code
allow Nothing found 0
strip A secret or PII was found and is redacted in flight 2
block The content or the action is denied 3

What it does

Domain Capability
Network mediation CONNECT forward proxy, fetch proxy, OpenAI- and Anthropic-compatible reverse proxy with SSE, MCP proxy (stdio and Streamable HTTP), A2A mediation
Egress control Default-deny nftables ruleset, with a boot self-test that refuses to start if out-of-band egress succeeds
Content inspection Six-pass normalization that folds evasions, then a fail-closed detection engine: injection, secrets, PII, SSRF, entropy, BIP-39 seed phrases, rate and data budgets
Capability control Identity-bound default-deny tool policy with argument constraints, outbound DLP on tool arguments, human approval on irreversible verbs, MCP descriptor pinning, chain detection, taint escalation
Memory protection Guarded reads and writes, poison quarantine, secret redaction, SHA-256 integrity baselines, snapshot and rollback
Instruction-file protection Screening and pinning of SKILL.md, CLAUDE.md, AGENTS.md and .cursorrules
Evidence Append-only signed ledger, SQLite or Postgres mirror, ECS/MITRE SIEM export
Control A kill switch with four independent sources that drills to full deny-all
Learning A human-gated loop that ships only signed rule bundles and can only tighten the gate

Architecture

Seven layers, operated as four gates. The control plane is segregated from the agent network.

Gate Layers Owns
Edge Gate L0 + L1 Egress choke-point, proxy modes, DNS pinning, SSRF controls, MCP and A2A wrapping
Content Gate L2 + L3 Normalization, injection, DLP and secrets, PII, entropy, rate and budget
Action Gate L4 + L5 Identity-bound tool policy, argument constraints, chain detection, human approval, taint, memory guard
Evidence and Control Gate L6 + operations Signed receipts, ledger and mirror, kill switch, RBAC, configuration validation, dashboard

A request passes the layers in order:

agent -> L0 egress -> L1 mediation -> L2 normalize -> L3 detect
      -> L4 policy -> L5 memory guard -> world
                                      -> L6 signed receipt (every path, allow or deny)

The full design is in the architecture document.

Putting an agent behind it

Most paths need no change to the agent's code.

Traffic How to route it
LLM API calls Point the client's base URL at the gateway (http://127.0.0.1:8443/v1) and use a virtual key as the API key
Web and tool egress Set HTTPS_PROXY=http://127.0.0.1:8080 with the agent's identity as proxy credentials, or call GET /fetch?url=
An MCP server Wrap its command: al mcp proxy --actor <spiffe-id> -- <server command>

Issue an agent identity and a virtual LLM key, then start the gateway:

al identity issue acme research-agent      # spiffe://acme/agent/research-agent + a token, shown once
al vkey issue alice --max-requests 200 --max-tokens 200000
al gateway --host 127.0.0.1 --config configs/balanced.yaml

The gateway serves the fetch and reverse proxies on port 8443 and the CONNECT forward proxy on port 8080. Agents reach only the hosts you list under gateway.allow_hosts; an empty list denies everything.

Mediating an MCP server:

al mcp proxy --actor spiffe://acme/agent/research-agent -- npx some-mcp-server

The tool catalog is pinned and scanned for poisoning. Each tool call is authorized against the identity's policy, and only for a tool the agent was actually shown. Every server reply is scanned before the agent sees it. Every decision is receipted.

Other surfaces:

al skill check ./my-skills/        # screen and pin agent instruction files
al memory put notes/todo "..."     # screened write; a poisoned value is blocked and quarantined
al memory verify                   # check protected keys against their integrity baselines
al memory rollback                 # restore the last known-good snapshot
al killswitch engage               # deny everything, at every ingress

Evidence

Every mediated decision produces a receipt: canonicalized with RFC 8785 (JCS), SHA-256 chained to its predecessor, and signed with the mediator's Ed25519 key.

{
  "v": 1,
  "seq": 42,
  "ts": "2026-07-10T12:00:00.000Z",
  "actor": "spiffe://acme/agent/claude-code",
  "action": "mcp_tool_call",
  "target": "tool:send_email",
  "verdict": "block",
  "findings": [
    { "scanner": "tool_policy", "rule_id": "policy.default_deny", "severity": "high", "owasp": "ASI03", "mitre": "T1078" }
  ],
  "block_reason": "TOOL_NOT_ALLOWED",
  "policy_hash": "sha256:...",
  "redaction": { "aws-access-key": 1 },
  "prev_hash": "sha256:...",
  "record_hash": "sha256:...",
  "sig": "ed25519:..."
}
  • Redaction is recorded as a class-to-count map. Plaintext never reaches the ledger.
  • The append-only JSONL ledger is the source of truth. The SQLite or Postgres mirror is a query surface built from it.
  • al export --verdict block writes ECS-shaped events with MITRE ATT&CK technique tags for a SIEM. Each event carries the receipt's record_hash and sig, so an alert traces back to a receipt that can be verified.

The receipt format is a published specification: receipt-v1.

Configuration

Configuration is a YAML file chosen with --config. Three profiles ship in the wheel and are written to configs/ by al init.

audit balanced (default) strict
Scan verdicts Observed and receipted, not enforced Enforced Enforced
Permissive settings Allowed (the only mode that allows them) Refused at validation Refused at validation
Egress As configured Default-deny Default-deny, HTTPS only

Enforced in every mode, including audit: a scanner crash or timeout blocks, the memory guard's own checks, the key policy, signed rules only, the kill switch, and full evidence chaining.

Validate a profile before using it:

al check --config configs/strict.yaml

Secrets never live in YAML. The admin token, the signing key and upstream provider keys come from the environment or from mounted secrets. Environment variables use the AL_ prefix, with __ between nested keys, for example AL_GATEWAY__UPSTREAM__ANTHROPIC_API_KEY.

The annotated configuration reference is in the implementation guide.

Command reference

Command Purpose
al init Create a workspace: keys, data directory, .env, configs and policy
al check Validate configuration; exits non-zero on any error
al healthz Boot the runtime and print the health payload
al scan Run the content gate over text and print the verdict
al gateway Run the data-plane gateway
al run Run the control-plane API
al dashboard Serve the read-only evidence dashboard
al identity Issue, list and revoke agent identities
al vkey Issue, list and revoke virtual LLM keys with budgets
al policy Inspect and check the identity-bound tool policy
al mcp Mediate an MCP server; review its advertised tools
al memory Guarded memory reads and writes, snapshot and rollback
al skill Screen and pin agent instruction files
al hitl List and resolve pending human approvals
al killswitch Engage or disengage full deny-all
al export Export the ledger as SIEM events
al verify-receipt Verify a receipt or a ledger
al egress The egress bypass self-test and the nftables ruleset
al learn Mine candidate rules, approve and sign them, generate tests
al db Initialize and query the evidence mirror
al keygen Generate or rotate the signing key

Run any command with --help for its options.

Running in production

A process started with al gateway on a workstation mediates and receipts what agents send through it, and nothing at the operating-system level stops an agent from going around it. The mediator says so: startup logs advisory mode, and the signed boot receipt carries the finding egress.advisory_mode.

Enforcement comes from the container topology. The repository ships a hardened container image and a Docker Compose file that places the agent on a network whose only route out is the mediator, keeps the control plane on a separate network, and runs two boot probes that must pass before any agent starts.

  • Image: ghcr.io/neural-nomad1709/agentlighthouse, signed with cosign, with an SBOM attestation
  • Deployment guides: deployment
  • Rollout from audit to strict: rollout guide
Package What it is
agentlighthouse-verify The standalone receipt verifier. Its only dependency is cryptography. Installed with this package.
agentlighthouse-governance Organizations, role-based access, budgets and signed posture attestation, on top of this package.

Scope and limitations

Read this before relying on the mediator.

  • The detection engine is pattern matching and heuristics behind a scanner interface. It makes no machine-learning judgement.
  • The forward proxy tunnels TLS opaquely. It enforces on destination host, port and pinned IP address, and does not inspect content inside a CONNECT tunnel.
  • The identity of an A2A peer is asserted, not cryptographically proven. The mediator pins agent cards and binds sessions to their peer pair.
  • Outside the container topology the mediator is advisory, as described under Running in production.

The complete statement is in the repository's README.

Security reporting

Please do not open a public issue for a suspected vulnerability. The reporting process is in SECURITY.md.

License

MIT. See the LICENSE file shipped with this package.

Metadata

Release files for agentlighthouse-core 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for agentlighthouse-core 0.4.0
File Interpreter ABI Platform Actions
agentlighthouse_core-0.4.0-py3-none-any.whl Python 3 none any Details for agentlighthouse_core-0.4.0-py3-none-any.whl

Release files / agentlighthouse_core-0.4.0-py3-none-any.whl

Download URL agentlighthouse_core-0.4.0-py3-none-any.whl
Size 254.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cb49266b89505658e1073f95022a031f04d796c66c813d2e24285f354c434f15
BLAKE2b-256 checksum
How to use checksums
ee8840aebf914040a14713bd996cf68f0c427353c90551f8e56609d14f22b052
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for agentlighthouse-core 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.4.0 This release

1 release file No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page