How to install lockhttp, set it up with lea and lockhub, and the commands of its launcher. The short path is in the README.
Moved from the README, whole.
lox runruns the hub and the lockhttp console, writes.lockfamily/up.jsonand serves the decisions in its terminal; it replaces lockhub's deprecatedlox up.
LockHTTP runs in Docker. On the host there is only the lockhttp launcher,
a shell script that runs every command in the release's image
(ghcr.io/davidgodefroid/lockhttp:X.Y.Z, amd64 and arm64). With Homebrew:
brew trust davidgodefroid/tap (Homebrew asks to trust a third-party tap
once), then brew install davidgodefroid/tap/lockhttp (or
davidgodefroid/tap/lockfamily for the whole family, lox and cosign
included). The lockhttp formula pulls in neither lox nor cosign: name
them with it, brew install davidgodefroid/tap/lockhttp davidgodefroid/tap/lox cosign.
lockhttp v0.12 needs lockhub's lox v0.12.1 or later (it passes
--runtime-gids to the console) and cosign v2.5.0 or later (lox add
and lox run verify every image with it). Without Homebrew,
the Lock Family's installer puts the same launcher in ~/.local/bin
(lockfamily install):
curl -fsSL https://lockfamily.dev/install.sh | shThe installer verifies the keyless cosign signature of the release and of
its image against this repository's release workflow, and writes the
verified image digest into the launcher. The brew formula checks the
archive's SHA-256 and writes the image digest the tap verified with cosign
when it was bumped. Either way the launcher runs the image by that digest. lea's LEA_LOCKHTTP=1 uses
this launcher from lea v0.16.0 on (it checks the digest against its pin or
with cosign); older lea accept only a root-owned /usr/local/bin/lockhttp,
which lockhttp no longer installs (scripts/install.sh is gone since
v0.11.0). Linux (Docker Engine) and macOS (Docker Desktop); on Windows,
WSL 2 with Docker Desktop.
| Command | Runs as | What it does |
|---|---|---|
lockhttp profile add [--non-interactive] [--json] [--profile NAME] [--production] [--trusted "a.com .corp.example"] |
you, on the project | Adds a profile with the default policy to the project's .lockhttp/config.toml (never rewrites one already there; never takes a secret). |
lockhttp init <agent> |
you, on the project | Nothing to write: lockhttp has no agent files (lea routes the agent's HTTP through the gate). |
lockhttp doctor [--fix [--yes]] [--json] [--gate ADDR] [--ca-cert FILE] |
you, on the project | Separated setup, the project's policy and its permissions, CA, gate; --fix repairs the permissions. |
lockhttp policy show|edit|path |
lockhttp, volume lockhttp-home |
Prints, edits or locates the console's copy of the policy. |
lockhttp console |
lockhttp, container lockhttp-console |
The policy console (under lox run, its own service runs it). It must run in a terminal. |
lockhttp gate |
gate, container lockhttp-gate |
The proxy. It needs the hub flags (--hub, --hub-key-file, --instance): lea passes them from lox run's up.json. |
lockhttp version, lockhttp update [vX.Y.Z] |
The launcher's and the image's versions; a newer release's launcher, checked the same way, and its image. |
LOCKHTTP_IMAGE runs an image of your own (docker build -t lockhttp .
from a clone), LOCKHTTP_DOCKER_ARGS adds docker run arguments. There is
no host install. Coming from v0.1.0's
sudo lockhttp install: migrating from a host
install.
The README's demo is generated by scripts/brand/demo.py:
python3 scripts/brand/demo.py > site/assets/demo.svg. Its terminals show
the capture in scripts/brand/demo-capture/: output of the gate and of
lox run, taken in two separate test runs and joined by hand
(how).
Accounts, volumes, the exact docker run of each command, and what Docker
does and does not separate: docs/docker.md. Every command
and flag: docs/usage.md.
LockHTTP runs in Docker and hub-attached only: lockhub's
lox run runs the hub and the lockhttp console for your projects directory,
and lea runs the gate beside its
proxy container when LEA_LOCKHTTP=1, with the hub flags lox run writes in
.lockfamily/up.json. The contract between lockhttp and lea (files, mounts,
uids, network rules) is in docs/lea.md; the one between
lox run and lea in lockhub's docs/lox-run.md.
LockHTTP needs lea, and lox add lockhttp sets it up (its only question is
the lock's name): see lockhub's
docs/lox-add.md.
# 1. Install the Lock Family (lox, lea and the launchers), or only this tool;
# Homebrew asks to trust a third-party tap once
brew trust davidgodefroid/tap
brew install davidgodefroid/tap/lockfamily # or, with lox and cosign: brew install davidgodefroid/tap/lockhttp davidgodefroid/tap/lox cosign
# or the launcher alone: see Install
# 2. In lea's projects directory (LEA_PROJECTS_DIR: lea reads
# .lockfamily/up.json only at its root): a lockhttp lock, the hub, its console
cd ~/projects
lox add lockhttp # asks for the lock's name: profile add, the declaration, lox run, the console
# or by hand:
# lockhttp profile add # the policy: .lockhttp/config.toml, which lox run reviews and copies
# lox add lockhttp web
# lox run # runs the hub and the console, registers the gate's key
# lox attach web # the console's terminal: approve its first policy (detach: Ctrl-P Ctrl-Q)
# 3. Turn LockHTTP on in lea's configuration, then restart lea: its gate asks
# the hub. LEA_LOCKHTTP=1 in the environment alone is ignored (lea's
# configuration wins and lea warns). lea mounts the locks' sockets when its
# container starts, and lea-proxy and its gate are shared by every lea on
# the machine (on or off for all of them), so stop them all.
echo LEA_LOCKHTTP=1 >> ~/.config/lea/lea.conf
lea stop --all
lea
# 4. Approve the held requests on a facade of the hub
lox approveThe console runs as the lockhttp account (uid 10021) in lox run's
service; lea's gate runs as gate (uid 10003) in a container of its own
and shares only the console's socket volume with it. Without a trusted
up.json naming a lockhttp lock, lea does not start the gate: it says to
run lox run. lockhttp gate refuses to start without its hub flags
("launched by lox run only").