Skip to content
DavidGodefroidPublic

About

Harness security for AI agents, for files: a Lock of the Lock Family. Agents ask yes/no questions about files (S3, SFTP, disk) they never read.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

lockfile: your agent asks about the file. It never reads it.

CI Latest release License: Apache 2.0 Go version

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.

Demo, step by step. 1: an agent (here Claude Code, left) runs lockfile plan with three yes/no plugins on an invoice and is told the plan is pending human approval. 2: the plan shows as a question in lox run (top right), the email address in its key masked. 3: you open the details, read each plugin's question, and press y to approve. 4: the agent runs the ticket; the lockfile console (bottom right) fetches the file and runs the three signed plugins in the sandbox. 5: only their answers, 1, 1 and 1, reach the agent.

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.

Why lockfile

  • The agent never reads the file. No byte, name, size, type, path or listing reaches it: 1, 0 or no answer, from a closed list.
  • Approval outside the agent. Each plan becomes a ticket on lockhub, which you decide in lox run unless a lox run auto 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.

Install

brew trust davidgodefroid/tap
brew install davidgodefroid/tap/lockfile davidgodefroid/tap/lox cosign

lockfile 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.sh

The launcher, its image, Vault, lea and building from source: docs/install.md and docs/docker.md.

Quick start

  1. In your project, add the file store. lox add asks 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
  2. In a terminal of its own, outside any agent, keep lox run open. It starts the console, and every plan shows up there:

    lox run
  3. With lox run up, install the plugins you want, then apply them at the console with :review (files is 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
  4. 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.

Highlights

🔢 Only 1s and 0s
Everything the console sends the agent comes from a closed list, checked end to end over the socket. No size, type, hash, name, listing or error text.

👤 Human in the loop
Every plan is a lockhub ticket, decided in lox run outside the agent, by you or by an auto rule you set. The screen says how many answers the plan reveals.

🔏 cosign everywhere
Plugins, the marketplace index and lockfile's own releases are checked against cosign signatures with a Rekor entry: keyless for official ones, or a pinned public key for an unofficial marketplace. There is no unsigned mode.

⏱️ Timing padded
A run's result leaves the console only at the next multiple of answer_quantum (5 s by default).

13 official plugins (empty file, PDF header, parses, truncated, blank pages, fonts, JavaScript, …): docs/plugins.md. Profiles and every key: docs/configuration.md.

How it works

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
Loading
  1. The agent picks plugins from lockfile plugins and plans with the exact key it was given. There is no listing and no stat.
  2. 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.
  3. 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.

Safety model

  • 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 lockfile account 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_error and fetch_failed each carry one symbol; whoever runs docker can reach the console's container.

Every rule and limit: docs/safety.md. Threat model: docs/security-model.md.

Documentation

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/.

The Lock Family

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 · Security · License

  • 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's docs-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.

About

Harness security for AI agents, for files: a Lock of the Lock Family. Agents ask yes/no questions about files (S3, SFTP, disk) they never read.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages