umbra
docs
Name every command, then prove it.
umbra sits between semi-trusted automation and the host system. What you did not declare does not get through. Policy lives in a KDL guardfile rather than in code, enforced across two surfaces: subprocess execution and outbound HTTP.
If you are still deciding whether any of that is your problem, the case for umbra is the better place to start. These pages assume you already decided.
Synced from umbra cf90518, 2026-09-24. A copy, so the repository is the source of truth if the two disagree.
Getting started
Guides
Reference
- Policy Auth, deny, restrict, tiering.
- Op resolution Verbs, wildcards, unrecognised shapes.
- Request semantics How a mounted leaf assembles and fires.
- Complex actions Composite verbs and their five invariants.
- Describe model Generated visibility for a generated surface.
- Descriptors The spec-driven source without a CLI tree.
- Inline operations Descriptors stated directly in KDL.
- Body projection `map`, `set`, and pinned values.
- MCP Apps host The frames a rendered widget sends back, under the guardfile.
- Serving the granted surface The same grants projected into what a server advertises.
- Value providers `env`, `file`, `literal`, and minted tokens.
- Audit spans projecting audit records onto tracing spans, and why a
- default-allow Every other shape in the exec dialect is closed: a verb the
- Upstream guardfiles `mcp-upstream`, the proxied-server shape
- Emitting OpenAPI rendering the granted subset as a spec other tools can read
- Action limits what an action deliberately cannot express, and what to reach
- YAML and TOML guardfiles the same guardfiles in two other syntaxes, lowered to KDL
- Keyed maps and discriminated unions `keyed`, `entry`, and `variant` for a body shape a fixed
- Declaring a grant's response shape `returns`, enforced by pruning what a successful call hands
- Corpora A corpus is the demo harness pointed at measurement instead
- Negative controls umbra controls checks that every refusal a guardfile states
Concepts
- Architecture The two guarded surfaces and the shared core.
- Spec-driven verbs The three-layer engine behind the HTTP surface.
- Exec-dialect verbs The same grammar aimed at wrapped binaries.
- MCP-dialect verbs The same grammar aimed at upstream MCP servers.
- What an MCP call costs Measured per-call latency, and the daemon it did not warrant.
- Occlusion primitives `withhold`, `pin`, and `resolve-flag` in the exec dialect
- Occluded replacement binaries `replace`, and the generated binary installed under the
Contributing