Install · pre-release
Install lea
lea runs in Docker. On your machine you need Docker, the lea command and, for the Locks, lox.
With Homebrew
brew trust davidgodefroid/tap
brew install davidgodefroid/tap/lox davidgodefroid/tap/lea
Needs Docker (on macOS, the formula also installs tmux). Then run lea in the directory that holds your projects, and keep lox run open beside it for the Locks. The whole family: brew install davidgodefroid/tap/lockfamily.
Homebrew asks you to trust a third-party tap once, hence brew trust first. lox is the Lock Family’s hub; lea alone does not need it, its Locks do.
Upgrade with brew upgrade lea lox.
The first run
Go to the directory that holds your projects, not a project inside it, and run
lea.cd ~/projects lealea asks once whether you want lea deck or your own tool in the container (
lea config deck on|offchanges it later). It checks that Docker answers, pulls and verifies its images, and records the projects directory. On Linux hosts where Docker uses AppArmor, the firstleadoes not prompt forsudo: it stops and tells you to runlea initonce (it asks forsudoto install lea’s AppArmor profile and egress log), thenlea.lea deck, lea’s terminal interface, opens on a Control Tower, a lead on Claude Code that runs
/lea:control-tower. Log in once (/login); the login is lea’s own, kept per projects directory, never your host’s.Press n for another agent, N for another Control Tower, ? for the keys, q to leave. The agents keep running.
LEA_PROJECTS_DIR, in the environment or in ~/.config/lea/lea.conf, wins over the working directory. lea refuses /, your home directory, a parent of it, and a directory that overlaps ~/.claude or a credentials directory.
Requirements
- Linux, macOS, or Windows with WSL 2 (run lea from your WSL distribution).
- Docker Engine on Linux, or Docker Desktop, running and usable without
sudo; a patched host kernel (the kernel). - On macOS, tmux 3.2 or later (
brew install tmux); the Linux release brings its own. curl,tar,ssh-keygen, andsha256sumorshasum. The installer downloadscosignwhen it is missing.- A subscription or API key for your agent: Claude Code by default, or Codex.
lea runs sudo only on Linux, to install two host files once: its AppArmor profile (where Docker uses AppArmor) and its egress log, an nftables table with its systemd unit lea-egress-log.service (where nft and systemd are present). lea init asks for it; a plain lea uses it only when sudo needs no password, and lea doctor runs sudo -n checks that never prompt.
Add the Locks
The Locks keep a human between your agents and production: locksql (SQL databases), lockmq (RabbitMQ), lockfile (files), locklog (logs), lockssh (commands over SSH) and lockhttp (outbound HTTP). Each runs as a console that alone holds the credentials.
Run lox add in lea’s projects directory, then keep lox run open in a terminal of its own, outside lea. Use a recent lox: lea doctor warns when it is older than the release lea pins.
lox add locksql # or lockmq, lockfile, locklog, lockssh
lox run
lox run starts the projects directory’s hub and locks, approves what the rules allow on its own, and asks you for the rest. A Lock is on for lea as soon as lox run runs a lock of its type there; LEA_LOCKSQL=0 (and so on) keeps one off.
A lock added while lea runs reaches the agents after lea stop, then lea: Docker cannot add a mount to a running container.
lockhttp also needs its launcher on the host (brew install davidgodefroid/tap/lockfamily) and LEA_LOCKHTTP=1 in ~/.config/lea/lea.conf; it refuses LEA_GIT_SSH and LEA_OTEL_UPSTREAM, whose forwarders would bypass its gate. Its gate then sits beside lea’s proxy and every outbound request goes through it, once you run lea stop --all, then lea (LEA_LOCKHTTP=1 lea alone is ignored, with a warning). Web requests, with LockHTTP.
Git and forges
Git over HTTPS works out of the box with GitHub and GitLab; another forge (Bitbucket, Codeberg, your own) needs lea egress allow DOMAIN once. For GitHub, give lea a token on the host, once: it stays in the proxy, and the agents’ gh and git use it without reading it.
gh auth token | lea github login
lea github status
Prefer a fine-grained token, limited to the repositories of the projects directory. For SSH (refused with LEA_LOCKHTTP=1), list the endpoints in ~/.config/lea/lea.conf, pin their host keys and rerun lea init: it prints lea’s own public key to add to your forge.
echo 'LEA_GIT_SSH="github.com:22"' >> ~/.config/lea/lea.conf
ssh-keyscan github.com >> ~/.config/lea/git_known_hosts # compare the fingerprints
lea init
Without Homebrew
lea’s own installer checks the requirements, downloads the release for your platform and verifies its checksum and signature. It then links ~/.local/bin/lea (when ~/.local/bin is not on your PATH, it only prints a hint) and runs lea init, which asks for your projects directory.
curl -fsSL https://leadeck.dev/install.sh | sh
lea
It never installs on the checksum alone: without a valid cosign signature it stops. The only exceptions are v0.1.0 and v0.1.1, released before signing: their checksums.txt is accepted when it matches the SHA-256 the installer pins, unless LEA_REQUIRE_COSIGN=1. Signed releases.
From source: clone the repository and run bin/lea init, which builds lea and its images with make and Docker (Go runs in a container).
Other agents
An agent runs on a provider: claude (Claude Code, the default), codex (OpenAI’s Codex CLI, in the image), or an OpenAI-compatible endpoint of your own, run through Codex.
lea new -p codex # one Codex agent
lea config tool codex # the tool lea starts without the deck
lea config deck off # without the deck, from the next lea
LEA_PROVIDER and LEA_MODEL set the default. Endpoints such as Ollama or vLLM go in ~/.config/lea/providers, with a key file that only the proxy mounts. Providers.
Update and uninstall
A release install updates itself at most once a day: a new patch release, its signature checked, becomes active at the next lea. lea update does it now, lea rollback goes back one version, and LEA_AUTOUPDATE=0 turns it off.
lea stop --all --forget
rm -rf ~/.local/bin/lea ~/.local/share/lea-install ~/.local/share/lea ~/.config/lea
docker image ls 'ghcr.io/davidgodefroid/lea*' # then docker image rm the ones listed
docker network rm $(docker network ls -q --filter label=lea.prefix)
# Linux, what lea init installed with sudo:
sudo systemctl disable --now lea-egress-log.service
sudo nft delete table bridge lea_egress
sudo rm -f /etc/systemd/system/lea-egress-log.service /etc/lea/egress-log.nft
sudo apparmor_parser -R /etc/apparmor.d/lea && sudo rm -f /etc/apparmor.d/lea
Installed with Homebrew, brew uninstall lea removes the command; lea’s data, configuration and images are removed as above. A source install also leaves the lea:dev, lea-proxy:dev and lea-ctl:dev images, its clone and the Go cache, ~/.cache/lea-go.