Skip to content
DavidGodefroidPublic

About

Harness security for AI agents: the Lock Family's approval hub and its lox CLI. lox run approves outside the agent's harness, signs decisions, never sees values in clear.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

lockhub: one hub approves for every Lock.

CI Latest release License: Apache 2.0 Go version

One hub approves for every Lock: lox run decides outside your
AI agent's harness, signs every decision, and never sees a value in clear.

lox run: a connection asked once, reads approved on their own, a production write asked

Quick start · How it works · Docs · Lock Family


lockhub is the approval hub of the Lock Family, harness security for AI agents. Each Lock sends it a masked ticket; lox run decides it, and the hub signs the decision.

The Lock executes only on a signed decision bound to the exact plan that was approved. The hub never runs a request, never sees its results, and never sees values in clear.

Note

Early development. This repository holds the hub server (lockhub serve) and the host CLI lox (lox init, lox add, lox run, lox approve, lox audit, …).

Why lockhub

  • Approvals live outside the agent's harness. lox run is the one terminal you keep open, outside lea and any agent: an agent's own tool is never where its approvals are shown or answered.
  • One place for every Lock. locksql, lockmq, lockfile, lockhttp, locklog and lockssh all send their tickets to the same hub.
  • Reads flow, risky actions wait. Auto mode approves reads by rule and asks you for writes, connections, dangerous actions and policy loosening.
  • Every decision is signed and audited, without a value in clear.

Install

brew trust davidgodefroid/tap
brew install davidgodefroid/tap/lox

Or everything at once (lea, lox and the Locks' launchers):

brew trust davidgodefroid/tap
brew install davidgodefroid/tap/lockfamily

Homebrew asks you to trust a third-party tap once before it loads its formulas. Other ways:

  • the Lock Family install.sh installs the static lox archives (cosign-signed checksums.txt) into ~/.local/bin;
  • the hub ships as the cosign-signed image ghcr.io/davidgodefroid/lockhub, pinned by digest (lox run starts it for you).

Details: docs/getting-started.md.

Quick start

  1. In your project (or lea's projects directory), check the prerequisites and write a lockfamily.yaml with the hub alone:

    lox init
  2. Add one data source, guided and applied at once:

    lox add locksql      # or lockmq, lockfile, lockhttp, locklog, lockssh
  3. Keep lox run open in a terminal of its own: it serves the decisions.

    lox run
  4. Start your agent in the project, or lea. lox add writes the MCP configuration for Claude Code only (<lock> init claude); wire another agent to the locks' launchers yourself. A lock added while lea runs reaches it at lea's next start (lea stop, then lea).

Where to run each command, with or without lea: docs/getting-started.md.

Highlights

🧭 Outside the harness
lox run starts (or reuses) the hub and the workspace's locks, then shows every ticket live: agent, lock, profile, masked request, decision, result.

⚡ Auto mode by default
Reads pass by rule; writes, DDL, dangerous actions, grants and policy loosening are asked. A connection is asked once per profile per session. Shift+Tab switches to manual.

✍️ Signed, bound decisions
The lock signs its ticket, the hub signs the decision. lox audit lists every exchange with both signatures; lox audit verify checks the whole chain.

🙈 Never in clear
Masked screens everywhere. A reveal is sealed to your terminal (the hub relays ciphertext); a paired phone signs its own decisions (WebAuthn).

How it works

agent → lock (socket) → hub (masked ticket) → lox run → hub (signed decision) → lock → agent
  • A Lock no longer needs a human at its own terminal: it sends the hub an approval ticket, a masked screen of the request.
  • lox run decides it: by its auto-mode rules, or by you in its terminal. lox approve, the lea deck, Slack, Telegram or a paired phone can answer too.
  • The hub signs the decision, and the Lock checks the signature before it runs anything.
  • Each lock (but lockhttp, whose egress is its own policy) reaches only the endpoints of its reviewed profile; lox doctor checks it. A database in a dev stack is reached by container name with networks: [shop] on the lock: only a part of its gateway joins shop, for the profile's dotless host names (db); the console never does (docs/lox-run.md).

The auto-mode rules, the keys of lox run, grants, production tickets and reveals: docs/approvals.md.

Supported locks

Lock Source lox add Since
locksql PostgreSQL, MySQL, MariaDB, SQLite lox add locksql v0.11.0
lockmq RabbitMQ lox add lockmq v0.3.0
lockfile S3, SFTP, a local directory lox add lockfile v0.4.0
lockhttp HTTP, through lea's gate lox add lockhttp v0.3.0
locklog this host's log files, journal and containers; Loki, Elasticsearch, OpenSearch lox add locklog v0.2.0
lockssh a server over SSH: allow-listed commands, others on a ticket lox add lockssh v0.1.0

"Since" is each lock's first release that runs under lox run (hub mode); lox run upgrades a pinned image older than the release this lox ships with, over a stack an earlier lox left up (it stops it first when its networks changed, volumes and keys kept); nothing restarts the stack by itself, even at boot, and lox down stops it (docs/lox-run.md). locklog's mount plan: docs/lox-run.md; lockssh's egress, home files and auto rules: docs/lox-run.md.

Safety model

  • The hub never runs a request, never sees its results, and never sees values in clear.
  • A Lock executes only on a decision signed by the hub key it pinned, bound to the exact plan that was approved.
  • Chat facades (Slack, Telegram) show masked screens only and answer only non-production reads and writes; a lockfamily.yaml can narrow this routing, never widen it.
  • Quitting lox run stops its decisions, not the stack: pending tickets wait at the hub until lox run or another facade (lox approve, a phone, a chat) answers; nothing is auto-approved.
  • Whoever can open the facade socket counts as the host's human: any process of your host account, never an agent container. A host agent running as you can therefore approve tickets (except the risk classes hub.mobile.require_device reserves to a phone): run agents in lea to keep them off it.

Details and limits: docs/approvals.md, docs/mobile.md, docs/design-notes.md.

Documentation

Doc What it covers
docs/getting-started.md First run with or without lea, where to run each command, what a release ships
docs/approvals.md Tickets and facades, grants, production tickets, reveals, lox run's auto mode and keys, lox audit
docs/lox-init.md lox init: flags, steps, re-running, secrets
docs/lox-add.md lox add: the questions per lock, rollback, non-interactive use, Vault, removing a lock
docs/lox-run.md The contract between lox run and lea: files, up.json, host agents, egress, upgrades, key rotation
docs/mobile.md Approving from a phone: pairing, exposure, routing, limits, notifications
docs/design-notes.md Where the code deliberately departs from the hub's design plan
CHANGELOG.md Release notes

The Lock Family

Every Lock is built on the same console, separation and approval model, and one hub approves for all of them. Start at lockfamily.dev.

Repo What it does
lockfamily The family site and install.sh: everything in one install
locksql SQL databases: the agent queries, PII comes back masked; connections and writes wait for you
lockmq RabbitMQ: masked queue inspection; connections, peeks and unmasked reads wait for you
lockfile Files (S3, SFTP, disk): the agent asks yes/no questions about files it never reads
lockhttp Outbound HTTP(S): reads of trusted hosts pass; anything that sends data or reaches an unknown host waits for you
locklog Logs: masked, bounded log search; the agent reads the logs, not the people in them
lockssh Commands over SSH: allow-listed commands run at once, the rest waits for you; the SSH key never leaves the console
lockhub The approval hub and its lox CLI: lox run approves outside the agent's harness
lockkit The shared Go core of every Lock: console, policies, masking, signed tickets, audit, MCP wiring
lea Runs many agents in containers, wired to the Locks

Contributing · Security · License

  • Contributing: issues and pull requests are welcome. The ticket and decision formats live in lockkit (ticket package), shared with every Lock. Build and test:

    go test ./...
    docker build -t lockhub .
    docker run --rm --read-only --cap-drop ALL lockhub version

    Docs are published at lockfamily.dev/docs from this repo's Markdown. Adding a file under docs/, or renaming or removing a README H2 section, needs a matching change to lockfamily's docs-site/nav.toml: open a lockfamily PR, or the nightly docs build fails.

  • Security: report vulnerabilities privately through GitHub security advisories.

  • License: Apache-2.0, see LICENSE.

About

Harness security for AI agents: the Lock Family's approval hub and its lox CLI. lox run approves outside the agent's harness, signs decisions, never sees values in clear.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages