Scoped, Auditable, Reversible.
Tiếng Việt · Docs · Quickstart · Cheat Sheet · Operator Guide · Security Model
FerrumGate is a governance gateway for AI agents that replaces ambient tool access with intent-scoped, single-use capabilities — so every action is policy-checked, rollback-prepared, and provenance-recorded.
Traditional API keys answer “who can call this?” but not “what was the agent trying to do?”, “was this in scope?”, or “can we roll it back?”.
FerrumGate sits between the agent and the tool, turning every side effect into a controlled lifecycle: compile intent, evaluate policy, mint a scoped capability, prepare rollback, execute, verify, and record provenance. Agents do not receive direct, ambient authority over production systems. They receive narrow, short-lived, explainable permission to perform a specific action, with rollback and lineage built in before the side effect happens.
Scoped — No ambient authority. Every capability is bound to a declared intent, specific resources, and a TTL ≤ 300 s. Once used or expired, the lease is gone.
Auditable — Policy decisions, capability grants, execution attempts, and terminal states are recorded as a chain of provenance. Evidence is append-only by design.
Reversible — Rollback and recovery contracts are prepared before any adapter performs a side effect. If verification fails, the system can compensate or roll back instead of leaving a partial mutation.
Prerequisites: Rust stable, cargo, make, curl.
# Build and run the development gateway
FERRUMD_BIND_ADDR=127.0.0.1:18080 \
cargo run -p ferrumd -- --config configs/ferrumgate.dev.toml
# Check liveness
curl http://127.0.0.1:18080/v1/healthz
# Full walkthrough in 10 minutes
cat docs/guides/quickstart.mdNote:
cargo runis debug mode — fine for local work. For production-like deployments, usecargo build --releaseand run./target/release/ferrumdwith a production config and bearer auth.
Every mutating action follows a minimum lineage chain: Intent → PolicyEvaluated → CapabilityMinted → ActionProposalSubmitted → SideEffectPrepared → ToolCallPrepared → ToolCallExecuted → SideEffectVerified → Terminal state (committed, compensated, rolled back, or failed). Store-backed transitions, fencing tokens, and lineage gates enforce the order. Unknown mutating tools fail closed unless explicitly bound.
FerrumGate provides bounded adapters for common agent side effects, each with sandboxing, allowlists, and rollback contracts:
- Filesystem — write, delete, move, copy, append, chmod, directory create/delete with sandboxing and snapshots.
- Git — commit, branch create/delete, tag create/delete with repository-root allowlists.
- HTTP — mutation with rustls-backed client, no redirects, bounded timeout, SSRF guard, and replay recovery contract.
- SQLite — file-backed mutation with database-root allowlist and verification gates.
- Mail draft — draft create/update/delete with recipient and content binding. Does not send email.
Entrypoints and tooling:
ferrumd— gateway daemonferrumctl— CLI for health, readiness, audit, policy, approvals, lifecycle outbox, backup/restoreferrum-mcp-server— MCP stdio server (exposes gateway tools to MCP clients)ferrum-migrate— SQLite-to-PostgreSQL migrationferrum-stress— machine-readable stress/smoke scenariosferrum-tui— terminal operator dashboard
- Stable — intent lifecycle, policy evaluation, capability minting, rollback prepare/verify/compensate, SQLite write queue, provenance chain, bearer/scoped/OIDC/agent auth.
- Implemented — filesystem, HTTP, Git, SQLite, mail draft adapters;
ferrumctlCLI;ferrum-stress;ferrum-tui; Prometheus metrics; rate limiting; Helm chart. - Beta — PostgreSQL runtime (local and CI live-tested). Production HA/multi-node topology is operator-managed, not provided by this repo.
- Experimental — MCP Streamable HTTP / SSE transport and resumability.
- Not implemented / out of scope — multi-tenancy, managed service, email sending, compliance certification.
Honesty note: FerrumGate is not a turnkey HA product or compliance certification. Operators still own deployment topology, TLS, secrets, backups, database HA, and production acceptance testing.
If you are new to the project, read in this order:
Other references:
- API Guide · MCP Integration · Demo Flows
- Policy Authoring · Troubleshooting
- FAQ · Roadmap
- Helm Chart · Monitoring Config
make fmt # formatting
make check # cargo check
make lint # clippy
make test # tests
make docs # link validation
make validate # expanded gate
make audit # dependency audit
make secret-scanSee CONTRIBUTING.md for conventions. If you are an AI assistant, see AGENTS.md for workspace constraints and tooling.