lockfile

Install lockfile

One static binary for both sides, checked against its cosign signature before it is installed.

Every release ships lockfile_<version>_<os>_<arch>.tar.gz for Linux and macOS on amd64 and arm64, a checksums.txt and its keyless cosign signature. No Go toolchain is needed.

Requirements

  • The console needs Linux with Landlock and seccomp, which sandbox the plugins (Landlock also denies TCP from kernel ABI 4). lockfile doctor reports what the kernel offers; without them, plans are refused with E_SANDBOX_UNAVAILABLE.
  • macOS gets the agent side only: the CLI and the MCP server, talking to a console on Linux.
  • cosign on PATH, for the install script, lockfile update and every plugin install. Without it nothing is installed: there is no unsigned mode.
  • sudo once, for lockfile install.

1. The binary

Script (Linux, macOS)

Downloads the archive for your OS and architecture, checks the signature of checksums.txt against lockfile’s release workflow, then the archive against checksums.txt, and installs /usr/local/bin/lockfile, with sudo if needed:

curl -fsSL https://raw.githubusercontent.com/DavidGodefroid/lockfile/main/scripts/install.sh -o install.sh
less install.sh                     # read it first
sh install.sh                       # LOCKFILE_VERSION=v0.2.0 to pin a version

LOCKFILE_INSTALL_DIR picks another directory. Keep the default for the console: lockfile install refuses a binary another account could replace.

By hand

Download the archive, checksums.txt and checksums.txt.sigstore.json from the latest release, then:

cosign verify-blob --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp '^https://github\.com/DavidGodefroid/lockfile/\.github/workflows/release\.yml@refs/tags/v[0-9]' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  checksums.txt
sha256sum --ignore-missing -c checksums.txt   # macOS: shasum -a 256 --ignore-missing -c checksums.txt
tar -xzf lockfile_<version>_<os>_<arch>.tar.gz lockfile
sudo install -m 0755 lockfile /usr/local/bin/lockfile

From source

CGO_ENABLED=0 go install github.com/DavidGodefroid/lockfile/cmd/lockfile@latest   # Go 1.26 or later
sudo "$(go env GOPATH)/bin/lockfile" install --trust-binary

--trust-binary pins this binary’s sha256, since your account can write it.

Docker (demo)

The repository’s Dockerfile builds a demo image of the separated setup, with the console account and an agent account in one container. It is for trying lockfile out, not for production: one container is one kernel, one boundary. The plugin sandbox still needs Landlock and seccomp from the host kernel.

docker build -t lockfile-demo https://github.com/DavidGodefroid/lockfile.git
docker run --rm -it --security-opt seccomp=unconfined lockfile-demo

2. The separated setup (Linux)

sudo lockfile install
lockfile doctor                     # from both accounts

lockfile install creates the lockfile account and the lockfile-clients group, adds your account to it, writes /etc/lockfile/system.toml, creates /run/lockfile and copies a root-owned /usr/local/bin/lockfile. It prints the root script before running it (--print only prints it, --yes skips the question).

Then give the console account a password, log out and in again (your account joined the group), and open a separate session as lockfile (switch user; prefer Wayland) for the console. The console refuses to start in your own account, where the agent runs and could read or type into its terminal.

3. A source profile (console account)

Profiles live in the lockfile account’s ~/.config/lockfile/config.toml; there is no per-project config. lockfile profile add appends one, validated:

# S3 (or an S3-compatible endpoint), credentials from Vault, production
lockfile profile add docs --source s3 --bucket documents --region eu-west-1 --prefix invoices/ \
  --credentials vault --vault-path secret/data/lockfile/docs --production

# SFTP with a key, host key checked against known_hosts
lockfile profile add partner --source sftp --host sftp.example.org --user reader --auth key \
  --key ~/.ssh/partner_ed25519 --known-hosts ~/.ssh/known_hosts --base-dir /outgoing

# A local directory
lockfile profile add samples --source local --path /srv/samples
[profiles.docs]
source = "s3"                 # s3 | sftp | local
bucket = "documents"
region = "eu-west-1"
endpoint = ""                 # S3-compatible server; https:// (http:// only for localhost)
prefix = "invoices/"          # keys outside the prefix are refused
credentials = "vault"         # ask | keychain | vault
vault_path = "secret/data/lockfile/docs"
production = true             # the profile name is typed for every approval
max_object_bytes = "50MiB"    # larger objects are not fetched
max_plugins_per_handle = 16   # answers revealed about one fetched file, at most
handle_ttl = "30m"            # a fetched file is deleted after this
answer_quantum = "5s"         # results leave the console only on multiples of this

No file ever holds a secret: it is typed at console start (ask), read from the console account’s keychain, or read from Vault. lockfile forget --profile P deletes a keychain secret. The full list of keys is in the usage guide.

4. Plugins (console account)

lockfile plugin install file.non-empty@1.0.0     # exact versions only; signatures checked with cosign
lockfile plugin install format.is-pdf@1.0.0
lockfile plugin install pdf.parses@1.0.0
lockfile plugin list

The official marketplace’s signer is pinned in the binary. See Plugins for the catalogue, updates, unofficial marketplaces and how to write your own.

5. The console

lockfile console --profile samples

It checks the isolation (separate account and session), asks for the secret, connects and serves the profile’s socket. Keep it in view: every plan waits for you there.

6. Wire your agent (your account)

lockfile init claude                # or codex, cursor, gemini; this project
lockfile init claude --user         # every project of this account
lockfile doctor --fix               # wires the installed agents not wired yet

Claude Code may call lockfile_status, lockfile_sources and lockfile_plugins without a prompt; plans and runs always go through Claude Code’s permission prompt and the console.

Upgrade

lockfile update [--check] [--yes]

Checks checksums.txt against the signature of lockfile’s release workflow, then the archive against it, then replaces the binary (with sudo from a pinned copy when root owns it). Restart the console afterwards.

Build

CGO_ENABLED=0 go build ./cmd/lockfile

Requires Go 1.26 or later.