Let any AI agent ask yes/no questions about a file it must never read:
signed, sandboxed plugins answer, and the agent only ever gets 1s and 0s.
Quick start · How it works · Docs · Lock Family · Website
lockfile is a Lock of the Lock Family, harness security for AI agents. A console sits between your agent and the files in S3, on SFTP or in a local directory: it fetches the file, runs signed, sandboxed plugins on it, and returns only each plugin's answer. The agent only asks.
Note
Pre-release (v0.10.x): a release may still change the config files,
the MCP tools or the CLI. The console is Linux only: the plugin sandbox needs Landlock
and seccomp. install.sh also installs the launcher on macOS, where only the agent side
runs; the Homebrew formula is Linux only.
- The agent never reads the file. No byte, name, size, type, path or
listing reaches it:
1,0or no answer, from a closed list. - Approval outside the agent. Each plan becomes a ticket on
lockhub, which you decide in
lox rununless alox runauto rule does. A plan with an unofficial plugin or typed values always waits for a human. - Fixed, signed questions. Each plugin answers one question from its signed manifest. The agent chooses no value to aim the bit at the content: a protocol-2 plugin may take up to 4 values, which the human types at approval.
- The code that reads the file is boxed. Landlock, seccomp and rlimits: no network, no path, stdout capped at 3 bytes.
Some files must not reach a model: invoices, contracts, medical letters. lockfile answers the one question an agent needs about them, and nothing else.
brew trust davidgodefroid/tap
brew install davidgodefroid/tap/lockfile davidgodefroid/tap/lox cosignlockfile runs in Docker, on Linux (the formula is Linux only; on Windows, WSL 2
with Docker Desktop). Homebrew installs the lockfile launcher, which runs
every command in the release's image. lox is lockhub's CLI: this release
needs lox v0.12.0 or later. lox add and lox run verify every image with
cosign v2.5.0
or later, which the lockfile formula does not pull in. The whole family
instead: brew install davidgodefroid/tap/lockfamily.
Without Homebrew, the signed install script of a release (needs cosign v2.5.0+; install lox v0.12.0+ beside the launcher):
V=vX.Y.Z
curl -fsSLO "https://raw.githubusercontent.com/DavidGodefroid/lockfile/$V/scripts/install.sh"
less install.sh
LOCKFILE_VERSION=$V sh install.shThe launcher, its image, Vault, lea and building from source: docs/install.md and docs/docker.md.
-
In your project, add the file store.
lox addasks where it is (S3, SFTP or a local directory; never a secret), writes the profile, wires your agent and starts the console:lox add lockfile
-
In a terminal of its own, outside any agent, keep
lox runopen. It starts the console, and every plan shows up there:lox run
-
With
lox runup, install the plugins you want, then apply them at the console with:review(filesis the lock's default name):lockfile plugin install file.non-empty@1.0.0 lockfile plugin install format.is-pdf@1.0.0 lox attach files
-
Start your agent in the project (
claude,codex,gemini, …) and ask about a file by its exact key: "is invoices/2026/10/abc123.pdf a valid PDF?"
To wire your agent, run lockfile init <agent> (claude, codex, cursor
or gemini). With
lea, run lox add in lea's projects
directory, then lea stop and lea. Step by step, by hand:
docs/install.md.
|
🔢 Only 1s and 0s |
👤 Human in the loop |
|
🔏 cosign everywhere |
⏱️ Timing padded |
13 official plugins (empty file, PDF header, parses, truncated, blank pages, fonts, JavaScript, …): docs/plugins.md. Profiles and every key: docs/configuration.md.
Two sides in two OS accounts. Only the console touches the file.
sequenceDiagram
autonumber
participant A as 🤖 AI agent<br/>(lockfile mcp / CLI)
participant C as 🔐 lockfile console
participant L as 🎫 lockhub (lox run)
participant S as 🗄️ S3 / SFTP / disk
participant P as 🧱 sandboxed plugins
A->>C: plan --key K --plugin X --plugin Y
C->>S: fetch K once, hash it (sha256 and size)
C->>L: ticket: key, signed questions, hash (your screen only)
C-->>A: pending, ticket T
L-->>C: signed decision (you or an auto rule)
A->>C: run T
C->>S: fetch K again into a 0700 workspace, refuse other bytes
C->>P: the file as a read-only fd 3
P-->>C: 1 or 0 each, checked strictly
C-->>A: one bit per plugin, on the answer quantum
- The agent picks plugins from
lockfile pluginsand plans with the exact key it was given. There is no listing and no stat. - The console validates the plan, then fetches the file once to hash it. The
sha256 and size go only to your masked lockhub screen, never to the agent,
which hears pending with a ticket. You decide it in
lox run. - The agent runs the ticket. The console fetches the file again, refuses
different bytes (
E_STALE), runs each plugin in its own sandbox and returns the answers together, with a handle for follow-up questions.
The approval screen, the agent's commands and MCP tools, and exit codes: docs/architecture.md.
- The console is the enforcement point. Skills, rules and MCP tool descriptions only guide the agent; the console's checks are the guarantee.
- OS separation. The console runs as the
lockfileaccount in its own container; the kernel checks every peer on the socket. - Confined agents only. An agent that does not run confined (in a
container, no runtime socket, no Lock Family state) is refused, unless a
non-production profile sets
unconfined = true(docs/configuration.md). - Bounded leakage.
max_plugins_per_handle(16) caps the answers about one file, and each approval states how many a plan reveals. - Audit for you only. Key, size, sha256 and each plugin's outcome go to a log only the console account can read. Never file bytes.
- Known limits. A plugin that lies about its question is mitigated by
review and signing, not prevented;
plugin_errorandfetch_failedeach carry one symbol; whoever runsdockercan reach the console's container.
Every rule and limit: docs/safety.md. Threat model: docs/security-model.md.
| Doc | What it covers |
|---|---|
| docs/install.md | Homebrew, the install script, the first plan by hand, upgrade, build, status |
| docs/docker.md | the setup: image, volumes, seccomp profile, console, agent wiring, what Docker separates |
| docs/usage.md | every command, profiles, the agent flow, MCP |
| docs/configuration.md | profile keys: S3, SFTP, local, credentials, limits; the company's managed configuration (lockfamily docs/managed.md) |
| docs/architecture.md | the life of a plan, the approval screen, commands and MCP tools, exit codes |
| docs/plugins.md | the official plugins, installing, unofficial marketplaces |
| docs/plugin-contract.md | for plugin authors: manifest, runtime, answer, publishing |
| docs/safety.md | the safety model, in short |
| docs/security-model.md | what the agent can see (the exhaustive list), the boundaries, the residual risks |
| CHANGELOG.md | what changed, release by release |
The site, davidgodefroid.github.io/lockfile, is built from site/.
| Repo | What it does |
|---|---|
| lockfamily | The family site (lockfamily.dev) and the one-line installer. |
| 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 key never leaves the console. |
| lockhub | The approval hub and its lox CLI: lox run approves outside the agent's harness and never sees values in clear. |
| lockkit | The shared Go core of every Lock: console, policies, masking, signed tickets, audit, MCP. |
| lea | Runs many agents in containers, wired to the Locks. |
- Contributing: issues and pull requests on
GitHub. Build with
CGO_ENABLED=0 go build ./cmd/lockfile(Go 1.26+). - Docs: 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: the threat model and its limits are in docs/security-model.md. To report a vulnerability, contact the maintainer (@DavidGodefroid) privately rather than in a public issue.
- License: Apache License 2.0, see LICENSE.