FerrumDeck

FerrumDeck is a deterministic Rust enforcement plane for AI agents — it blocks the tool call in-process, it doesn't just chart it after the fact. Deny-by-default tool policy, per-run budget enforcement, runtime (Airlock) inspection, approval gates, and an append-only audit trail — all in the request path, returning an allow/deny/approve decision before the agent acts.

Enforce, don't just observe. LangSmith, Phoenix, Galileo, and Fiddler watch your agent and tell you afterward what it did. FerrumDeck sits in the call path and enforces — it returns allowed=false and the tool never fires. Observability is a dashboard you read after the incident; enforcement is the gate that prevents it. And because the gate sits in the trace, every decision it makes is itself a queryable OTel GenAI span (ferrumdeck.decision = allow|deny|approval|kill) — you enforce and observe in one pass, not two tools.

See the blind spot for yourself. docs/benchmarks/enforce-vs-observe.md runs one AgentDojo-style injection trace two ways over the same governance profile: a record-only stack that emits a span after the unsafe send_email already ran, versus the in-path gate that emits ferrumdeck.decision=deny on the same span and the call never fires. Deterministic, offline, no LLM — spans captured with an in-memory exporter so the output is real telemetry, not a mock. Reproduce with make bench-enforce-vs-observe.

And here is what enforcement costs when it is wrong. The coherence-divergence monitor's measured false-positive rate is 10.20% — 25 of 245 benign trajectories, Wilson 95% CI [7.01%, 14.63%] (corpus + method, report, make eval-coherence-fp) — so roughly one correct run in ten would be parked at an approval gate. The per-provenance breakdown is the part worth reading, because 10.20% is a weighted average over three unlike classes: real: n=5 — five trajectories captured verbatim from real agent runs, and none of them contains a single tool action, so they cannot fire the detector at all — against synthetic_grounded: 6.77% (13/192, every string drawn from this repository's own git log subjects and tool allowlist) and synthetic_authored: 25.00% (12/48, hand-written to exercise shapes no harvested text produced). Five of nine shapes never fire at all. So the headline is a property of a corpus mix this repository chose, not an estimate of what a deployed agent would meet. That number is on this screen rather than in a footnote because it is the honest cost of being in the path instead of beside it, and because FERRUMDECK_COHERENCE_MODE=enforce now refuses to activate unless a measurement like it exists and is under 14 days old. It does not refuse on the value of the rate — through 0.8.17 it did, against a threshold that was the Wilson upper bound of the measurement it gated, so it could never fail; the rate and its cost in parked runs are now reported to whoever flips the switch instead. Enforcing on an unmeasured matcher is an availability risk of unknown size.

"But won't in-path enforcement slow my agent down?" No — the decision is sub-millisecond. Measured CPU cost of the governance decision itself (Apple M4, --release, decision path only — excludes DB / queue / LLM):

Enforcement layer	p50	p95
Deny-by-default allowlist check	183 ns	192 ns
Airlock RASP inspection (benign call)	437 ns	503 ns
R1–R3 reversibility ladder	0.54 ns	0.63 ns
EU AI Act Art. 50 transparency rule	222 ns	257 ns

An LLM step costs hundreds of ms to seconds; ~1 µs of in-path governance is ~6 orders of magnitude smaller than the call it gates. Reproduce these and every other figure below with one command — see Reproduce every number on this page. This is the added decision cost, not end-to-end latency — no "fastest"/"first" claim.

Governed vs ungoverned (reproducible) — measured on a recognized public workload. The governance layer, run two ways (ungoverned = a record-only stack with no decision point; governed = the deny-by-default allowlist + Airlock RASP + spend gate deciding before execution), on citable, deterministic, offline workloads — every number regenerable and pinned to the real Rust fd_policy engine by a cargo test:

Indirect prompt injection (AgentDojo-style, arXiv:2406.13352, 17 attack / 8 benign): attack success rate 100% → 0% (17/17 blocked; Wilson CI [81.6%, 100%]) with 100% benign-task utility retained (8/8) — every attack stopped, zero false-positives on this corpus.
Spend-overrun (fixed safe-PR trajectory, 4 injected unsafe actions): 4/4 blocked vs 0/4 ungoverned, and the governed run costs 54% less (85¢ vs 184¢) because stopping the RCE / exfil / denied-tool / runaway loop saves more than the ~1 µs/decision + audit overhead.
Payment-governance (an agent overspends an AP2 mandate / x402 call): 3/3 unsafe mandates blocked, $150.95 → $0.40 — each blocked on a distinct control (bad Ed25519 signature, over-ceiling, out-of-scope merchant), every verdict audit-logged (ferrumdeck.decision span + W3C traceparent).

Reproduce every number on this page

Every figure above is regenerable, and each command exits non-zero if a number has drifted — none of them just print and pass.

Command	Verifies	Time
`make reproduce-readme-figures`	Everything on this page: the latency table, the block/benign rates with their Wilson intervals, and both spend figures	~70s, or ~2.5 min on a cold checkout (first run builds `--release`)
`make reproduce-readme-figures-fast`	The same minus latency — rates and spend only	~10s
`make reproduce-spend-gate`	Just the two spend figures, driving the AP2 gate and the x402 example end to end	~50s
`make bench-enforcement`	Re-measures the latency table without comparing it (raw criterion output + HTML report)	~2.5 min cold

All of it is deterministic and offline: no services, no API keys, no money moved. The nightly runs the first one and opens a tracking issue on drift.

Reference machine: Apple M4, --release. This matters for the latency rows and only those. The absolute nanoseconds are a property of the silicon, so on a different machine the comparison widens to an order-of-magnitude check and the output tells you which regime it applied — a nanosecond figure that fails on a different CPU would be a broken gate, not a strict one.

Rates are compared exactly; latencies are compared within a band. That asymmetry is deliberate and it is the interesting part. The rate benchmarks (17/17, 8/8, 13/13, 4/4) are seeded, offline and LLM-free — there is no clock and no sampling in the path, so a rate that moves at all is a behaviour change and any drift fails. Latency is a measurement of a busy machine; run-to-run variance here reached 4.4× at p95 under load, so p95 gets a wider band than p50, and both are sized to catch an algorithmic regression rather than background noise. Every row prints its measured/published ratio whether it passed or not, so a figure drifting toward its band is visible before it crosses.

Methodology for the latency table, including the deny and RCE-blocked cases not shown above, is in docs/benchmarks/enforcement-latency.md.

Full table, workloads, reproduce commands + honest caveats: fd-evals/GOVERNED_BENCHMARK_RESULTS.md. Each control mapped to the five risk categories in the CISA/NSA (Five Eyes) Careful Adoption of Agentic AI Services (May 2026) guidance — and the transparency control tied to EU AI Act Article 50, enforceable 2026-08-02 — in fd-evals/CONTROLS_CROSSWALK.md. Reproduce: make eval-injection-defense · make bench-governed; method + numbers also in docs/BENCHMARK.md.

x402 spend gate — budget enforcement for autonomous payments. The x402 protocol (Coinbase-contributed, now stewarded by the x402 Foundation under the Linux Foundation, 2026-07-14; Cloudflare's Monetization Gateway began charging agents per access over it 2026-07-01) lets an agent pay for a paywalled resource inline — the server answers with HTTP 402 Payment Required and a stablecoin quote, and the agent pays and retries. FerrumDeck extends the same per-agent budget that caps token spend to that new category: it prices the 402 quote in cents (a first-class cost event on the same ledger as inference), checks it against the remaining budget before the payment is authorized, and hard-stops (deny + one alert) if paying would breach the ceiling. It moves no money — a simulate → gate → record demo only. This is the same posture platform vendors are converging on (Databricks Unity AI Gateway hard spend caps over any model/agent/MCP service; FinOps FOCUS 1.4 extending cost accounting to AI token/agent economics), done deny-by-default in-path. Run it: cargo run -p ferrumdeck --example x402_spend_gate — examples/x402-spend-gate (fd_policy::x402).

Payment-rail coverage: x402 + AP2. The same pre-call spend gate now covers a second rail — Google's AP2 (Agent Payments Protocol), where a payment is pre-authorized by a signed Mandate chain rather than an inline HTTP 402 quote. Before an autonomous payment is authorized, FerrumDeck verifies the Ed25519 signature chain (a user-signed Intent Mandate + a Cart Mandate cryptographically bound to it), checks the cart is within the intent's authorized scope (merchant/category + the user's own max), and checks the cart total against the same per-task Budget::has_cost_headroom ceiling the x402 gate uses. It is deny-by-default: a missing/invalid signature, an unknown key, a cart total over the ceiling, an amount over the intent max, or a merchant outside scope all hard-stop the payment — verifying real signatures, not trusting a flag. The authorized payment folds into the same cost_cents ledger as x402 + tokens, and emits the same governance evidence (W3C-trace-context decision span + an audit record). Verification is pinned by cargo test -p fd-policy --test ap2_gate; the governed-vs-ungoverned AP2 numbers ship as a row in the benchmark below (fd_policy::ap2).

▶ Run the 5-minute reproducible demo → — one command boots the local stack and, against the real gateway API, you watch a budget-breach auto-kill and a denied tool call happen in-process. It's self-verifying: each guarantee is asserted with jq and the script exits non-zero on failure, so you get a hard pass/fail, not a screenshot to trust.

Status: early / alpha, built primarily by one maintainer. The governance core — per-agent deny-by-default tool allowlists, per-run/per-agent budget enforcement, DB-backed tenant isolation, and Airlock RASP at the gateway tool-policy check — is implemented and tested. Several advertised layers are still being wired end-to-end. See Project Status & Limitations for an honest map of what enforces today vs. what's on the roadmap before you rely on it.

Install from crates.io

The enforcement engine is published — you can depend on it, not just clone it. One dependency via the umbrella crate:

Current version: v0.8.19. cargo add ferrumdeck pulls the latest published release. The --features audit variant below has resolved since 0.8.4 — the release that first published ferrumdeck-audit; on 0.8.0–0.8.1 that command errored, because the crate was unpublished and the name unclaimed. (This version line is asserted against the workspace version by a test, so it can't silently go stale.)

cargo add ferrumdeck

use ferrumdeck::{PolicyEngine, ToolAllowlist};

let engine = PolicyEngine::default();
let allowlist = ToolAllowlist { allowed_tools: vec!["read_file".into()], approval_required: vec![], denied_tools: vec!["delete_repo".into()] };
assert!(engine.evaluate_tool_call_with(&allowlist, "read_file").is_allowed()); // allowed
assert!(engine.evaluate_tool_call_with(&allowlist, "delete_repo").is_denied()); // denied
assert!(engine.evaluate_tool_call_with(&allowlist, "unknown").is_denied());     // deny-by-default

Prefer the engine directly (no umbrella)? cargo add ferrumdeck-policy — the import path is still use fd_policy::…. Primitives only: ferrumdeck-core (use fd_core::…). All three are Apache-2.0. (Published as ferrumdeck* because the bare fd-core name is taken on crates.io by an unrelated crate; the Rust import paths are unchanged.)

The 0.8.0 headline feature — the audit trail + out-of-band chain-head checkpoint anchoring (#14: verify_against_checkpoints, CheckpointSigner) — ships as ferrumdeck-audit (import path fd_audit), wired into the umbrella as an optional audit feature so it doesn't bloat the lean engine:

cargo add ferrumdeck --features audit

access path ferrumdeck::audit (e.g. ferrumdeck::audit::CheckpointSigner, ferrumdeck::audit::verify_against_checkpoints).

Two more crates are published so the claims that rest on them can be inspected without cloning:

cargo add ferrumdeck-otel   # import path `fd_otel`
cargo add ferrumdeck-dag    # import path `fd_dag`

ferrumdeck-otel is the crate the OTel claims on this page actually rest on — the GenAI semantic conventions, the enforcement-decision spans with their stable ferrumdeck.* attributes, cost decomposition, and W3C trace-context extraction from MCP _meta (SEP-414). It was workspace-internal until 0.8.11, which meant the span contract this README describes was one nobody outside the repository could check. ferrumdeck-dag is the dependency-ordering scheduler: cycle detection and topological order, no execution and no policy, useful on its own.

The remaining crates (fd-registry, fd-storage, and the gateway service) are workspace-internal today — they build from a clone but are not published.

What the default omits, and why audit is opt-in. A plain cargo add ferrumdeck gives you the enforcement engine — deny-by-default tool policy, per-run budgets, Airlock RASP — but not the audit hash-chain and signed chain-head checkpoints, which sit behind --features audit. That's deliberate, not an oversight: the audit trail is a separate concern from the in-path allow/deny decision (it pulls in Ed25519 signing and is about after-the-fact tamper-evidence, not stopping the call), so the default stays the lean policy engine most callers reach for. Turn it on when you need tamper-evident record-keeping — e.g. EU AI Act Art. 12/19 logging or Colorado SB 26-189 retention.

Python plane: install from source only. Only the Rust enforcement engine is published to a package registry (crates.io). The Python data-plane packages (fd-runtime, fd-worker, fd-mcp-router, fd-mcp-tools, fd-evals, fd-cli) and the workspace-root ferrumdeck package are not on PyPI — their version numbers are internal workspace versions, not PyPI releases. Install them from a clone with uv: uv sync. What the Python plane is, why it exists, and what to use instead — including why the HTTP contract in contracts/, not fd-runtime, is the interface to build against.

What this proves

FerrumDeck is the control plane, not the agent — the production layer that makes an autonomous agent safe to run: it decides which tools a run may call, kills runs that blow their budget, gates risky actions on a human, and records every decision in an immutable trail. It's built as a credibility artifact for an AgentOps / AI-infrastructure audience.

▶ Run the 5-minute reproducible demo → — one command boots the local stack and verifies, against the real gateway API, the four guarantees below:

Deny-by-default tool policy — a run may only call tools on its per-agent allowlist; everything else is denied. (POST /v1/runs/{id}/check-tool)
Budget auto-kill — every run carries a hard token / cost / tool-call / wall-time budget; a breach kills the run and appends a budget.exceeded event. (fd_policy::budget → RunStatus::BudgetKilled)
Coherence-divergence caught mid-run — when an agent states a blocking fact ("tests failing", "permission denied") and then advances as if it were untrue, the live monitor catches it on the run stream and applies the reversibility ladder (R1–R3). (fd_policy::airlock::coherence)
Immutable audit trail — every policy, budget, and approval decision is appended to audit_events; the repository exposes no UPDATE/DELETE.
OTel GenAI spans — and every enforce decision is one — every LLM/tool step emits OpenTelemetry GenAI-semconv spans to Jaeger, and so does every enforcement decision: the tool-policy check writes a gen_ai.tool.call span carrying ferrumdeck.decision = allow|deny|approval|kill, ferrumdeck.reason, ferrumdeck.rung (R1–R3), and ferrumdeck.budget_remaining, so the allow/deny you enforce is the span you query. Naming follows the GenAI-semconv stability opt-in (OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental → execute_tool + gen_ai.operation.name); Rust gateway and Python worker write one schema. (fd_otel::decision · fd_runtime.tracing)

The demo is self-verifying — it asserts each property with jq and exits non-zero on failure, so it works as a smoke test, not a screenshot. For an honest map of what enforces today vs. what's still being wired, see Project Status & Limitations.

Reproduced: indirect-prompt-injection defense-path coverage

Against a vendored AgentDojo-style (arXiv:2406.13352) indirect-injection corpus (25 cases: 17 attacks — off-allowlist tools, RCE payloads, data-exfil destinations — and 8 benign controls), FerrumDeck's deny-by-default tool allowlist + Airlock RASP block:

Metric	Value	95% CI (Wilson)
Block-rate under attack	100.0% (17/17)	[81.6%, 100%]
Benign-task utility preserved	100.0% (8/8)	[67.6%, 100%]

One-command repro (deterministic, offline, no LLM required):

uv run python -m fd_evals injection-defense --suite injection_defense   # or: make eval-injection-defense

Honest framing: this measures defense-path coverage on a fixed governance profile — the fraction of injected malicious tool calls the policy/RASP layer blocks — not model robustness, and not a general "injection-proof" claim. The corpus is pinned to the real Rust fd_policy RASP by cargo test -p fd-policy --test injection_defense (which runs the actual AirlockInspector over every case), and the fd-evals mirror must agree with it. Small vendored corpus ⇒ a wide CI; the number moves as the corpus grows. No "first"/"best" claim.

Second axis: Agent Security Bench (ASB) + an EU AI Act Art. 50 transparency rule

The injection_defense axis above is AgentDojo (indirect injection). The asb axis adds a second, complementary set: attack classes from Agent Security Bench (arXiv:2410.02644) that AgentDojo does not cover — the Plan-of-Thought (PoT) backdoor, memory poisoning, and direct prompt injection — run through the same governance path plus the R1–R3 reversibility ladder. The point of difference: a backdoored plan that reaches an allowlisted-but-irreversible action (a deploy, an apply_migration) is stopped not by the allowlist but by the R3 rung (irreversible → require_approval, so it never auto-executes). That is graduated enforcement catching an attack a static allowlist would wave through.

Metric	Value	95% CI (Wilson)
ASB block-rate under attack	100.0% (13/13)	[77.2%, 100%]
Benign-task utility preserved	100.0% (8/8)	[67.6%, 100%]
Art. 50: non-compliant responses denied	100.0% (6/6)	[61.0%, 100%]
Art. 50: compliant responses preserved	100.0% (4/4)	[51.0%, 100%]

Of the 13 ASB attacks, 4 are stopped specifically by the R3 reversibility rung (the PoT-backdoor class), the rest by deny-by-default, the anti-RCE matcher, and the exfiltration shield.

The EU AI Act Article 50 rule (fd_policy::transparency_art50) is a transparency enforcement rule on the same R1–R3 ladder: a governed generative response must carry a human-readable AI disclosure and a machine-readable synthetic-content marker; in enforce mode a response missing either is denied before release (R3), in shadow it is logged (R1).

One-command repro (deterministic, offline, seeded, no LLM):

uv run python -m fd_evals asb --suite asb --seed 0   # or: make eval-asb

Honest framing: the ASB number measures whether the malicious action is stopped from auto-executing on a fixed governance profile — not that FerrumDeck detects the backdoor trigger or the poisoned memory semantically, and not model robustness (no LLM). The Art. 50 rule is a structural check (presence of a disclosure phrase + a machine-readable marker), not a truthfulness or standard-conformance (C2PA/SynthID) judgement. Both are pinned to the real Rust enforcement by cargo test -p fd-policy --test asb_defense — which runs the actual ToolAllowlist + AirlockInspector + reversibility ladder and the real transparency_art50 rule over every case, and asserts the R3 rung is the decisive layer for the PoT class — and the fd_evals.asb mirror must agree. Small vendored corpus ⇒ wide CIs. No "first"/"best" claim.

Live-fire: a drifting run is caught and R-tiered (deterministic, no stack)

examples/demo/coherence-drift.py feeds a deliberately drifting trajectory through the same detection core the live gateway runs on each step, and is self-verifying (exits non-zero if the drift is not caught). Real captured output:

▸ Drifting run — states a blocking fact, then advances as if it were untrue
  ✗ DIVERGENCE [test_failure] confidence=1.00
      stated:       '2 tests failed: assertion error in auth flow'
      then did:     'git_commit: commit: fix auth flow'
      response:     R3 (require_approval)   shadow → record + surface   enforce → GATE run → WaitingApproval
      sse coherence.divergence.detected {category:test_failure, response_rung:R3, gated(enforce):True}
  ✗ DIVERGENCE [permission_denied] confidence=1.00
      stated:       'deploy blocked: permission denied on prod'
      then did:     'deploy: shipping to production, reporting success'
      response:     R3 (require_approval)   shadow → record + surface   enforce → GATE run → WaitingApproval

▸ Coherent control — resolves the fact before advancing (must NOT fire)
  ✓ no divergence — the resolved run is clean

COHERENCE OK ✓  2 divergences fired (both R3), control clean. In enforce mode each R3 gates the run for review.

Against the live gateway the same divergence writes an audit_events row with violation_type=coherence_divergence, emits the coherence.divergence.detected SSE event, and surfaces on the run's Coherence card. It runs shadow by default (records + surfaces, never blocks); set FERRUMDECK_COHERENCE_MODE=enforce to gate an R3 divergence (run → WaitingApproval). Setting it is a request, not a switch: the gateway refuses to activate enforce mode unless a measured false-positive rate is in the committed series and no more than 14 days old, and says so on /ready. There is no maximum-rate threshold: deriving one needs gated-run volume and time-to-clear, which only the operator has, so the gate reports the rate rather than vetting it. Enforcing on an unmeasured matcher is an availability risk of unknown size. This is the enforce-not-observe wedge: FerrumDeck acts on the drift, it doesn't just chart it.

Mapping to the DeepMind AI Control Roadmap (D1–D4 / R1–R3)

Google DeepMind's AI Control Roadmap (2026-06-18, blog) frames agent security on two axes: Detection tiers D1–D4 (set by the model's detection-evasion capability — how hard a misaligned agent is to catch) and Prevention & Response tiers R1–R3 (set by the model's attack-execution capability — how strong the response must be). FerrumDeck already names this ladder in fd_policy::reversibility (anchor deepmind-ai-control-roadmap-r1-r3). To be precise and avoid overclaiming: D1–D4 is an adversary-capability rating, not something a defense tool "is" — FerrumDeck maps onto the R-tier response axis and the roadmap's operational metrics, not onto a self-assigned detection tier.

Response tier → FerrumDeck mechanism (R3 = synchronous block-before-execute; R1 = asynchronous review-after-the-fact):

Roadmap tier	What the roadmap requires	FerrumDeck mechanism (today)
R3 — synchronous	block a harmful action before it executes	Deny-by-default tool-policy check (`POST /v1/runs/{id}/check-tool` returns `allowed=false`, tool never fires); budget auto-kill (`RunStatus::BudgetKilled`); coherence divergence in `enforce` mode — an R3 divergence gates the run → `WaitingApproval`
R2 — conditional	proceed only while it stays within bounds	Reversibility ladder `allow_under_budget` — a costly action proceeds while the budget gate has headroom, else escalates to R3
R1 — asynchronous	record + review the transcript, remediate after	coherence divergence in `shadow` mode (default) records + surfaces the R-tier but does not gate; post-hoc `CoherenceMonitor::scan_trajectory`; the append-only `audit_events` trail

Detection → the roadmap's live metrics. DeepMind measures a control system by coverage (fraction of agent traffic monitored), recall (fraction of misaligned behaviors caught), and time-to-response:

Coverage — the CoherenceMonitor observes the run's trajectory event stream (each submitted step), so coverage is the fraction of the run stream it sees. (Honest limit: today it is fed at the gateway step-submission choke point, not the in-loop agentic executor — see Project Status & Limitations.)
Recall — the divergence pattern is the Strained-Coherence signal (arxiv:2606.07889); the shared cross-plane golden fixture pins detection so recall doesn't silently regress.
Time-to-response — CoherenceMonitor::observe_event fires mid-run, the instant a divergence completes, before the run finishes — not only in a post-hoc autopsy. That is what moves the same signal from R1 (async) to R3 (synchronous) when enforce is on.

Honest scope. R3 enforcement of a coherence divergence is opt-in (FERRUMDECK_COHERENCE_MODE=enforce) and shadow-by-default. The heuristic is a lexical matcher, and its measured false-positive rate is 10.20% (25 of 245 benign trajectories, Wilson 95% CI [7.01%, 14.63%]; make eval-coherence-fp, report, per-provenance breakdown) — so roughly one correct run in ten would be parked at an approval gate, and gating is a deliberate choice for high-consequence agents (the roadmap's own point: R1 async review is insufficient for critical-infrastructure agents where a harmful action can't be undone after the fact). min_confidence ships at 0.0 — no suppression — and that is a stated position, not a default nobody set. Through 0.8.17 it shipped at 0.5 against a score that could never fall below 0.6375, so the threshold was disconnected and no operator could tell. The scale is now a true [0, 1] and the knob works (0.5 would cut the false-positive rate to 4.08%), but the default is left wide open because suppressing 60% of detections trades false positives for false negatives and this all-benign corpus cannot price that trade. The mapping above is machine-checked: examples/demo/coherence-drift.py prints and asserts the R3 → "DeepMind R3: synchronous block-before-execute" label and that the enforce path gates it, exiting non-zero if that ever stops holding. Several advertised layers remain in-progress — see Project Status & Limitations before relying on any tier.

Overview

FerrumDeck solves the critical challenge of running AI agents safely in production. While LLMs are probabilistic and unpredictable, production systems require deterministic governance, audit trails, and budget controls.

The Problem

AI agents can make costly mistakes (token spend, wrong tool calls)
Prompt injection attacks can bypass safety measures
No visibility into what agents are doing in production
Difficult to reproduce and debug agent failures
Compliance requirements demand audit trails

The Solution

FerrumDeck provides a dual-plane architecture:

Control Plane (Rust)	Data Plane (Python)
Deterministic state	Probabilistic execution
Policy enforcement	LLM interactions
Budget tracking	Tool calls via MCP
Audit logging	Step execution
Approval gates	Artifact storage

Project Status & Limitations

FerrumDeck is an early-stage / alpha project, built primarily by a single maintainer. It is a real, working control plane — but it is not yet production-hardened. This is an honest map of what enforces today vs. what is scaffolded or on the roadmap, so you can evaluate it without surprises.

The CRA clock

EU Cyber Resilience Act Article 14 reporting obligations begin 2026-09-11: a 24-hour early warning, a 72-hour notification and a 14-day final report, filed to the coordinating CSIRT and ENISA through the Single Reporting Platform. Those windows are short enough that the evidence has to already exist when the clock starts — which is what FerrumDeck's hash-chained audit log is designed to produce: an ordered, tamper-evident record of what an agent was permitted to do, what it attempted, what was blocked, and who approved what and how long they took. FerrumDeck does not file anything, does not notify anyone, and is not a compliance product. It produces evidence; deciding whether an incident is reportable, and reporting it, stays with the operator. Which evidence classes the log actually covers — and, more usefully, which it does not — is set out per class in docs/compliance/safe-evidence-coverage.md.

Concurrent writes no longer drop audit records. Until 0.8.12 AuditRepo::create read the tenant's chain tip FOR UPDATE and inserted at tip + 1; that lock does not stop a concurrent transaction inserting a new maximum, and at genesis there was no row to lock at all. Two writers could collide on idx_audit_events_chain, nothing retried the loser, and because the hot-path caller is fire-and-forget the event was lost — while the surviving chain still verified, because the missing chain_seq was never allocated. Measured: 17 of 24 concurrent writers collided. A transaction-scoped per-tenant advisory lock closes it; rust/crates/fd-storage/tests/audit_chain_collision.rs drives the same race and asserts zero collisions, zero drops and a contiguous chain_seq run. Two honest limits remain: a write that fails for any other reason (connection loss, disk) is still dropped by the fire-and-forget caller — logged at ERROR with the tenant and index so it is countable — and rows written by anything that bypasses AuditRepo::create are outside the guarantee.

Implemented and enforced (covered by the Rust test suite):

Deny-by-default tool policy, per agent. The gateway evaluates every tool call against the run's agent allowlist (allowed / approval-required / denied tiers) — not a process-global default.
Budget enforcement, per run / per agent. The auto-kill and the cost forecast evaluate against the run's effective budget (per-run config.budget override → agent-version caps → engine default).
Tenant isolation. Project-scoped access is gated by a DB-backed project → workspace → tenant ownership check; unknown project or tenant mismatch is denied.
Airlock RASP at the gateway tool-policy check (POST /v1/runs/{id}/check-tool): all five layers run here, in shadow or enforce mode — the anti-RCE pattern matcher (for tools named in airlock.rce.target_tools only — see the qualifier below), the financial/velocity circuit breaker, and the data-exfiltration + credential-DLP shield on every call, plus the schema-drift guard (validates tool_input against the tool version's registered input schema) when the tool has a registered version and the behavioral-drift monitor (per-agent rolling z-score on cost) when the run's agent is known. The gateway attaches the guard + monitor at boot (state.rs) and threads tool_version_id / agent_id into the inspection context (check_tool_policy). The schema-drift guard is seeded at boot from the tool_versions table and refreshed live on every tool registration (create_tool calls guard.upsert), so a version registered after boot is drift-checked without a restart. A tool version with no compiled schema is fail-open by default; FERRUMDECK_SCHEMA_DRIFT_FAIL_CLOSED=true flips that case to deny-by-default.

Two layers are name-matched — and their defaults used to match nothing. Layer 1 (anti-RCE) and Layer 3 (exfiltration + credential DLP) each filter by tool NAME before doing any work. Until 0.8.12 Layer 1 defaulted to eight shell-shaped literals (bash, python_repl, write_file, …) and Layer 3 to eight HTTP-shaped ones (http_get, curl, send_email, …). Neither matched anything in a deployment that names its tools after its own domain — including this one, whose seed registers git_read / git_write / test_run / github_create_pr. Both layers inspected zero of four while reporting enabled and passing their tests.

Both defaults are now empty, meaning inspect every tool. Fail-closed is the right default for a security layer. Measured on a seeded stack, same payload before and after: git_write went from risk_score: 0 to risk_score: 90, violation: rcepattern, and github_create_pr with a link-local URL now returns violation: ipaddressused. Benign calls still score 0.

Narrowing is still supported — set target_tools to control cost or a specific false positive — and the gateway reconciles each layer's list against the registry at boot, logs a WARN naming both lists when a layer covers nothing, and reports airlock_coverage.{anti_rce,exfiltration}.status (full / partial / blind / disabled) on GET /ready.

Airlock still defaults to shadow, which records violations without blocking them. Detection and refusal are different things; set FERRUMDECK_AIRLOCK_MODE=enforce for the latter.
Enforcement on the agentic execution path. The Python worker's in-loop agentic executor authorizes every tool call against the control-plane check-tool endpoint before it runs: allow → execute, deny → refuse, requires_approval → do not execute (the run is gated pending approval). The local allowlist is only a cheap pre-filter, never the final authority, and the path fails closed — if the control plane is unreachable the call is refused (configurable via AGENTIC_FAIL_CLOSED, default on). (Previously this loop only checked a local allowlist and executed approval-required tools anyway; fixed 2026-07-27.)
Append-only audit trail for policy, budget, approval, routing, and promotion decisions (the repository exposes no UPDATE/DELETE).
Coherence-divergence monitor, wired live at the gateway run stream. As each step is submitted, the run's trajectory is fed to the CoherenceMonitor; a stated-blocking-fact → contradicting-closure-action divergence surfaces mid-run through the same airlock.violation_detected audit path, is persisted on the run row (coherence_divergence_flagged), and emitted on the completion span. A reliability signal — it never blocks a tool or kills a run.

Scaffolded / not yet wired end-to-end — do not rely on these yet:

Trace→signal loop (HarnessX). The harness-suggestion governance endpoints (/v1/harness-suggestions*) and the training-signal export (POST /v1/runs/{id}/training-signal, redacted server-side via the audit redaction path) are implemented, unit-tested, and wired into the dashboard. The evals dashboard read path is no longer stubbed: /api/v1/evals/* serves the gateway's real on-disk reports, mapped onto the dashboard's run contract, and returns an explicit 501 (never an empty list) when no report store is reachable. Two defects on that path were fixed at once — the gateway parsed only the offline-benchmark file-naming convention, so every safe-PR smoke and regression report was silently dropped before it reached the dashboard, and the BFF proxied the gateway's field names verbatim, so even the runs that did arrive rendered as blank cells. The live round-trip is now verified (0.8.13): against a running gateway, GET /v1/evals/runs served 36 runs from evals/reports and the newest matched its file field for field. Every figure carries measured_at with its precision and its source — second-precision from the report body for the LLM suites, day-precision from the file name for the offline benchmarks, which record no timestamp at all. File mtime is deliberately never consulted: on a fresh clone it would report the moment of the clone as the moment of the run. The store is a database now (0.8.14, #46): dispatched runs and committed reports live in one eval_runs table, with evals/reports/*.json as its import source rather than a second query surface. A suite can be dispatched from the dashboard and the run persists. But no eval executor consumes the queue, so a dispatched run stays pending with queued_at set and started_at null. That is reported rather than disguised — the gateway answers 202 Accepted, never 201, the body says no executor has claimed the run, and the list carries unclaimed: true. An empty store still returns 501 rather than an empty 200: eval_ingests records that an ingest happened, which is what keeps "we looked and found none" distinct from "we never looked" now that the store is a database the gateway cannot start without. (The eval numbers themselves are not ungated: the deterministic governance suites + real-engine pins run on every push + PR via ci.yml's eval-regression job.) Approving a suggestion records the decision; it never auto-applies a policy/allowlist/budget change.
Eval gating — deterministic suites gate PRs; the LLM-backed nightly does not yet, and the regression suite's assertion coverage is 50%. docs/eval-health.md is generated from the committed report files on every nightly run and shows, per eval, the last run date, pass/fail, score, consecutive-pass streak and assertion coverage.

That page is a snapshot — each refresh overwrites yesterday's answer, so a number that has held steady for a month and one that has never been re-measured render identically. The record is docs/eval-health-series.jsonl: one append-only row per eval run carrying the measurement date, the commit that produced it, the numbers, and the harness version that produced them — the last because two of this repo's eval numbers changed without the agent changing at all. The page reprints the most recent rows so drift is visible without opening the data. The file is never rewritten; a row found to be wrong is corrected by appending a row with correction_of and reason, and CI fails if the committed file stops being a prefix of the working one.

Read the coverage before the score. On its most recent committed run the regression suite scored 1.00 with assertion coverage of 50%: half of its scorer results asserted nothing at all and returned a full score for having nothing to check, so that 1.00 is an average over the covered half only, not over twenty tasks. smoke sits at 100% coverage.

That 50% is measured on the 2026-08-16 run, which predates the rescope in the same commit. schema_valid was removed from the suite because no task declared an output_schema, so it skipped on every task while contributing a full score. The suite now declares three scorers, of which expected_output_match still reports "No output expectations declared" on all twenty tasks — so the next run should land near 67%, not 100%. The figure on the eval-health page will stay at 50% until the suite is re-run, and it is labelled with its run date there. It is LLM-backed, so re-running it costs real model calls; it has not been re-run purely to refresh a number. This is stated plainly on the eval-health page and is repeated here because "eval gating in CI" — which is also in this repository's GitHub description — reads as a stronger claim than a half-covered suite supports. The deterministic suites that gate every PR (injection_defense, asb, the governed benchmark) are a different matter: they are seeded, offline, LLM-free and assert on real engine output. An eval that has never passed is labelled NEVER PASSED in its own row. Read that page before trusting any eval-gating claim here — it is the evidence, and it opens by stating in prose what the safe-PR numbers mean. docs/eval-verdicts.md carries the companion judgement: one row per eval saying whether its score is evidence about the agent or about the harness, with the reproduction command. In short: the safe-PR suites do not measure safe-PR agent quality. Their dataset expects files changed, a PR opened and tests passing against example/project, which does not exist and which this control plane never clones — so the suites were rescoped to assert what is genuinely observable here (policy decisions, budget compliance, non-degenerate output). The expectations no scorer reads are reported on every run rather than averaged past. There is no eval in this repo that measures whether the agent writes good pull requests, and nothing here should be read as claiming there is.
Audit tamper-evidence — detectable up to the last checkpoint, not tamper-proof. The log is append-only (repo API with no UPDATE/DELETE path and the trg_audit_events_append_only trigger, migration 20260719000001) and hash-chained: migration 20260801000001 adds prev_hash/record_hash/chain_seq, each row's SHA-256 commits to its predecessor over a canonical encoding (rust/crates/fd-audit/src/chain.rs), and AuditRepo::verify_chain catches any insertion, deletion, or edit within a tenant's chain. The chain alone left one honest gap — a privileged actor who rewrites the entire tail (dropping the trigger, recomputing every downstream hash) can produce a self-consistent chain, because they hold every input. That gap is now closed by signed head checkpoints (rust/crates/fd-audit/src/checkpoint.rs): a small (tenant_id, chain_seq, record_hash, checkpointed_at) record, signed with an Ed25519 key that is not the database's, is appended to an out-of-band sink (FileCheckpointSink ships; the CheckpointSink trait takes object storage or a transparency log later). verify_against_checkpoints proves the chain has not been rewritten past the most recent checkpoint — because a record's hash transitively commits to its whole prefix — and names the checkpoint it verified against. The guarantee, stated exactly: tampering is detectable up to the most recent checkpoint; records after it keep only the in-chain guarantee (that window is reported, not hidden), a missing checkpoint degrades to the in-chain guarantee and says so rather than silently passing, and this is detection, not prevention — not tamper-proof, and only as strong as the sink being genuinely out-of-band and the signing key off-box (a file sink on the DB host is a weak anchor). Shipped for #14; a robust remote sink + off-host key custody is the remaining hardening.
Multi-tenant SaaS hardening. Tenant isolation is enforced, but there is no dashboard auth/session layer, no SSO/RBAC, and no API-key self-service — treat the dashboard + gateway as a trusted-operator deployment for now.
Realtime run stream (SSE) — all five events push; replay is per-process. The gateway serves GET /v1/events/{channel} and pushes every run-channel governance event: policy.response.recorded, policy.decision.explained, routing.decision.recorded, coherence.divergence.detected and run.forecast.updated. Each is published only after the record it describes has committed — from inside the audit write for the four backed by audit_events, and on the Ok arm of an awaited update_forecast for the forecast, whose record is the run row and which therefore carries forecast_at rather than a record_id. A failed write publishes nothing, because silence is the correct signal when there is no record to read back. Two limits, both deliberately accepted with the reasoning recorded on #47. The replay buffer is per process, so a reconnect that lands on a different replica of a multi-replica gateway cannot be served completely — it emits a stream.gap naming the range rather than a stream that merely looks quiet. And every SSE connection counts against RATE_LIMIT_PER_MINUTE: one token per connect, not per event, with a correct Retry-After on the 429, so a reconnect storm is throttled rather than exempted. Two of the five have not been watched arriving on a real socket: coherence.divergence.detected needs a multi-step trajectory and routing.decision.recorded needs a workflow run the dev seed cannot satisfy. Both have database-backed ordering tests. The BFF can emit synthetic events for wire-shape development behind FERRUMDECK_SSE_MOCK_EVENTS, but that flag is OFF by default in every environment, so a fabricated enforcement verdict can never reach an operator's console.
The gateway serves no /v1/audit list route. GET /v1/audit/{event_id} was added in 0.8.13 so the record_id on a pushed decision event resolves, but the dashboard's BFF has proxied GET /v1/audit?<query> for some time and that target has never existed, so the proxy forwards to a 404. scripts/check_route_backing.py counts the BFF route as backed because it contains a real fetch( — true, and not the same as the target existing. Recorded rather than fixed in passing.

Testing caveat. The unit/lint suites (cargo test --workspace, clippy, ruff, jest) pass and gate CI. The tests/security, tests/chaos, and tests/e2e suites require a live stack (make dev-up) and skip without it. Hardening them to assert behaviour (not liveness) is in progress (#6): test_airlock.py (RCE, raw-IP exfil, credential DLP), test_policy_engine.py, test_input_validation.py (command injection), and test_owasp_llm.py (deny-by-default tool policy) now assert the actual enforcement decision — the specific violation_type + risk band, or allowed=false — and the tests/chaos suite's simulated no-ops are now explicit skips naming the fault-injection plumbing they need, not green tautologies. The Airlock layer decisions also have a runnable, no-Docker backbone in rust/crates/fd-policy/tests/airlock_decisions.rs + airlock_layers_fire.rs.

One headline case per suite has since been converted to a behavioural assertion: tests/security asserts that a denied tool call leaves no side effect and a durable record (with a negative control, so it cannot pass against an engine that records every call as blocked); tests/chaos asserts that a policy decision taken before a Postgres outage is identical after recovery; tests/e2e asserts that an exhausted cost budget refuses the next call rather than logging and continuing. None of the three has been observed passing against a live gateway — they are written against the real routes and skip cleanly without a stack, but the assertions themselves are unverified until someone runs them with make quickstart up, and a dedicated live-stack CI job is still the missing infra piece on #6. Fixing the two conftests that made this visible is a finding in its own right: tests/chaos and tests/e2e probed /health/live, a route the gateway does not serve, so both suites skipped unconditionally against any stack and CHAOS-001 has never once executed. Still liveness-only and deferred on #6: the rest of tests/e2e, the remaining tests/security/test_audit_trail.py cases, and the stateful/obfuscation cases (velocity, coherence, base64/unicode evasion) — do not read those as proof that a given attack is blocked.

Automated test coverage. The CI-gating unit/lint suites total 2,113 tests, re-derivable with make claims-recount: Rust 829 (cargo test --workspace -- --list), Python unit 553 (pytest over the four python/packages/*/tests the CI unit job runs), frontend 681 (jest), and API-contract 50 (pytest tests/api). The live-stack suites — tests/security (84), tests/chaos (14), tests/e2e (43) — need make dev-up, skip without it, and (per the caveat above) are still being converted from liveness to behaviour, so they are excluded from that headline; tests/integration (81) is likewise live-stack and non-gating.

Those counts are collected, which is not the same as run. Until 0.8.9 the three suites reported 135 collected, 135 skipped, 0 executed and the CI check was green throughout, because a skipped test and a passing test are indistinguishable in a green check. They now run against a real stack in the live-stack-tests job under an executed-test floor of 102 — of the 141 collected, at least 102 must actually execute or the build fails, with a message naming the usual cause (a service that did not come up, a readiness probe pointing at a route the gateway does not serve, an unseeded API key). These counts live in the single source docs/feature-status.yml and are held to the README by the claims-integrity CI check (make check-claims).

The known gaps above are tracked in the open on the roadmap, one GitHub issue each under the roadmap label. Found a gap not listed there? Please open an issue — accurate status is a feature.

Key Features

Governance

Deny-by-Default Tools: Only explicitly allowed tools can be called
Approval Gates: High-risk actions require human approval before execution
Budget Enforcement: Automatic run termination when limits exceeded (tokens, cost, time)
Predictive Budget Forecast: Deterministic linear + EWMA projection of end-of-run cost after every step, surfacing a budget_breach_projected flag on the run API + SSE event (run.forecast.updated) before the auto-kill fires. See docs/runbooks/budget-forecast.md.
Policy Engine: Configurable rules for tool access and risk management
Airlock RASP: Five runtime self-protection layers — anti-RCE pattern matcher, financial circuit breaker, data-exfiltration shield, schema-drift guard, behavioral-drift monitor — in shadow or enforce mode. All five fire at the gateway tool-policy check: anti-RCE / financial / exfil on every call, schema-drift when the tool has a registered version, behavioral-drift when the run's agent is known. The schema-drift guard is seeded at boot and refreshed live on every tool registration (no restart needed); a tool version with no compiled schema is fail-open by default, or deny-by-default under FERRUMDECK_SCHEMA_DRIFT_FAIL_CLOSED=true.
Explicit Conflict Resolution + Decision Traces: When multiple policies match a tool call, a named precedence function (Deny > RequiresApproval > BudgetCap > Allow) picks the winner deterministically, and every decision carries an audit-grade trace of matched verdicts and overrides surfaced on the run API + policy.decision.explained SSE event. See docs/runbooks/policy-conflict-resolution.md.
Routing-Decision Audit (multi-agent coordination): Every time the orchestrator binds a subtask to a concrete agent / role / model, a RoutingDecision record (candidates considered, chosen binding, reason code, SHA-256 content hash) is written through the existing immutable audit trail and surfaced on GET /v1/runs/{id}/routing plus the routing.decision.recorded SSE event. fd-evals replays compare the content hash to detect coordination drift. Anchor: AgensFlow (arXiv:2605.27466). See docs/runbooks/routing-decision-audit.md.
Champion-Challenger Promotion Gate: A registered challenger version cannot replace the live champion until it clears a deterministic gate — configurable metric thresholds (inclusive floors) plus a required human approval. Deny-by-default: the challenger stays in shadow until explicitly promoted. The decision + metric evidence (SHA-256 content hash for tamper-evidence) flow through the same PolicyDecision channel every gate uses and are written to the immutable audit trail. Exposed on POST /v1/promotions/evaluate (write scope) + GET /v1/promotions/{agent_id}, surfaced on the agent dashboard (champion vs challenger + gate status). See docs/runbooks/champion-challenger-promotion.md.
Reversibility-Aware Graduated Response (R1–R3 ladder): A Reversibility { reversible, costly, irreversible } dimension on the tool registry — orthogonal to the existing risk tiers — drives a graduated response at the gateway tool-policy check, modelled on the DeepMind AI Control Roadmap R1–R3 ladder: reversible → R1 allow-and-log (monitor, no gate); costly → R2 allow-under-budget while the run's cost budget has headroom, escalating to R3 when exhausted; irreversible → R3 require-approval (the existing human-in-the-loop gate). Deny-by-default: an unregistered tool defaults to irreversible. The chosen rung is folded into the allowlist decision more-restrictive-wins (it can only add friction, never loosen a Deny), emitted on the OTel span (ferrumdeck.policy.response_level) + the immutable audit log, returned from POST /v1/runs/{id}/check-tool, and surfaced on the run console as an R1/R2/R3 badge (read from the polled run endpoint; the realtime policy.response.recorded SSE shape is defined, with gateway→BFF push deferred). See docs/runbooks/graduated-response-levels.md.
Eval-Driven Harness Suggestions (trace→delta, HarnessX): fd-evals turns the aggregate signal across an eval run's trace into a proposed harness/policy delta — e.g. "run cost exceeded the cap on 7/10 runs → propose a tighter per-call cap" — and POSTs it to the control plane. The HarnessSuggestion is content-hashed and written to the immutable audit trail (same store as the promotion gate, no parallel channel), exposed on POST /v1/harness-suggestions + GET /v1/harness-suggestions/agent/{agent_id} + POST /v1/harness-suggestions/{id}/resolve, and surfaced on the eval-run dashboard with a review/approve panel. Human-in-the-loop, deny-by-default: approving records the decision in the audit trail and never auto-applies a change to a live policy, allowlist, or budget — applying remains a separate, explicit step.
Delegation-Aware Budget Leases: The stateless budget gate compares an accumulated usage snapshot against a cap, which lets a parent task that delegates to N children collectively spend up to N × the cap — every child checking the same cap believes it owns the whole budget (the Token-Budgets delegation-fanout class). A BudgetLease closes that gap: all leases in one delegation tree share a single atomic remaining-budget pool, a child is handed a sub-lease carved from (not copied alongside) the parent's authority, and every spend decrements the one shared pool — so total spend across parent + children can never exceed the root cap, even under concurrent fan-out. The lease is move-only (!Copy, !Clone): a lease moved into a delegated child is a compile error if the parent reuses it, runtime-rejected otherwise. Anchor: Token Budgets (arXiv:2606.04056).
x402 Pre-Call Spend Gate (autonomous payments): Extends the per-agent cost budget from token/model spend to paid-API spend. When an agent's outbound call hits an x402 402 Payment Required response, the gate parses the quoted price (X402Challenge — amount, asset, scheme), normalizes it to cents (a first-class X402CostEvent that folds into the same cost_cents ledger as inference, so a run's cost slope includes autonomous payments), and checks it against the remaining per-agent budget before the payment is authorized — reusing the exact Budget::has_cost_headroom primitive the R2 reversibility rung uses. A quote that would breach the ceiling is hard-stopped (deny + exactly one alert, mapped to a PolicyDecision::deny); a quote in an asset with no known USD peg is denied by default (you cannot check a cents budget against an unpriceable quote). It never moves money — a gate + cost model, not a wallet; settlement lives outside FerrumDeck. The paid call rides the existing OTel decision span (ferrumdeck.cost.x402_cents alongside token cost). Runnable, self-verifying demo: cargo run -p ferrumdeck --example x402_spend_gate (examples/x402-spend-gate). (fd_policy::x402)
AP2 Signed-Mandate Spend Gate (autonomous payments, 2nd rail): The same pre-call spend gate, extended to Google AP2 payments authorized by a signed Mandate chain. evaluate_ap2_payment verifies the Ed25519 signature chain — a user-signed Ap2IntentMandate (scope: merchants/categories + max amount) and an Ap2CartMandate cryptographically bound to it by intent_id — then checks the cart against the intent's authorized scope and the same per-task Budget::has_cost_headroom ceiling the x402 gate enforces, all before the payment is authorized. Deny-by-default on every failure mode (Ap2DenyKind): missing/invalid signature, unknown signing key, cart-not-bound-to-intent, non-USD/unpriceable total, merchant/category/amount outside scope, or cart total over the budget ceiling — real signature verification, not a trusted flag. The authorized payment normalizes to an Ap2CostEvent that folds into the same cost_cents ledger as x402 + tokens, and emits the same evidence (W3C-trace-context decision span + audit record; ferrumdeck.cost.ap2_cents). Never moves money — verify + gate + record only. Pinned to the real Ed25519 engine by cargo test -p fd-policy --test ap2_gate; surfaced as a governed-vs-ungoverned row in make bench-governed. (fd_policy::ap2)

Observability

OpenTelemetry Integration: Full distributed tracing with GenAI semantic conventions
Cross-MCP trace correlation (MCP SEP-414): When a caller propagates W3C trace context in the tool-call request _meta (traceparent/tracestate/baggage), ferrumdeck parents its enforcement decision span on that context — so the decision joins your trace end-to-end (host → client SDK → MCP server → ferrumdeck decision → downstream) and the trace-id lands on the persisted decision record. Malformed traceparent is rejected (never propagated); off unless the OTel semconv opt-in is set. Targets the 2026-07-28 MCP revision (now the current, ratified spec — verified 2026-08-01) and implements the SEP-414 conventions — not a conformance claim (no MCP conformance suite has been run). See docs/mcp-trace-conformance.md.
Cost Tracking: Real-time token counting and cost calculation per run
Jaeger UI: Visual trace exploration and debugging
Realtime run stream (SSE): the dashboard subscribes to per-run / per-workspace channels. ⚠ all five run-channel events push; the replay buffer is per-process — the gateway serves GET /v1/events/{channel} and pushes all five governance events for real: policy.response.recorded, policy.decision.explained, routing.decision.recorded, coherence.divergence.detected and run.forecast.updated. Each is published only after the record it describes has committed, so an id on the wire is an id that resolves — an event that outran its record could not be told apart from one describing a write that never happened. A synthetic generator can emit them for wire-shape development behind FERRUMDECK_SSE_MOCK_EVENTS — OFF by default in every environment, so no fabricated enforcement verdict can ever reach an operator's console. (#47)
Audit Trail: Append-only logging of every action — enforced by the repo API (no UPDATE/DELETE path), a DB trigger (trg_audit_events_append_only: rejects every UPDATE; rejects DELETE within the 3-year retention floor), a per-tenant cryptographic hash-chain (prev_hash/record_hash/chain_seq; each row's SHA-256 commits to its predecessor, computed in one FOR UPDATE transaction) that makes any insertion/deletion/edit within a chain detectable by AuditRepo::verify_chain, and signed out-of-band head checkpoints (fd-audit's CheckpointSigner/FileCheckpointSink) that catch even a wholesale self-consistent tail rewrite via verify_against_checkpoints. ⚠ tamper-evident up to the last signed checkpoint; not tamper-proof — detection, not prevention: records after the last checkpoint keep only the in-chain guarantee, a missing checkpoint degrades to it (and says so), and the anchor is only as strong as an out-of-band sink + off-host key (#14). Don't represent it as tamper-proof for compliance.
Tool-call firing rate: Derived OTel signal (ferrumdeck.metrics.tool_call_firing_rate) tracking the share of reasoning steps that invoked at least one tool, per run + per agent over a sliding window. Surfaced on the agent overview tab with a configurable low-firing-rate threshold (default 40%) that flags model regressions or broken tool registries before they propagate. See docs/runbooks/tool-call-firing-rate.md.
Debt-vs-tax cost decomposition (§2605.27320): Per-call span_role ∈ {primary, retry, judge, guardrail, escalation, revalidation, monitor} classification on every LLM/tool call, with two derived rollups per task/run — agent.cost.token (primary calls = debt) and agent.cost.tax (everything else). Dashboard panel ranks tasks by tax / (token + tax) descending so retry / escalation storms are visible at a glance. See docs/runbooks/cost-decomposition.md.
Claim grounding rate — grounding rate per VeriGraph (arXiv:2606.16603): A per-run reliability metric (ferrumdeck.reliability.claim_grounding_rate, 0.0–1.0) — the fraction of the final agent output's claims that are reachable from a raw-data / tool-output source node via the run's evidence graph, per VeriGraph's claim-level grounding definition. This is a lineage to the claim-level auditability literature, not a ferrumdeck-original metric. Computed at run completion (Rust fd_otel::claim_grounding, mirrored by Python fd_evals.claim_grounding for the eval plane, with a shared golden fixture pinning cross-plane agreement), persisted on the run row next to cost/tokens, emitted on the run span, and rendered as a stat card on the run console. Honest scope: the "reachable evidence path" is operationalized as a deterministic lexical-overlap reachability proxy (sentence-split claims; a claim is grounded when enough of its significant tokens are covered by a source node) — pure and CI-stable, not an LLM judge or semantic-entailment model. It is a reliability signal only: a project may set an optional min_claim_grounding_rate in its settings to flag (never block or kill) a run below it — off by default, preserving the deny-by-default posture for tool permissions, not reliability scoring. See docs/runbooks/claim-grounding-rate.md.

Reproducibility

Versioned Registry: Agents, tools, and prompts are version-controlled
Step-Level Replay: Debug specific steps with exact inputs
Deterministic IDs: ULID-based identifiers for time-ordered, collision-resistant tracking

Quality

Evaluation Framework: Deterministic offline test suites for agent workflows (the fd-evals framework runs the reproducible benchmarks above). ⚠ read + dispatch live; no eval executor consumes the queue — GET /api/v1/evals/{suites,suites/{id},runs,regression-report} serve a durable eval_runs store, with evals/reports/*.json as its import source rather than a second query surface. Every figure carries measured_at with its precision and source. A suite can be dispatched from the dashboard and the run persists — but no executor consumes the queue, so it answers 202 Accepted and the run stays pending, reported as unclaimed rather than dressed up as running (#46).
Regression Gating: the eval suite reports quality regressions between versions. ⚠ PR gate covers the 3 deterministic suites; LLM-judged suite stays nightly — ci.yml's eval-regression job runs the injection-defense / ASB / governed-vs-ungoverned suites + the real fd_policy engine pins on every push + PR (no services, no secrets), so a golden-fixture or engine-pin regression blocks a merge. The LLM-judged smoke/regression suite still runs nightly in evals.yml, not on PRs (#7).
Baseline Comparisons: Track performance across versions. ⚠ read + dispatch live; no eval executor consumes the queue — the baseline view reads the same /api/v1/evals/* data, which is real and now verified end to end; each regression names the measurement time of both endpoints it compares (#7).
Per-harness eval dimension (Harness-Bench): fd-evals reports at the (model × harness_config) level — same model under different harness configs can produce different scores. Each run records its tools_available, permission_tier, state_recovery, and tracing config alongside the existing baseline, the dashboard groups results by (model × harness) with a side-by-side Recharts bar chart, and DeltaReport exposes a per-dimension diff (added/removed tools, tier change, recovery change). See docs/runbooks/harness-config.md.
Training-signal export (trace→signal, HarnessX): closes the eval loop the other way — projects a run's trace into a JSONL of (state, action, observation, outcome_score) tuples for downstream training/eval. Built server-side at POST /v1/runs/{id}/training-signal, where every state/observation is run through the existing audit redaction path (fd_audit::redaction) so PII/secrets are stripped before they ever leave the control plane; outcome_score is trace-intrinsic (step status) with an optional eval-supplied run_score override. The dashboard exposes a per-suite/per-run "Download training signal" action.

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                              Clients                                      │
│              (Dashboard / CLI / SDK / CI Pipelines)                      │
└─────────────────────────────────────────────────────────────────────────┘
        │                           │                           │
        ▼                           ▼                           ▼
┌─────────────────┐    ┌──────────────────────────────────────────────────┐
│    DASHBOARD    │    │                CONTROL PLANE (Rust)               │
│   (Next.js)     │    │                                                   │
│                 │    │  ┌───────────┐  ┌──────────┐  ┌──────────────┐   │
│ • Runs Monitor  │◀──▶│  │  Gateway  │  │  Policy  │  │   Registry   │   │
│ • Approvals     │    │  │  (Axum)   │  │  Engine  │  │  (Versioned) │   │
│ • Analytics     │    │  │           │  │          │  │              │   │
│ • Audit Trail   │    │  │ • REST    │  │ • Budget │  │ • Agents     │   │
│ • Evals UI      │    │  │ • SSE     │  │ • Rules  │  │ • Tools      │   │
│                 │    │  │ • Auth    │  │ • Gates  │  │ • Versions   │   │
└─────────────────┘    │  └───────────┘  └──────────┘  └──────────────┘   │
   :3001/:8000         │                                                   │
                       │  ┌───────────┐  ┌──────────┐  ┌──────────────┐   │
                       │  │   Audit   │  │   DAG    │  │    OTEL      │   │
                       │  │    Log    │  │Scheduler │  │    Setup     │   │
                       │  └───────────┘  └──────────┘  └──────────────┘   │
                       └──────────────────────────────────────────────────┘
                                              │
                          ┌───────────────────┼───────────────────┐
                          ▼                   ▼                   ▼
                   ┌───────────────┐   ┌───────────────┐   ┌───────────┐
                   │   PostgreSQL  │   │     Redis     │   │   Jaeger  │
                   │   (pgvector)  │   │    Streams    │   │    UI     │
                   │               │   │               │   │           │
                   │ • runs/steps  │   │ • Job Queue   │   │ • Traces  │
                   │ • agents/tools│   │ • Pub/Sub     │   │ • GenAI   │
                   │ • audit_events│   │               │   │   Spans   │
                   └───────────────┘   └───────┬───────┘   └───────────┘
                        :5433                  │                :16686
                                               ▼
              ┌───────────────────────────────────────────────────────────┐
              │                      DATA PLANE (Python)                    │
              │                                                             │
              │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
              │  │    Worker    │  │     LLM      │  │    MCP Router    │  │
              │  │              │  │   Executor   │  │                  │  │
              │  │ • Poll Queue │  │              │  │ • GitHub MCP     │  │
              │  │ • Execute    │  │ • Claude     │  │ • Filesystem MCP │  │
              │  │ • Report     │  │ • GPT-4      │  │ • Custom Tools   │  │
              │  │ • Retry      │  │ • litellm    │  │ • Policy Checks  │  │
              │  └──────────────┘  └──────────────┘  └──────────────────┘  │
              └───────────────────────────────────────────────────────────┘

Data Flow

Client creates a run via POST /v1/runs
Gateway authenticates, validates, creates run in PostgreSQL
Gateway enqueues first step to Redis Stream
Worker polls Redis, fetches step details from Gateway
Worker executes step (LLM call, tool call, etc.) with tracing
Worker reports result back to Gateway
Gateway updates state, checks budget, enqueues next step
Repeat until run completes or fails

Service Ports

Service	Port	Description
Gateway	`8080`	REST API (Rust control plane)
Dashboard	`3001` / `8000`	Next.js UI (dev) / Static server
PostgreSQL	`5433`	Database (pgvector enabled)
Redis	`6379`	Queue and cache
Jaeger UI	`16686`	Distributed tracing
OTel Collector	`4317` / `4318`	gRPC / HTTP endpoints

Receipts schema

The control plane's append-only audit log is documented as a stable receipts substrate compatible with Foundation Protocol (Mila + MetaGPT). See docs/receipts-schema.md for the canonical AuditEvent shape, the FP event-substrate mapping (metering / receipt / settlement / policy / provenance / audit), the wrap-don't-replace stance on downstream consumers, and the per-call p95 budget. Drift is gated by the audit_record_schema_drift integration test in rust/crates/fd-audit/tests/.

Quick Start

Just want to see it work? Run the one-command reproducible demo (./examples/demo/run-demo.sh) — it boots the stack and self-verifies deny-by-default policy, the approval gate, the immutable audit trail, and OTel spans in Jaeger.

Prerequisites

Rust 1.80+ (rustup.rs)
Python 3.12+
Docker & Docker Compose
uv (docs.astral.sh/uv) - Fast Python package manager

1. Clone and Setup

git clone https://github.com/sattyamjjain/ferrumdeck.git
cd ferrumdeck

# Copy environment file
cp .env.example .env

# Start infrastructure (PostgreSQL, Redis, Jaeger)
make dev-up

# Install all dependencies
make install

# Run database migrations
make db-migrate

# Build everything
make build

2. Start Services

# Terminal 1: Start the Gateway (Rust)
make run-gateway
# Gateway running at http://localhost:8080

# Terminal 2: Start a Worker (Python)
make run-worker

3. Create Your First Run

# Create an API key (dev mode)
export API_KEY="fd_dev_key_abc123"

# Create a run
curl -X POST http://localhost:8080/v1/runs \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_safe_pr_agent",
    "input": {
      "task": "Review the latest changes in the repository"
    }
  }'

# Check run status
curl http://localhost:8080/v1/runs/{run_id} \
  -H "Authorization: Bearer $API_KEY"

4. Open the Dashboard

# Start the dashboard (static server)
make run-dashboard
# Open http://localhost:8000

# Or run the Next.js development server
cd nextjs && npm run dev
# Open http://localhost:3001

The dashboard provides a complete UI for:

Monitoring runs in real-time
Approving/rejecting tool calls
Managing agents and tools
Viewing analytics and audit trails

5. View Traces

Open Jaeger UI at http://localhost:16686 to see distributed traces.

Project Structure

ferrumdeck/
├── .github/
│   └── workflows/           # CI/CD pipelines
│       └── ci.yml          # Main CI (lint, test, build, eval gate)
│
├── contracts/               # API Contracts
│   ├── openapi/            # OpenAPI 3.1 specifications
│   │   └── control-plane.openapi.yaml
│   └── jsonschema/         # JSON Schema definitions
│       ├── run.schema.json
│       ├── policy.schema.json
│       ├── tool.schema.json
│       └── workflow.schema.json
│
├── rust/                    # Control Plane (Rust)
│   ├── crates/             # Shared libraries
│   │   ├── fd-core/        # IDs, errors, config, time utilities
│   │   ├── fd-policy/      # Policy engine, budgets, rules
│   │   ├── fd-registry/    # Agent/tool versioning
│   │   ├── fd-audit/       # Audit logging, redaction
│   │   ├── fd-storage/     # PostgreSQL repos + Redis queue
│   │   ├── fd-dag/         # DAG scheduler
│   │   └── fd-otel/        # OpenTelemetry setup
│   └── services/
│       └── gateway/        # Axum HTTP API service
│
├── python/                  # Data Plane (Python)
│   └── packages/
│       ├── fd-runtime/     # Workflow execution, tracing, client
│       ├── fd-worker/      # Queue consumer, step execution
│       ├── fd-mcp-router/  # MCP tool routing with policy checks
│       ├── fd-mcp-tools/   # MCP server implementations (git, test runner)
│       ├── fd-cli/         # Command-line interface
│       └── fd-evals/       # Evaluation framework with scorers
│
├── nextjs/                  # Dashboard (Next.js 16.1)
│   ├── src/
│   │   ├── app/            # App Router pages
│   │   │   └── (dashboard)/ # Dashboard route group
│   │   │       ├── runs/       # Run monitoring & detail
│   │   │       ├── approvals/  # Approval queue
│   │   │       ├── agents/     # Agent registry
│   │   │       ├── tools/      # Tool registry
│   │   │       ├── workflows/  # Workflow management
│   │   │       ├── analytics/  # Usage charts
│   │   │       ├── audit/      # Audit trail viewer
│   │   │       ├── evals/      # Evaluation results
│   │   │       ├── policies/   # Policy management
│   │   │       ├── logs/       # Container logs
│   │   │       └── settings/   # API keys & config
│   │   ├── components/     # React components (shadcn/ui)
│   │   ├── hooks/          # Custom React hooks
│   │   ├── lib/            # API client, utilities
│   │   └── types/          # TypeScript interfaces
│   └── Dockerfile          # Multi-stage production build
│
├── evals/                   # Evaluation Suite
│   ├── suites/             # Test suite definitions (YAML)
│   │   ├── smoke.yaml      # Quick smoke tests
│   │   └── regression.yaml # Full regression suite
│   ├── datasets/           # Test datasets
│   ├── agents/             # Agent configs for testing
│   ├── scorers/            # Scorer configurations
│   └── reports/            # Generated reports (gitignored)
│
├── examples/                # Example Agents
│   └── safe-pr-agent/      # PR review agent example
│       ├── agent.yaml      # Agent configuration
│       └── workflow.yaml   # Multi-step workflow
│
├── deploy/
│   └── docker/
│       ├── compose.dev.yaml    # Local development stack
│       ├── Dockerfile.gateway  # Gateway Docker build
│       └── Dockerfile.worker   # Worker Docker build
│
├── config/
│   └── mcp-config.json     # MCP server configuration
│
├── observability/
│   └── otel/
│       └── collector.yaml  # OTel Collector configuration
│
├── docs/                    # Documentation
│   ├── architecture/       # System design docs
│   ├── adr/                # Architecture decisions
│   ├── security/           # Security documentation
│   └── runbooks/           # Operational guides
│
├── Cargo.toml              # Rust workspace manifest
├── pyproject.toml          # Python workspace manifest (uv)
├── Makefile                # Development commands
└── .env.example            # Environment template

Components

Control Plane (Rust)

fd-core — Foundation Primitives

Type-safe IDs, error handling, and configuration.

ID System (ULID-based with prefixes):

TenantId     // ten_01ARZ3NDEKTSV4RRFFQ69G5FAV
AgentId      // agt_01ARZ3NDEKTSV4RRFFQ69G5FAV
RunId        // run_01ARZ3NDEKTSV4RRFFQ69G5FAV
StepId       // stp_01ARZ3NDEKTSV4RRFFQ69G5FAV
PolicyRuleId // pol_01ARZ3NDEKTSV4RRFFQ69G5FAV

Error Types:

NotFound, Validation, Unauthorized, Forbidden
PolicyDenied, BudgetExceeded, ApprovalRequired
Database, Queue, ExternalService, Internal

fd-policy — Policy Engine

Governance rules enforcement with deny-by-default security.

Tool Allowlist:

pub struct ToolAllowlist {
    allowed_tools: Vec<String>,      // Explicitly allowed
    approval_required: Vec<String>,  // Require human approval
    denied_tools: Vec<String>,       // Explicitly denied
}
// Priority: Denied > Approval Required > Allowed > Default Deny

Budget System:

pub struct Budget {
    max_input_tokens: Option<u64>,   // Default: 100,000
    max_output_tokens: Option<u64>,  // Default: 50,000
    max_total_tokens: Option<u64>,   // Default: 150,000
    max_tool_calls: Option<u32>,     // Default: 50
    max_wall_time_ms: Option<u64>,   // Default: 5 minutes
    max_cost_cents: Option<u64>,     // Default: $5.00
}

Tool Risk Levels:

Level	Description	Examples
Low	Read-only operations	read_file, list_directory
Medium	Limited mutations	write_file (with approval)
High	External communications	send_email, create_pr
Critical	Security-sensitive	deploy, payment, delete

fd-registry — Versioned Registry

Immutable, version-controlled storage for agents and tools.

// Agent versions are immutable - changes require new versions
pub struct AgentVersion {
    id: AgentVersionId,
    agent_id: AgentId,
    version: String,           // Semantic version: "1.2.3"
    system_prompt: String,
    model: String,             // "claude-sonnet-4-20250514"
    allowed_tools: Vec<String>,
    model_params: Value,       // temperature, max_tokens, etc.
    changelog: String,
}

fd-storage — Database & Queue

PostgreSQL repositories with SQLx compile-time checked queries:

RunsRepo, StepsRepo, AgentsRepo, ToolsRepo
PoliciesRepo, ApiKeysRepo, AuditRepo, WorkflowsRepo

Redis Streams for reliable job queuing:

Consumer groups for horizontal scaling
Automatic acknowledgment and retry
Message format: StepJob with context

fd-audit — Audit Trail

Append-only, immutable event logging:

Run creation/completion
Tool calls (allowed/denied)
Policy decisions
Approval resolutions
API key usage

Gateway Service

Axum-based HTTP API with middleware:

Authentication: API keys (SHA256 hashed) or OAuth2 JWT
Rate Limiting: Per-tenant request limiting
Request ID: X-Request-ID for distributed tracing

Data Plane (Python)

fd-runtime — Runtime Primitives

Models:

class RunStatus(Enum):
    CREATED, QUEUED, RUNNING, WAITING_APPROVAL,
    COMPLETED, FAILED, BUDGET_KILLED, POLICY_BLOCKED

class StepType(Enum):
    LLM, TOOL, RETRIEVAL, SANDBOX, APPROVAL

class Budget(BaseModel):
    max_input_tokens: int = 100_000
    max_output_tokens: int = 50_000
    max_total_tokens: int = 150_000
    max_tool_calls: int = 50
    max_wall_time_ms: int = 300_000  # 5 minutes
    max_cost_cents: int = 500        # $5.00

Control Plane Client:

client = ControlPlaneClient(base_url, api_key)
run = await client.create_run(agent_id, input_data)
await client.submit_step_result(run_id, step_id, output, status)

Tracing (GenAI Semantic Conventions):

with trace_llm_call(model="claude-sonnet-4", run_id=run.id) as span:
    response = await llm.complete(messages)
    set_llm_response_attributes(span, response)
    # Automatically tracks: tokens, cost, latency

fd-worker — Step Executor

Queue consumer that executes individual steps:

async def run_worker():
    consumer = RedisQueueConsumer(redis_url)
    executor = StepExecutor(
        control_plane_url,
        api_key,
        mcp_servers=load_mcp_config(),
        tool_allowlist=allowlist,
    )

    while running:
        job = await consumer.poll()
        if job:
            await executor.execute(job)

Retry Strategy (exponential backoff):

@retry(
    retry=retry_if_exception_type(RETRYABLE_EXCEPTIONS),
    stop=stop_after_attempt(3),
    wait=wait_exponential(min=1000, max=30000)
)
async def execute_with_retry(step):
    ...

fd-mcp-router — Tool Router

Deny-by-default MCP tool routing:

class MCPRouter:
    async def call_tool(self, tool_name: str, args: dict) -> ToolResult:
        # 1. Check allowlist (deny-by-default)
        status = self.allowlist.check(tool_name)
        if status == "denied":
            return ToolResult(success=False, error="Tool not allowed")
        if status == "requires_approval":
            # Pause and wait for human approval
            ...

        # 2. Find server and execute
        server = self.find_server(tool_name)
        return await server.call(tool_name, args)

Supported MCP Servers:

GitHub (@modelcontextprotocol/server-github)
Filesystem (@modelcontextprotocol/server-filesystem)
Custom servers (stdio or HTTP-based)

fd-cli — Command Line Interface

# Runs
fd run create --agent agt_xxx --input '{"task": "..."}'
fd run status <run_id>
fd run logs <run_id> --follow

# Registry
fd agent list
fd agent get <agent_id>
fd tool list

# Approvals
fd approval list
fd approval approve <approval_id>
fd approval reject <approval_id> --reason "..."

# Evaluations
fd eval run --dataset evals/datasets/safe-pr-agent.jsonl
fd eval report --output reports/latest.html

fd-evals — Evaluation Framework

Deterministic testing for agent workflows:

runner = EvalRunner(
    scorers=[
        FilesChangedScorer(),
        PRCreatedScorer(),
        TestPassScorer(),
        LintScorer(),
    ],
    control_plane_url=url,
)

summary = runner.run_eval(
    dataset_path="evals/datasets/safe-pr-agent.jsonl",
    agent_id="agt_safe_pr_agent",
    max_tasks=20,
)
# Returns: pass_rate, avg_score, cost_per_task, regressions

fd-mcp-tools — MCP Server Implementations

Built-in MCP tool servers for common operations:

# Git operations server
from fd_mcp_tools import GitMCPServer

# Test runner server
from fd_mcp_tools import TestRunnerMCPServer

Dashboard (Next.js)

A professional admin UI built with Next.js 16.1.1, React 19.2, and Tailwind CSS 4.

Key Pages

Page	Description
`/overview`	Dashboard home with key metrics and recent activity
`/runs`	Real-time run monitoring with step timeline visualization
`/runs/{runId}`	Detailed run view with step-by-step execution trace
`/approvals`	Approval queue with approve/reject actions
`/agents`	Agent registry with version management
`/tools`	Tool registry and MCP server status
`/workflows`	Multi-step workflow definitions and runs
`/analytics`	Usage charts, cost tracking, performance metrics
`/audit`	Immutable audit trail viewer with filtering
`/evals`	Evaluation suite results and comparisons
`/policies`	Policy configuration and management
`/threats`	Airlock RASP violations — RCE / velocity / exfil / schema-drift / behavioral-drift
`/logs`	Container and service logs viewer
`/settings`	API key management and configuration

Technology Stack

Next.js 16.1.1      # App Router with standalone output
React 19.2.3        # Concurrent features, Server Components
Tailwind CSS 4      # Utility-first styling with dark theme
TanStack Query 5    # Server state with polling (2-3s intervals)
TanStack Table 8    # Data tables with sorting/filtering
Radix UI            # Accessible component primitives
shadcn/ui           # Pre-built component library
Recharts 3          # Analytics visualizations
nuqs 2              # URL state management
sonner 2            # Toast notifications

Running the Dashboard

# Development (hot reload)
cd nextjs && npm install && npm run dev
# Open http://localhost:3001

# Production build
npm run build
npm start  # Runs on port 3001

# Static dashboard (simple HTTP server)
make run-dashboard
# Open http://localhost:8000

# Docker
docker build -t ferrumdeck-dashboard nextjs/
docker run -p 3001:3001 \
  -e GATEWAY_URL=http://gateway:8080 \
  -e FD_API_KEY=fd_dev_key_abc123 \
  ferrumdeck-dashboard

Environment Variables

GATEWAY_URL=http://localhost:8080     # Control plane URL
FD_API_KEY=fd_dev_key_abc123          # API key for authentication
NEXT_PUBLIC_POLL_INTERVAL=2000        # Polling interval (ms)

API Proxy (BFF Pattern)

The dashboard proxies all API calls through /api/v1/* routes:

// src/app/api/v1/[...path]/route.ts
// Forwards requests to GATEWAY_URL with authentication

API Reference

Authentication

All API requests require authentication via Authorization header:

# API Key
Authorization: Bearer fd_tenant_abc123xyz

# Or OAuth2 JWT
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Endpoints

Runs

Method	Endpoint	Description
POST	`/v1/runs`	Create a new run
GET	`/v1/runs`	List runs with filtering
GET	`/v1/runs/{runId}`	Get run details
POST	`/v1/runs/{runId}/cancel`	Cancel a running run
GET	`/v1/runs/{runId}/steps`	List steps in a run
POST	`/v1/runs/{runId}/steps/{stepId}`	Submit step result (worker)
POST	`/v1/runs/{runId}/check-tool`	Check tool policy before execution

Registry

Method	Endpoint	Description
GET	`/v1/registry/agents`	List agents
POST	`/v1/registry/agents`	Create agent
GET	`/v1/registry/agents/{agentId}`	Get agent details
GET	`/v1/registry/agents/{agentId}/versions`	List agent versions
POST	`/v1/registry/agents/{agentId}/versions`	Create agent version
GET	`/v1/registry/agents/{agentId}/stats`	Get agent statistics
GET	`/v1/registry/tools`	List tools
POST	`/v1/registry/tools`	Create tool
GET	`/v1/registry/tools/{toolId}`	Get tool details
GET	`/v1/registry/mcp-servers`	List MCP servers

Approvals

Method	Endpoint	Description
GET	`/v1/approvals`	List pending approvals
PUT	`/v1/approvals/{approvalId}`	Approve or reject

Policies

Method	Endpoint	Description
GET	`/v1/policies`	List policies
POST	`/v1/policies`	Create policy
GET	`/v1/policies/{policyId}`	Get policy details
PATCH	`/v1/policies/{policyId}`	Update policy
DELETE	`/v1/policies/{policyId}`	Delete policy

API Keys

Method	Endpoint	Description
GET	`/v1/api-keys`	List API keys
GET	`/v1/api-keys/{keyId}`	Get API key details
POST	`/v1/api-keys/{keyId}/revoke`	Revoke an API key

Workflows

Method	Endpoint	Description
POST	`/v1/workflows`	Create workflow
GET	`/v1/workflows`	List workflows
GET	`/v1/workflows/{workflowId}`	Get workflow
GET	`/v1/workflows/{workflowId}/runs`	List workflow runs
POST	`/v1/workflow-runs`	Execute workflow
GET	`/v1/workflow-runs/{runId}`	Get execution status
POST	`/v1/workflow-runs/{runId}/cancel`	Cancel workflow run
GET	`/v1/workflow-runs/{runId}/executions`	List step executions
POST	`/v1/workflow-runs/{runId}/executions`	Create step execution
POST	`/v1/workflow-runs/{runId}/executions/{executionId}`	Submit step result

Health & Documentation

Method	Endpoint	Description
GET	`/health`	Liveness probe
GET	`/ready`	Readiness probe
GET	`/docs`	Swagger UI documentation
GET	`/api-docs/openapi.json`	OpenAPI specification

Example: Create a Run

curl -X POST http://localhost:8080/v1/runs \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_safe_pr_agent",
    "input": {
      "task": "Review PR #123 in repo owner/repo",
      "repository": "owner/repo",
      "pr_number": 123
    },
    "config": {
      "budget": {
        "max_total_tokens": 50000,
        "max_cost_cents": 100
      }
    }
  }'

Response:

{
  "id": "run_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "agent_id": "agt_safe_pr_agent",
  "status": "queued",
  "created_at": "2024-12-24T10:00:00Z"
}

Configuration

Environment Variables

Create a .env file from .env.example:

# ============================================
# Application
# ============================================
FERRUMDECK_ENV=development
FERRUMDECK_LOG_LEVEL=debug
FERRUMDECK_LOG_FORMAT=pretty  # or "json" for production

# ============================================
# Gateway
# ============================================
GATEWAY_HOST=0.0.0.0
GATEWAY_PORT=8080
GATEWAY_WORKERS=4

# ============================================
# Database (PostgreSQL)
# ============================================
DATABASE_URL=postgres://ferrumdeck:ferrumdeck@localhost:5433/ferrumdeck
DATABASE_MAX_CONNECTIONS=20
DATABASE_MIN_CONNECTIONS=5

# ============================================
# Queue (Redis)
# ============================================
REDIS_URL=redis://localhost:6379
REDIS_QUEUE_PREFIX=fd:queue:

# ============================================
# LLM Providers
# ============================================
ANTHROPIC_API_KEY=sk-ant-api03-xxx
OPENAI_API_KEY=sk-xxx
DEFAULT_MODEL=claude-sonnet-4-20250514

# ============================================
# OpenTelemetry
# ============================================
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_SERVICE_NAME=ferrumdeck
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=1.0

# ============================================
# Worker
# ============================================
FD_API_KEY=fd_dev_key_abc123
CONTROL_PLANE_URL=http://localhost:8080
WORKER_CONCURRENCY=4
WORKER_MAX_RETRIES=3

# ============================================
# OAuth2 (Optional)
# ============================================
OAUTH2_ENABLED=false
OAUTH2_JWKS_URI=https://your-provider/.well-known/jwks.json
OAUTH2_ISSUER=https://your-provider/
OAUTH2_AUDIENCE=api://ferrumdeck
OAUTH2_TENANT_CLAIM=tenant_id

MCP Server Configuration

Configure MCP servers in config/mcp-servers.json:

{
  "servers": [
    {
      "name": "github",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    }
  ],
  "allowlist": {
    "allowed": [
      "read_file", "list_directory", "search_files",
      "get_file_contents", "list_commits", "get_pull_request"
    ],
    "approval_required": [
      "write_file", "create_file", "create_pull_request",
      "create_issue", "push_files"
    ],
    "denied": [
      "delete_file", "delete_branch", "merge_pull_request"
    ]
  }
}

Security Model

Defense in Depth

FerrumDeck implements multiple security layers. The first five sit outside the run; the sixth — Airlock RASP — runs inside every tool dispatch.

┌─────────────────────────────────────────────────────────┐
│ Layer 1: Authentication                                  │
│   • API Keys (HMAC-SHA256 hashed, scoped)               │
│   • OAuth2/JWT with tenant claims                       │
├─────────────────────────────────────────────────────────┤
│ Layer 2: Deny-by-Default Tools                          │
│   • Explicit allowlist required                         │
│   • Risk level classification                           │
│   • Per-agent tool restrictions                         │
├─────────────────────────────────────────────────────────┤
│ Layer 3: Budget Enforcement                             │
│   • Token limits (input, output, total)                 │
│   • Cost limits (in cents)                              │
│   • Time limits (wall clock)                            │
│   • Automatic run termination                           │
├─────────────────────────────────────────────────────────┤
│ Layer 4: Approval Gates                                 │
│   • Human-in-the-loop for sensitive actions             │
│   • Configurable per tool                               │
│   • Timeout with auto-rejection                         │
├─────────────────────────────────────────────────────────┤
│ Layer 5: Audit Trail                                    │
│   • Immutable event logging                             │
│   • Every action recorded                               │
│   • Compliance-ready                                    │
├─────────────────────────────────────────────────────────┤
│ Layer 6: Airlock RASP — runtime self-protection         │
│   • Anti-RCE pattern matcher                            │
│   • Financial circuit breaker (velocity + loop guard)   │
│   • Data exfiltration shield                            │
│   • Schema-drift guard (per ToolVersion)                │
│   • Behavioral-drift monitor (per-agent z-score)        │
│   • Shadow vs Enforce modes                             │
└─────────────────────────────────────────────────────────┘

Airlock RASP

Lives in rust/crates/fd-policy/src/airlock/. Inspects every tool call in-process — five concrete checks composed on a single AirlockInspector, no plugin chain. The inspector runs at the gateway boundary and surfaces violations to the /threats dashboard page.

#	Layer	Signal	Failure mode caught
1	RCE Pattern Matcher (`patterns.rs`)	Regex over tool-call args	`eval()`, `exec()`, `os.system`, shell metacharacters, base64+eval obfuscation, path traversal
2	Velocity / Circuit Breaker (`velocity.rs`)	Per-run spend + identical-call counter	Runaway cost, infinite tool-call loops
3	Exfiltration Shield (`exfiltration.rs`)	URL extraction + domain allowlist	Outbound calls to non-whitelisted hosts, raw IP addresses (C2-style)
4	Schema-Drift Guard (`schema_drift.rs`)	JSON Schema compiled from `ToolVersion.input_schema`	LLM-constructed payloads that miss required fields, type-mismatch, unknown fields
5	Behavioral-Drift Monitor (`behavioral_drift.rs`)	Per-agent rolling z-score over `cost_cents` / `latency_ms` / `refused` / `schema_violation`	Single-axis exploitation — calls that deviate >3σ from the agent's own recent baseline after a warmup window

Modes

shadow (default): violations are logged + persisted as threats, but the call is allowed through. Use for rollout and rule tuning.
enforce: violations block the call. Use in production once you've triaged the shadow-mode threat stream.

Configure via the gateway's AirlockConfig — each layer has independent enabled, thresholds, and risk-score defaults. See rust/crates/fd-policy/src/airlock/config.rs.

Coherence-Divergence Monitor — a trajectory-level signal

The five layers above each inspect a single tool call in isolation. The coherence-divergence monitor (rust/crates/fd-policy/src/airlock/coherence.rs) is different: it watches the agent run trajectory — the audit-trail event stream — for a sequential failure no per-call check can see. The agent states a fact that should change its plan ("tests still failing", "permission denied", "the file does not exist") and the very next advancing action proceeds as if that fact were untrue (marks the task done, commits, reports success). Each divergence is emitted as a structured CoherenceSpan carrying the stated-fact quote, the contradicting action, a confidence in [0, 1], and a severity — and CoherenceSpan::to_violation() projects it onto the same AirlockViolation shape (violation_type = coherence_divergence) as every other layer, so it lands in the identical audit_events.details path.

Motivation — Strained Coherence (arXiv:2606.07889): in that study, coding- agent trajectories exhibiting this divergence failed 94% of the time versus 46% for trajectories without it (Fisher's exact p = 0.003). That is a pre-failure signal worth surfacing before the run finishes, so the monitor is streaming: CoherenceMonitor::observe_event consumes one trajectory event at a time and returns a span the instant a divergence appears, rather than only in a post-hoc autopsy. A false-positive guard keeps it honest — a run that acknowledges and acts on the blocking fact (remediates, states it resolved, or disclaims success in the action itself) does not fire.

Status: wired live at the gateway run stream. submit_step_result projects each submitted step into trajectory events (a Tool step is an advancing action followed by its observed output; a reasoning step is a statement) and feeds them to a process-wide CoherenceMonitor keyed per run. A divergence surfaces mid-run through the same airlock.violation_detected audit_events path, is persisted on the run row (runs.coherence_divergence_flagged, surfaced on GET /v1/runs/{id} and the run console's Coherence card), and is emitted on the run-completion span (ferrumdeck.reliability.coherence_divergence). At completion a synthetic "reports success" closure action is fed so a run that terminates with an unresolved blocking fact (and does not disclaim it) also flags. It is a reliability signal — it never blocks a tool or changes run status, mirroring the claim-grounding "flag, never block" posture. Toggle with FERRUMDECK_COHERENCE_ENABLED=false. Configured by CoherenceConfig (separate from the per-call AirlockConfig, since it is driven by CoherenceMonitor rather than AirlockInspector::inspect). Single-process today: the per-run trajectory state lives in gateway memory, so a multi-instance deployment would track each run only within the instance that receives its steps. See docs/runbooks/coherence-divergence.md.

Exfiltration Shield — credential & data-budget detail

The data-exfiltration shield in rust/crates/fd-policy/src/airlock/exfiltration.rs runs in-process on every network-tool dispatch and layers three checks against the outbound payload:

Credential DLP (credential_dlp.rs) — scans for cloud keys (AWS access key id, GCP service-account JSON), PATs (GitHub, Slack bot tokens, Stripe live keys, Anthropic and OpenAI keys), and financial account numbers. False positives on PAN and IBAN are suppressed with Luhn (mod-10) and mod-97 checksum gates respectively, so a random 16-digit correlation id is not flagged as a credit card. Matches are recorded with a redacted form (first-4 + last-4 only) — the raw secret never reaches audit storage.
Domain allowlist + raw-IP block — deny-by-default, with subdomain matching and IP-literal rejection to prevent C2-style direct dialing.
Per-domain data budget — configurable data_budget_per_domain_bytes caps cumulative outbound bytes per (run, domain) tuple. Further dispatches that would exceed the budget are denied; the violation reuses the existing audit and shadow/enforce-mode plumbing, so an exceedance kills the run the same way a budget-exceeded policy decision does.

Threat Model

Assumption: Prompt injection cannot be fully prevented.

Strategy: Containment, not prevention.

Threat	Mitigation
Malicious tool calls	Deny-by-default allowlist
Token exhaustion	Budget limits with auto-kill
Data exfiltration (destination)	Domain allowlist + raw-IP block (Airlock RASP)
Credential exfiltration (payload)	Airlock credential DLP — cloud keys, PATs, Luhn-valid PANs, mod-97 IBANs (redacted in audit)
Slow-leak exfil to allowed host	Airlock per-domain data budget per run
Tool-call payload drift	Airlock schema-drift guard against the registered `ToolVersion` JSON Schema
Single-axis exploitation	Airlock behavioral-drift monitor — rolling z-score per agent
Privilege escalation	Scoped API keys, tenant isolation
Audit tampering	Append-only logging (app-layer + DB trigger), a per-tenant cryptographic hash-chain (`prev_hash`/`record_hash`/`chain_seq`) — insertions/deletions/edits within a chain are detectable via `AuditRepo::verify_chain` — and signed out-of-band head checkpoints (#14) that catch a wholesale self-consistent tail rewrite via `verify_against_checkpoints`, up to the last checkpoint. Residual: detection not prevention; the window after the last checkpoint keeps the in-chain guarantee, and the anchor needs an out-of-band sink + off-host key — see Project Status

Observability

OpenTelemetry Integration

FerrumDeck uses OpenTelemetry with GenAI semantic conventions:

Tracked Attributes:

gen_ai.system              = "anthropic" | "openai"
gen_ai.request.model       = "claude-sonnet-4-20250514"
gen_ai.usage.input_tokens  = 1234
gen_ai.usage.output_tokens = 5678
gen_ai.usage.cost_usd      = 0.0234

ferrumdeck.run.id          = "run_xxx"
ferrumdeck.step.id         = "stp_xxx"
ferrumdeck.agent.id        = "agt_xxx"
ferrumdeck.tenant.id       = "ten_xxx"

Receiver Attestation (optional, off by default)

FerrumDeck spans are agent-self-reported: the agent (or the worker on its behalf) describes what it did. That is useful, but a self-reported span is an assertion, not a proof — nothing independently confirms the call happened as described.

Receiver attestation is an optional cross-check. When enabled, a tool/ service call may carry a minimal, Sello-style receiver-signed receipt (receiver_id, tool_name, a per-call call_token binding, an owner-encrypted payload_ref, and a signature). The trace plane (fd_runtime.attestation) verifies that the receipt (a) has a valid receiver signature and (b) binds to the same call the span claims (same tool name + same call_token), then annotates the span:

ferrumdeck.attestation.attested                  = true | false
ferrumdeck.attestation.status                    = "attested"
                                                 | "unverified_no_receipt"
                                                 | "unverified_signature_invalid"
                                                 | "unverified_mismatch"
                                                 | "unverified_unknown_receiver"
ferrumdeck.attestation.self_reported_unverified  = true | false
ferrumdeck.attestation.receiver_id               = "github-mcp"
ferrumdeck.attestation.call_token                = "call_tok_xxx"

Enable it with the environment switch (off unless explicitly set):

export FD_ATTESTATION_ENABLED=true   # default: false (existing pipelines unaffected)

and supply a ReceiptVerifier (keyed per receiver) + the per-call receipt to trace_tool_call(...). When disabled, the verification path is skipped entirely and spans are byte-for-byte identical to before.

Trust model — what attestation DOES and does NOT prove. Be honest about this; it is deliberately narrow:

✅ Does prove that a party holding the receiver's key issued a receipt that binds to this specific call (same tool + same call_token), and that the receipt was not altered after signing.
✅ Does give you an honest, additive signal: a span without a verified receipt is flagged self_reported_unverified = true instead of being silently trusted.
❌ Does not prove the call's contents or results are correct — the payload_ref is owner-encrypted and the trace plane never decrypts it. Attestation proves binding, not semantics.
❌ Does not provide third-party non-repudiation with the default scheme. The default is HMAC-SHA256 (a symmetric, shared-secret signature): a valid signature proves the holder of the receiver key produced it, not that only the receiver could have. The ReceiptVerifier interface is scheme-agnostic so an asymmetric scheme (e.g. Ed25519) can replace HMAC later without changing callers.
❌ Does not enforce anything. Unattested spans are never dropped — most spans are unattested today. This is signal for the trace view, not a gate. There is no "attestation required" mode.

Jaeger UI

Access traces at http://localhost:16686:

Search by run ID, agent ID, or error status
View step execution timeline
Analyze token usage and costs
Debug failures with full context

Cost Tracking

Automatic cost calculation based on model pricing:

Model	Input ($/1M)	Output ($/1M)
claude-opus-4	$15.00	$75.00
claude-sonnet-4	$3.00	$15.00
gpt-4o	$2.50	$10.00
gpt-4o-mini	$0.15	$0.60

Example Agents

Safe PR Agent

A flagship example demonstrating FerrumDeck's governance features. Located in examples/safe-pr-agent/.

Agent Configuration (agent.yaml):

name: safe-pr-agent
description: |
  Reads a repository, analyzes code, proposes changes,
  runs tests in sandbox, and creates a pull request.
  Every action is permissioned, traced, and cost-accounted.

default_model: claude-sonnet-4-20250514

# Read-only tools allowed by default
allowed_tools:
  - read_file
  - list_files
  - search_code

# These require human approval
approval_required_tools:
  - write_file
  - create_pr

# Governance limits
budget:
  max_input_tokens: 50000
  max_output_tokens: 20000
  max_tool_calls: 30
  max_wall_time_ms: 180000  # 3 minutes
  max_cost_cents: 100       # $1

Create Your Own Agent:

# Copy the example
cp -r examples/safe-pr-agent examples/my-agent

# Edit the configuration
vim examples/my-agent/agent.yaml

# Register with the control plane
curl -X POST http://localhost:8080/v1/registry/agents \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d @examples/my-agent/agent.yaml

Evaluation Framework

Running Evaluations

# Run full evaluation suite
./scripts/run-evals.sh

# Run specific dataset
fd eval run \
  --dataset evals/datasets/safe-pr-agent.jsonl \
  --agent agt_safe_pr_agent \
  --output evals/reports/latest.json

# Compare against baseline
fd eval compare \
  --baseline evals/reports/baseline.json \
  --current evals/reports/latest.json

Evaluation Dataset Format

{"task_id": "pr-review-001", "input": {"task": "Review PR #1"}, "expected": {"files_changed": true}}
{"task_id": "pr-review-002", "input": {"task": "Review PR #2"}, "expected": {"files_changed": true}}

CI Integration

Evaluations run automatically on PRs to main:

# .github/workflows/evals.yml
- name: Run evaluations
  run: fd eval run --suite smoke --parallel 4

- name: Check for regressions
  run: |
    if [ $(jq '.pass_rate' report.json) -lt 80 ]; then
      echo "Eval gate FAILED: Pass rate below 80%"
      exit 1
    fi

Development

Prerequisites

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Docker
# See: https://docs.docker.com/get-docker/

Common Commands

# Start development infrastructure
make dev-up

# Stop infrastructure
make dev-down

# Install all dependencies
make install

# Build everything
make build

# Run all tests
make test

# Format code
make fmt

# Lint code
make lint

# Run full CI checks locally
make check

# Run database migrations
make db-migrate

# Start gateway
make run-gateway

# Start worker
make run-worker

Running Tests

# All tests
make test

# Rust tests
cargo test --workspace

# Python tests
uv run pytest python/packages/fd-evals/tests/ -v
uv run pytest python/packages/fd-worker/tests/ -v

# Specific package
cargo test -p fd-policy
uv run pytest python/packages/fd-runtime

# With coverage
cargo tarpaulin --out Html
uv run pytest --cov=fd_runtime --cov-report=html

# Next.js type checking
cd nextjs && npx tsc --noEmit

Code Quality

# All checks
make check

# Rust
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings

# Python
uv run ruff check python/
uv run ruff format --check python/
uv run pyright python/

# Next.js
cd nextjs && npm run lint

Deployment

Trust boundary

Read this before you expose any port. FerrumDeck's enforcement boundary is the gateway — it applies per-agent deny-by-default policy, budgets, and Airlock to every tool call. The dashboard BFF in front of it is not a second enforcement layer; it is a trusted-operator surface.

Trust boundary — the dashboard BFF performs no caller authentication. Every /api/v1/* route in nextjs/ proxies to the gateway with a single shared server key (FD_API_KEY, attached by getAuthHeaders() in nextjs/src/lib/api/config.ts) and does no inspection of the incoming caller — there is no nextjs/src/middleware.ts, and handlers such as app/api/v1/runs/route.ts attach the key unconditionally. So reaching the dashboard port is equivalent to holding FD_API_KEY, including authority to POST /v1/runs. ⚠ Do not expose the dashboard port outside a trusted network — keep it behind a VPN, private subnet, or authenticating reverse proxy — until per-caller authentication (dashboard session + SSO/RBAC + API-key self-service) lands (#10). This is a positioning limit stated plainly, not a bug: a deny-by-default control plane must say where its own boundary is.

Production Checklist

Docker Deployment

# Build all images
docker build -t ferrumdeck-gateway -f deploy/docker/Dockerfile.gateway .
docker build -t ferrumdeck-worker -f deploy/docker/Dockerfile.worker .
docker build -t ferrumdeck-dashboard nextjs/

# Run with Docker Compose (development)
docker compose --env-file .env -f deploy/docker/compose.dev.yaml up -d

# Services will be available at:
#   Gateway:   http://localhost:8080
#   Dashboard: http://localhost:3001
#   Jaeger:    http://localhost:16686

Kubernetes

A Helm chart ships at deploy/helm/ferrumdeck/. It packages the gateway, worker, Next.js dashboard, and (optionally) bundled Postgres (pgvector) and Redis. Kustomize manifests at deploy/k8s/ are retained for parity — use whichever fits your tooling.

# Pull bundled deps (Bitnami postgresql + redis)
helm dependency update deploy/helm/ferrumdeck

# Demo install with bundled Postgres + Redis
helm install ferrumdeck deploy/helm/ferrumdeck \
  --namespace ferrumdeck --create-namespace \
  --set secrets.data.anthropicApiKey=sk-ant-...

# Port-forward and verify
kubectl -n ferrumdeck port-forward svc/ferrumdeck-gateway 8080:8080
curl http://localhost:8080/health

For production, disable the bundled deps and point at managed Postgres (pgvector ≥ 0.7) and managed Redis (Streams support required); set secrets.create=false and reference an externally-managed Secret from External Secrets Operator or sealed-secrets. See deploy/helm/README.md for the full production checklist. CI runs helm lint + kubeconform on every change under deploy/helm/.

Minimum resources per service:

Gateway: 512MB RAM, 0.5 CPU
Worker: 1GB RAM, 1 CPU (scales horizontally)
Dashboard: 256MB RAM, 0.25 CPU

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (make check)
Commit (git commit -m 'Add amazing feature')
Push (git push origin feature/amazing-feature)
Open a Pull Request

Code Style

Rust: Follow rustfmt defaults, clippy warnings as errors
Python: Follow ruff rules (see pyproject.toml), pyright type checking
TypeScript: ESLint with Next.js config
Commits: Use conventional commits (feat:, fix:, docs:, etc.)

See AGENTS.md for detailed coding guidelines and single-test commands.

License

Apache-2.0 — see LICENSE for details.

Acknowledgments

Rust Control Plane:

Axum — Web framework
SQLx — Async SQL with compile-time checks
Tower — Middleware framework
Tokio — Async runtime

Python Data Plane:

litellm — Unified LLM interface
MCP — Model Context Protocol
Pydantic — Data validation
Tenacity — Retry with backoff

Dashboard:

Next.js — React framework
Tailwind CSS — Utility-first CSS
shadcn/ui — Component library
TanStack Query — Server state management
Radix UI — Accessible primitives
Recharts — Chart library

Observability:

OpenTelemetry — Tracing framework
Jaeger — Distributed tracing UI

Name		Name	Last commit message	Last commit date
.claude/auto-memory		.claude/auto-memory
.github		.github
config		config
contracts		contracts
db/migrations		db/migrations
deploy		deploy
docs		docs
evals		evals
examples		examples
nextjs		nextjs
observability		observability
python		python
rust		rust
scripts		scripts
src/ferrumdeck		src/ferrumdeck
tests		tests
.agent-audit-kit.yml		.agent-audit-kit.yml
.editorconfig		.editorconfig
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.live-stack-known-failures.yml		.live-stack-known-failures.yml
.route-backing.yml		.route-backing.yml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.toml		Cargo.toml
LICENSE		LICENSE
Makefile		Makefile
QUICKSTART.md		QUICKSTART.md
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
mkdocs.yml		mkdocs.yml
pyproject.toml		pyproject.toml
rust-toolchain.toml		rust-toolchain.toml
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation

FerrumDeck

Reproduce every number on this page

Install from crates.io

What this proves

Reproduced: indirect-prompt-injection defense-path coverage

Second axis: Agent Security Bench (ASB) + an EU AI Act Art. 50 transparency rule

Live-fire: a drifting run is caught and R-tiered (deterministic, no stack)

Mapping to the DeepMind AI Control Roadmap (D1–D4 / R1–R3)

Table of Contents

Overview

The Problem

The Solution

Project Status & Limitations

The CRA clock

Key Features

Governance

Observability

Reproducibility

Quality

Architecture

Data Flow

Service Ports

Receipts schema

Quick Start

Prerequisites

1. Clone and Setup

2. Start Services

3. Create Your First Run

4. Open the Dashboard

5. View Traces

Project Structure

Components

Control Plane (Rust)

fd-core — Foundation Primitives

fd-policy — Policy Engine

fd-registry — Versioned Registry

fd-storage — Database & Queue

fd-audit — Audit Trail

Gateway Service

Data Plane (Python)

fd-runtime — Runtime Primitives

fd-worker — Step Executor

fd-mcp-router — Tool Router

fd-cli — Command Line Interface

fd-evals — Evaluation Framework

fd-mcp-tools — MCP Server Implementations

Dashboard (Next.js)

Key Pages

Technology Stack

Running the Dashboard

Environment Variables

API Proxy (BFF Pattern)

API Reference

Authentication

Endpoints

Runs

Registry

Approvals

Policies

API Keys

Workflows

Health & Documentation

Example: Create a Run

Configuration

Environment Variables

MCP Server Configuration

Security Model

Defense in Depth

Airlock RASP

Coherence-Divergence Monitor — a trajectory-level signal

Exfiltration Shield — credential & data-budget detail

Threat Model

Observability

OpenTelemetry Integration

Receiver Attestation (optional, off by default)

Jaeger UI