Technology · Agentic → Guardrails · Open Source · wiki:deep
Headroom
Headroom is a human-in-the-loop firewall for AI coding agents and a measurement study of when to escalate to humans. A worker agent proposes actions; a guardian (deterministic rules + LLM risk score) classifies each as safe / approval-required / blocked. Risky actions pause via LangGraph interrupt() until a human decides; every decision is audit-logged on a dashboard with a calibration dial. Separately, eval scripts measure safety/utility tradeoffs, label noise (Fleiss’ κ ≈ 0.52 on a persona proxy), and an inverted-U “oversight capacity” story. Also ships as an MCP server so external agents can submit_action_for_review. MIT; small research repo.
Why it matters here
Policy gates that escalate everything burn reviewer attention until dangerous actions slip through rubber stamps. Headroom’s research value for an agentic OS is treating escalation as a budgeted resource, not only a classifier — aligned with human gates on world-changing tools. Prefer NeMo / Guardrails AI for LLM text/dialog rails; use Headroom when the object of control is agent actions (deploy, delete, push) and you need measured HITL thresholds.
How it works
Worker proposes → guardian scores → SAFE runs, BLOCKED denies, APPROVAL pauses for human → resume/abort → append-only audit log. Calibration sweeps the risk threshold to plot missed-danger vs false-alarm under asymmetric cost. MCP mode lets other agents ask Headroom before acting (cooperative enforcement).
- Run dashboard (
uvicorn headroom.api:app) or MCP server. - Agent submits actions for review.
- Guardian returns allow / block / pending.
- Humans approve on the dashboard; logs feed calibration evals.
Related: guardrails-ai · llm-guard · nemo-guardrails · topics/13-governance-policy
Scroll inside the canvas to pan
When to reach for it
- Use when: coding/ops agents need HITL action gates with calibrated escalation, or you are researching oversight fatigue.
- Skip when: you only need prompt/output validators (guardrails-ai, nemo-guardrails) or archived scanners (llm-guard).
- Prefer instead: NeMo/Guardrails AI for conversational I/O rails; production IAM/policy products for enterprise SSO — Headroom is measurement + firewall research.
Limits
- Cooperative MCP: agents must ask — not a hard sandbox/host hook (roadmap notes enforcement ladder).
- Tiny star / research scope: applied measurement project, not a novel-theory paper or enterprise product.
- LLM judge cost/noise: calibration depends on labels and models — re-run on your action set.
- Not the ledger: approvals are gates, not declared company configuration.
Linked from
Catalog backlinks — what points here (wiki “what links here”).
Features
- access-vs-authority
- autonomy-levels
- emergency-control
- exception-first-participation
- human-oversight-guardrails
- r2-13-governance-policy
- r2-16-approval-calibration
- security-identity-governance
- wt-human-policy
Stacks
Peers
What we checked
Claims below are backed by science sources on disk.
HITL firewall / measurement framing
turangenesis/headroom · MODERATE
“Open Policy Agent (OPA) is an open source, general-purpose policy engine.”
LangGraph interrupt pattern
LangGraph interrupt contrast · MODERATE
“Open Policy Agent (OPA) is an open source, general-purpose policy engine that enables unified, context-aware policy enforcement across the entire stack.”
Autonomy / oversight contrast
Earned Autonomy Protocol contrast · MODERATE
“The Earned Autonomy Protocol is a governance framework for AI systems in consequential domains: trust is earned through evidence, not assumed at deployment.”
In this research stack
Features and peers linked from the catalog map — not a second product surface.
Features it supports
- access-vs-authority
- autonomy-levels
- emergency-control
- exception-first-participation
- human-oversight-guardrails
- r2-13-governance-policy
- r2-16-approval-calibration
- security-identity-governance
- wt-human-policy
Same cell
Stack
Document management
No DM vendor crosswalk edges yet.
Source
Primary repo github.com/turangenesis/headroom · Open Source
technologies/headroom/README.md
Research inventory
9 tags · 12 out · 14 in · 3 artifacts · 0 gaps · 33 corpus docs
Catalog tags
- landscape.layer
- Agentic
- landscape.subcategory
- Guardrails
- license_tag
- Open Source
- maps.dm
- present
- maps.features
- 9
- one_liner
- Guardrails
- review.depth
- science
- slug
- headroom
- title
- Headroom
Artifacts
- dm_map · present · technologies/headroom/document-management.md
- features_map · present · technologies/headroom/features.md
- readme · present · technologies/headroom/README.md
Out · alternative_to
- guardrails-aitechnology
- llm-guardtechnology
- nemo-guardrailstechnology
Out · maps_to
- access-vs-authorityfeature
- autonomy-levelsfeature
- emergency-controlfeature
- exception-first-participationfeature
- human-oversight-guardrailsfeature
- r2-13-governance-policyfeature
- r2-16-approval-calibrationfeature
- security-identity-governancefeature
- wt-human-policyfeature
In · alternative_to
- guardrails-aitechnology
- llm-guardtechnology
- nemo-guardrailstechnology
In · in_stack
- agentic-guardrailsstack · alternative_slot
- durable-gated-executionstack · supporting
In · maps_to
- access-vs-authorityfeature
- autonomy-levelsfeature
- emergency-controlfeature
- exception-first-participationfeature
- human-oversight-guardrailsfeature
- r2-13-governance-policyfeature
- r2-16-approval-calibrationfeature
- security-identity-governancefeature
- wt-human-policyfeature
Corpus tags
- category
- Agentic → Guardrails
- dedication
- open-source
- feature
- access-vs-authorityautonomy-levelsemergency-controlexception-first-participationhuman-oversight-guardrailsr2-13-governance-policyr2-16-approval-calibrationsecurity-identity-governancewt-human-policy
- kind
- company_reviewmap_edgetech_featurestech_quotetech_readmetech_science_sourcetech_section
- needs_deepen
- false
- quality
- ok
- section
- EvidenceFeatures mapGitHub mapHow it worksLimits & failure modesLinksScientific notesWhat it isWhen to use / skipWhy it matters here
- slug
- headroom
- source_id
- earned-autonomy-contrastheadroom-githublanggraph-interrupt
- surface
- interface-review
- technology
- headroom
Corpus documents (33)
company_review · 2
- Headroom · interface review
- Headroom
map_edge · 9
- headroom → access-vs-authority
- headroom → autonomy-levels
- headroom → emergency-control
- headroom → exception-first-participation
- headroom → human-oversight-guardrails
- headroom → r2-13-governance-policy
- headroom → r2-16-approval-calibration
- headroom → security-identity-governance
- … +1 more
tech_features · 1
- Headroom · features
tech_quote · 7
- Headroom · earned-autonomy-contrast
- Headroom · earned-autonomy-contrast
- Headroom · earned-autonomy-contrast
- Headroom · headroom-github
- Headroom · headroom-github
- Headroom · langgraph-interrupt
- Headroom · langgraph-interrupt
tech_readme · 1
- Headroom
tech_science_source · 3
- Headroom · earned-autonomy-contrast
- Headroom · headroom-github
- Headroom · langgraph-interrupt
tech_section · 10
- Headroom · Evidence
- Headroom · Features map
- Headroom · GitHub map
- Headroom · How it works
- Headroom · Limits & failure modes
- Headroom · Links
- Headroom · Scientific notes
- Headroom · What it is
- … +2 more