FerrumDeck Documentation¶

Welcome to the FerrumDeck documentation. FerrumDeck is a deterministic, in-path enforcement plane for AI agents — deny-by-default tool policy, per-run budget enforcement, Airlock RASP, and a hash-chained audit trail, all in the request path. It is early / alpha, built primarily by one maintainer; read the project status & limitations before you rely on it.

Getting Started¶

Quick Start - Get up and running in minutes
Architecture Overview - Understand the system design
Local Development - Set up your development environment

Core Concepts¶

Control Plane (Rust)¶

The control plane is the source of truth for all governance, orchestration, and audit operations:

Gateway API: HTTP endpoints for run management, registry access
Policy Engine: Enforces tool allowlists, budgets, approval gates
Registry: Stores versioned agents, tools, and prompts
Audit Log: Immutable event trail for compliance

Data Plane (Python)¶

The data plane executes agent steps with full observability:

Workers: Queue consumers that execute steps
LLM Executor: Unified LLM interface via litellm
MCP Router: Deny-by-default tool execution
Sandbox: Isolated code execution (future)

It is install-from-source only — not on PyPI, deliberately. See The Python data plane for what it is, why it is not published, and what to build against instead.

Key Abstractions¶

Concept	Description
Run	A single execution of an agent workflow
Step	One unit of work (LLM call, tool invocation, etc.)
Agent	A configured persona with allowed tools and prompts
Tool	An external capability (via MCP or custom)
Policy	Rules governing what actions are allowed

Architecture¶

Clients → Gateway → Policy Engine → Run Orchestrator
                                          │
                                    Redis Queue
                                          │
                                    Python Worker
                                          │
                              ┌───────────┼───────────┐
                              │           │           │
                           LLM Call   Tool Call   Sandbox

Security Model¶

FerrumDeck is designed with the assumption that prompt injection cannot be fully prevented. Instead, we focus on containment:

Deny-by-default tools: Only explicitly allowed tools can be called
Budget enforcement: Runs are killed when limits are exceeded
Approval gates: Sensitive actions require human approval
Audit trail: Every action is logged immutably

See Threat Model for details.

API Reference¶

Development¶

Measurement reports¶

Point-in-time data reports, generated from committed evidence:

Coherence monitor false-positive rate, by provenance (2026-09)

Ongoing measurement records live in eval health and the append-only series.