Harness Docs / Architecture

Four Layers

Pin, Daemon, Enforcement, Ledger. The four architectural layers of the AiEGIS Harness. Together they form the runtime gate between an AI agent and the world.

01 / Overview

What the harness is

The AiEGIS Harness is the runtime gate between an AI agent and the world. Every action the agent wants to take — call an API, run a tool, send a message, sign a contract, move money — is intercepted by the harness, evaluated against rules, signed, logged, and either allowed or blocked. The agent cannot bypass it.

That capability decomposes into four architectural layers. They are independent enough that an operator can swap any one (e.g. use their own ledger backend) without touching the other three.

Canonical source: AIEGIS_HARNESS_SPEC.md sha d4f0b5d19066eba9.

02 / The layers

L1 — Pin

L1 / Pin

Cryptographic identity

What it does: Binds the agent to a real human on real hardware. The "pin" is the agent's Ed25519 passport — a credential issued by AiEGIS Identity that attests three facts: the hardware (TPM/SE), the human (biometric + did:web), and the agent runtime.

Why it's un-bypassable: The TPM/SE signature cannot be forged off-device. A receiver verifying the passport chain knows it is talking to this agent on this hardware, not a copy.

Where it lives in code: AiEGIS Identity surface — /identity. The harness daemon consumes a pre-issued passport from local key storage.

L2 — Daemon

L2 / Daemon

Local runtime gate

What it does: Wraps the agent's tool calls and outbound traffic. Intercepts every action before any network call leaves the machine. Attaches the L1 passport, calls L3 for a decision, writes the result to L4, and either releases the action with a signed AiEGIS token attached, or aborts.

Reference implementations: Rust (crates/harness-cli) and Python (reference-daemon/harness.py). Functional parity is verified by a 10-case side-by-side probe.

Deployment shapes: Proxy (HTTP fronting), Sidecar (per-pod gate), or SDK (in-process library). See Deployment Shapes.

L3 — Enforcement

L3 / Enforcement

Policy evaluation

What it does: Runs the action + passport through the 15-layer governance pipeline. Selects policy packs by jurisdiction. Evaluates each rule. Aggregates packs (any DENY wins). Returns ALLOW, WARN, or BLOCK.

Surface: POST /api/protect. Wire-compatible across the local reference daemon and the production cloud endpoint at https://aiegis.ie/api/protect.

Rule format: Policy-pack format spec. Reference packs (PII block, tool allowlist, rate limit) ship with the scaffold.

Reference implementation: harness_core::eval (Rust) and the same Python module above. Rego and JSONLogic are both supported; the embedded Rego subset covers the patterns used by the reference packs.

L4 — Ledger

L4 / Ledger

Append-only audit transcript

What it does: Records a signed entry for every decision, regardless of outcome. Entries are append-only — the SQLite reference backend has BEFORE DELETE and BEFORE UPDATE triggers that abort. Five-year retention floor enforced by the production deployment.

Entry shape: {ts, agent_did, action, target, decision, deciding_pack, deciding_rule, deciding_layer, deny_reason, decision_ms, harness_kid, ledger_sig}.

Surface: /grid/ledger in production. Local reference daemon writes to a SQLite file via --audit-db.

Reference implementation: harness_core::audit. Article 12 retention rules enforced by the upstream janitor.

03 / How they compose

End-to-end

An action flowing through the harness touches all four layers:

agent --tool.call-->  L2 daemon
                       │
                       ├──> attach L1 passport (Ed25519)
                       │
                       ├──> POST /api/protect ── L3 enforcement
                       │                          │
                       │                          ├──> select packs by jurisdiction
                       │                          ├──> evaluate rules in order
                       │                          └──> ALLOW | WARN | BLOCK
                       │
                       ├──> append signed entry to L4 ledger
                       │
                       └──> release action with AiEGIS token attached
                            (or abort + surface DENY to caller)

The "no token, no service" property of the harness lives at the receiver side: downstream services that adopt the harness protocol refuse any action that does not carry a valid AiEGIS token. The L4 ledger is the third-party-verifiable record that the L3 decision was actually made.

04 / What's un-bypassable today

Honest scope

Un-bypassable today (mandatory):

  • L1 hardware-bound passport — TPM/SE signature cannot be forged off-device.
  • L3 evaluation — every action that does reach /api/protect runs the full pack set.
  • L4 audit entry — append-only triggers raise on tamper.

Bypassable today (opt-in, hardening on roadmap):

  • Routing through /api/protect itself — agents voluntarily POST. Forced routing requires receivers to enforce "no AiEGIS token, no service".
  • Local daemon presence — agents can talk to /api/protect directly without the daemon. The daemon's integrity surface ("ran in approved environment") matters for L1 attestation; the L3+L4 properties still hold.

The roadmap closes both gaps via: (a) protocol adoption — receivers refuse unsigned actions; (b) signed daemon binaries — Apple-notarised + Authenticode-signed, like Sigstore but for the runtime.