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.
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, …).
- Approvals live outside the agent's harness.
lox runis 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.
brew trust davidgodefroid/tap
brew install davidgodefroid/tap/loxOr everything at once (lea, lox and the Locks' launchers):
brew trust davidgodefroid/tap
brew install davidgodefroid/tap/lockfamilyHomebrew asks you to trust a third-party tap once before it loads its formulas. Other ways:
- the Lock Family install.sh
installs the static
loxarchives (cosign-signedchecksums.txt) into~/.local/bin; - the hub ships as the cosign-signed image
ghcr.io/davidgodefroid/lockhub, pinned by digest (lox runstarts it for you).
Details: docs/getting-started.md.
-
In your project (or lea's projects directory), check the prerequisites and write a
lockfamily.yamlwith the hub alone:lox init
-
Add one data source, guided and applied at once:
lox add locksql # or lockmq, lockfile, lockhttp, locklog, lockssh -
Keep
lox runopen in a terminal of its own: it serves the decisions.lox run
-
Start your agent in the project, or
lea.lox addwrites 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, thenlea).
Where to run each command, with or without lea: docs/getting-started.md.
|
🧭 Outside the harness |
⚡ Auto mode by default |
|
✍️ Signed, bound decisions |
🙈 Never in clear |
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 rundecides 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 doctorchecks it. A database in a dev stack is reached by container name withnetworks: [shop]on the lock: only a part of its gateway joinsshop, 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.
| 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.
- 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.yamlcan narrow this routing, never widen it. - Quitting
lox runstops its decisions, not the stack: pending tickets wait at the hub untillox runor 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_devicereserves 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.
| 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 |
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: issues and pull requests are welcome. The ticket and decision formats live in lockkit (
ticketpackage), 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'sdocs-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.