README
¶
lockfile
Your AI asks about the file. It never reads it.
lockfile lets an AI agent ask yes/no questions about a file it must never
read: is this invoice empty, a PDF, does it parse, does it have a blank page,
is it truncated? A console run by a human in a separate OS account fetches
the file from S3, SFTP or a local directory, runs signed, sandboxed plugins
on it, and returns only each plugin's answer: 1, 0, or no answer. No byte
of the file, its name, size, type or path ever reaches the agent, and every
plan is approved by the human first.
Plugins come from a signed marketplace (lockfile-marketplace): each answers one fixed question, written in its signed manifest.
agent account (CLI / MCP) lockfile account (console, human terminal)
lockfile plan/run/answers ──UDS──▶ approve ─▶ fetch ─▶ workspace (0700)
▲ JSON-RPC │ fd 3, read-only
│ ▼
└────── 1 / 0 per plugin ◀── strict check ◀── sandboxed plugin process
Quick start (Linux)
# 1. The binary (checks the release signature with cosign).
curl -fsSL https://raw.githubusercontent.com/DavidGodefroid/lockfile/main/scripts/install.sh -o install.sh
sh install.sh
# 2. The separated setup: console account `lockfile`, your account in `lockfile-clients`.
sudo lockfile install
lockfile doctor
# 3. In the lockfile account's own session (switch user, Wayland):
lockfile profile add samples --source local --path /srv/samples --prefix invoices/
lockfile plugin install file.non-empty@1.0.0
lockfile plugin install format.is-pdf@1.0.0
lockfile console --profile samples
# 4. In your account: wire your agent, then ask.
lockfile init claude
lockfile plugins --json
lockfile plan --key invoices/2026/10/abc123.pdf --plugin file.non-empty --plugin format.is-pdf --run --json
{"handle":"f_8Kq2xR","answers":[
{"plugin":"file.non-empty","version":"1.0.0","official":true,"result":1},
{"plugin":"format.is-pdf","version":"1.0.0","official":true,"result":0}]}
result: null with "error": "plugin_error" means the plugin gave no
answer: it is not a 0.
Documentation
- Usage: every command, profiles, the agent flow, MCP.
- Security model: what the agent can see (the exhaustive list), the boundaries, the residual risks.
- Plugin contract: for plugin authors.
Status
v0.2: console, agent CLI, MCP server and agent wiring on
lockkit. The console needs Linux
(Landlock and seccomp sandbox the plugins); macOS gets the agent side only.
Not yet: an onboarding wizard (setup), a macOS console, public-key trust roots for
unofficial marketplaces.
License
Apache-2.0, see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
lockfile
command
Command lockfile lets an AI agent ask yes/no questions about a file it never reads: a separate account fetches the file and runs signed plugins on it in a sandbox, and the agent gets 1 or 0 per plugin.
|
Command lockfile lets an AI agent ask yes/no questions about a file it never reads: a separate account fetches the file and runs signed plugins on it in a sandbox, and the agent gets 1 or 0 per plugin. |
|
Package index is the format of a marketplace's signed index.json: every plugin, its versions, the manifest hash and the per-platform artifacts.
|
Package index is the format of a marketplace's signed index.json: every plugin, its versions, the manifest hash and the per-platform artifacts. |
|
internal
|
|
|
answers
Package answers runs plugins on a fetched file and turns their outcomes into what the agent may see: per plugin 1, 0, or no answer with a code from a closed list.
|
Package answers runs plugins on a fetched file and turns their outcomes into what the agent may see: per plugin 1, 0, or no answer with a code from a closed list. |
|
backend
Package backend is lockfile on lockkit's console: the Backend that connects a profile's source, validates and shows plans for approval, runs the approved ones and returns only the closed result of design §7b.
|
Package backend is lockfile on lockkit's console: the Backend that connects a profile's source, validates and shows plans for approval, runs the approved ones and returns only the closed result of design §7b. |
|
clientcmd
Package clientcmd is the agent's side of lockfile, shared by the CLI and the MCP server: it calls a running console and turns every answer into a value of the closed list of design §7b.
|
Package clientcmd is the agent's side of lockfile, shared by the CLI and the MCP server: it calls a running console and turns every answer into a value of the closed list of design §7b. |
|
marketplace
Package marketplace installs plugins from a signed marketplace index: the index, then the artifact, are checked against the marketplace's trust root, and every downloaded byte against the hashes the signed index lists.
|
Package marketplace installs plugins from a signed marketplace index: the index, then the artifact, are checked against the marketplace's trust root, and every downloaded byte against the hashes the signed index lists. |
|
mcpserver
Package mcpserver is lockfile's MCP server: one tool per agent command, each a thin adapter over clientcmd.
|
Package mcpserver is lockfile's MCP server: one tool per agent command, each a thin adapter over clientcmd. |
|
plugin
Package plugin is the local plugin store: verified plugin binaries and manifests under <Dir>/plugins/<qualified name>/<version>/ (0500), and <Dir>/plugins.lock recording what was verified at install time.
|
Package plugin is the local plugin store: verified plugin binaries and manifests under <Dir>/plugins/<qualified name>/<version>/ (0500), and <Dir>/plugins.lock recording what was verified at install time. |
|
product
Package product holds lockfile's names for lockkit, its refusal codes and its command exit codes.
|
Package product holds lockfile's names for lockkit, its refusal codes and its command exit codes. |
|
profile
Package profile reads lockfile's configuration (design §4) on lockkit's config base: source profiles, limits and marketplaces, from the config file of the lockfile account.
|
Package profile reads lockfile's configuration (design §4) on lockkit's config base: source profiles, limits and marketplaces, from the config file of the lockfile account. |
|
rpc
Package rpc holds the wire types of lockfile's console methods, shared by the console's backend and its clients (CLI and MCP).
|
Package rpc holds the wire types of lockfile's console methods, shared by the console's backend and its clients (CLI and MCP). |
|
separate
Package separate builds the one-time root setup that separates a product's console from the agent: a console account, a clients group the agent's account joins, the root-owned system file the console requires (lockkit sysconf), the shared socket directory, and a root-owned copy of the binary.
|
Package separate builds the one-time root setup that separates a product's console from the agent: a console account, a clients group the agent's account joins, the root-owned system file the console requires (lockkit sysconf), the shared socket directory, and a root-owned copy of the binary. |
|
source
Package source fetches one object by its exact key from S3 (or an S3-compatible store), SFTP or a local directory.
|
Package source fetches one object by its exact key from S3 (or an S3-compatible store), SFTP or a local directory. |
|
testenv
Package testenv starts in-process protocol servers for tests: an S3 fake over HTTP and an SSH server with a read-only SFTP subsystem.
|
Package testenv starts in-process protocol servers for tests: an S3 fake over HTTP and an SSH server with a read-only SFTP subsystem. |
|
testenv/consoletest
Package consoletest runs a real lockfile console in the test process: lockkit's console.Run on lockfile's backend, a local source, plugins built from sandbox/testdata, a scripted human and a real socket in the test's private runtime directory.
|
Package consoletest runs a real lockfile console in the test process: lockkit's console.Run on lockfile's backend, a local source, plugins built from sandbox/testdata, a scripted human and a real socket in the test's private runtime directory. |
|
verify
Package verify checks signatures of marketplace indexes and plugin artifacts against a trust root.
|
Package verify checks signatures of marketplace indexes and plugin artifacts against a trust root. |
|
wiring
Package wiring holds lockfile's agent texts (skill, instructions, Cursor rule) and their wiring through lockkit's agentwire.
|
Package wiring holds lockfile's agent texts (skill, instructions, Cursor rule) and their wiring through lockkit's agentwire. |
|
workspace
Package workspace holds fetched files in the lockfile account: one private directory per handle, a random file name, never the source name.
|
Package workspace holds fetched files in the lockfile account: one private directory per handle, a random file name, never the source name. |
|
Package pluginspec is the lockfile plugin contract: the signed manifest a plugin ships with, and the rule that turns a plugin's stdout and exit status into an answer.
|
Package pluginspec is the lockfile plugin contract: the signed manifest a plugin ships with, and the rule that turns a plugin's stdout and exit status into an answer. |
|
Package sandbox runs one plugin binary on one input file under Landlock, seccomp-bpf and rlimits, and turns what it produced into a pluginspec.Outcome.
|
Package sandbox runs one plugin binary on one input file under Landlock, seccomp-bpf and rlimits, and turns what it produced into a pluginspec.Outcome. |
Click to show internal directories.
Click to hide internal directories.