Deadbolt

A permission engine for AI-operated systems.

Deadbolt is a local-first Rust research project for controlling the point where an AI suggestion becomes a real machine action.

The basic rule is simple.

The model may suggest. Authority stays outside the model.

Deadbolt does not give a model a shell and then try to make the shell safe. It defines individual operations as typed routes. Each route decides what request it accepts, which policy applies, what permission is required, whether a human must confirm it, what gets recorded, how the result is checked, and how it can be undone.

An agent can still do useful work. It just does not inherit permission to do everything else at the same time.

Why Deadbolt exists

Models are getting much better at deciding what a computer should do.

That is a different problem from deciding whether they should be allowed to do it.

Deadbolt keeps those two decisions separate.

AI / operator request
        |
        v
 untrusted proposal
        |
        v
    typed route
        |
        v
 policy + exact lease + confirmation
        |
        v
   bounded adapter
        |
        v
 receipt + rollback + verification

The proposal may come from a local model, a remote model, an operator, or MCP. Deadbolt treats it as a proposal either way.

The model does not grant itself permission to execute it.

That separation is the point of the project.

What works today

Deadbolt is a research prototype. It also has real end-to-end code behind the design.

The live mutation code is intentionally tiny.

Hyprland mutations

Two real Hyprland changes are currently implemented:

• decoration:rounding -> 0
• general:border_size -> 3

For either route, Deadbolt reads and records the existing value before changing anything. It validates the typed request, checks local policy, verifies the exact signed lease, asks for explicit confirmation, records what happened, and keeps enough information to roll the change back.

The mutations themselves are almost comically boring. That is useful. Changing a border width gives us somewhere concrete to work on permission and recovery without pretending we have solved arbitrary computer control.

The retro cockpit demo walks through the rounding route:

demo retro-cockpit --real-hyprland

See the Hyprland cockpit walkthrough for the complete opt-in sequence.

Read-only style planning

Deadbolt can also preview, compile, and snapshot a constrained desktop style request without granting permission to apply it.

For example:

cargo run -p cog-cli -- style-plan preview \
  --input examples/style-plans/haunted-win95.json

A valid plan is still only a plan. Producing one does not give the caller permission to execute it.

MCP for review

mcp serve runs a local stdio MCP server with these tools:

• deadbolt_status
• deadbolt_capability_registry
• deadbolt_cockpit_summary

They are read-only.

An agent can inspect Deadbolt through MCP. It cannot turn that access into execution permission.

Receipts and verification

Deadbolt records evidence for fixtures, dry runs, observations, leases, transactions, and reviewed local adapter operations.

There are deterministic verifiers for several of those records.

A verifier can tell you whether an artifact satisfies the rules it knows how to check. It cannot prove that consent happened, that a host action occurred as reported, or that the wider system is trustworthy. A valid receipt, lease, report, or verifier result does not grant execution permission merely by existing.

The exact list of implemented pieces lives in Implementation status.

The rules Deadbolt tries to enforce

A model output is data. So is provider output, MCP output, a planner result, a registry entry, or a generated report. None of those things grants permission by itself.

Capabilities should be narrow. If the requested operation is "set Hyprland border size to 3", the permission should describe that operation. It should not quietly mean "run any command you like".

A lease is checked against the request that will use it. Deadbolt does not treat a signed permission as a general credential that happens to be nearby.

Real mutation routes currently stop for explicit local confirmation before commit.

Rollback belongs in the design of the operation. Deadbolt does not wait until after a successful apply to wonder how to undo it.

Deadbolt records decisions and results because inspectability matters. Receipts and verifier output make it possible to reconstruct what the system believed it was doing. They do not turn internal consistency into proof of facts outside the system.

What Deadbolt does not do

Deadbolt is not a general desktop automation framework.

It is not an agent shell.

It is not a production trust system.

It is not evidence that arbitrary computer use has been made safe.

There is currently no general hyprctl mutation interface, arbitrary shell runner, Home Manager or Nix apply route, provider or cloud execution permission, or raw model-visible context pipeline.

Those omissions are deliberate.

The exact current trust and permission claims are documented in Current authority boundary. That document is stricter than this README and should win if the two ever appear to disagree.

Quick start

Most Deadbolt development does not require a model, a running Hyprland session, or permission to modify the desktop.

git clone https://github.com/noctem-o/deadbolt.git
cd deadbolt
cargo build --locked
cargo test -p cog-kernel
cargo test -p cog-cli
cargo clippy --locked --all-targets -- -D warnings

To inspect the CLI:

cargo run -p cog-cli -- --help

Real Hyprland mutation is opt-in. It needs local configuration, a valid lease, confirmation, and a working rollback path.

Use the demo walkthrough rather than treating the examples above as a generic way to execute commands.

Repository layout

Deadbolt is split across several Rust crates.

• cog-leases handles signed capability leases and authorization checks.
• cog-kernel contains synthetic kernel decision and replay code. It is not on the two current live mutation paths.
• cog-guardrails checks typed proposals.
• cog-evidence and cog-canonical define evidence records and deterministic canonicalization.
• cog-transactions records transactions, snapshots, rollback data, and dry runs.
• cog-hyprland contains the narrow Hyprland-specific code.
• cog-cli connects the local pieces and exposes the command-line interface.
• sensorium-* contains context-reduction and replay support code.

For the full data flow and trust boundaries, read Architecture.

Read next

• Implementation status lists what actually exists today.
• Current authority boundary defines what Deadbolt currently does and does not claim.
• Hyprland cockpit walkthrough runs through the live demo.
• MCP stdio docs documents the read-only MCP interface.
• Architecture describes the system boundaries and evidence flow.
• Reviewer quickstart is the shortest route into reviewing the code.
• Security policy
• Contribution guide

Status

Deadbolt is experimental software under active development.

It starts locked. Its real execution permissions are deliberately small. Broad agent execution is not currently part of the project.

I would rather make two boring operations difficult to misuse than expose fifty impressive ones whose authority nobody can explain.

Deadbolt is licensed under Apache-2.0.