lea is the confined runtime of the Lock Family.
lea runs your coding agents side by side in a container: Claude Code by default, OpenAI's Codex
CLI, or a model of your own (Ollama, vLLM, any OpenAI-compatible endpoint) through Codex. The
container sees one directory of your projects (read/write), a read-only allow-list of your
~/.claude configuration for Claude Code (its own copy of your settings and plugins, never
written back) plus that projects directory's transcripts (~/.claude/projects/<slug>,
read/write), and none of your other files (see What an agent can read). The
agents get their own container engine (so make test and docker run work), reach the
internet only through an egress proxy that refuses your private network, and never see your SSH
keys or credentials.
You drive them from lea deck: a terminal with your agents in a column on the left and the selected agent's terminal on the right.
╭─ ●●● lea ──────── 3 agents ─╮│
│› ⠹ fix login timeout 42% ││ ✻ Claude Code
│ shop · fix/login · 2m ││
│ ● review cart api 18% ││ > the timeout is set in session.go…
│ reviewer · shop · now ││
│ ● add dark mode 7% ││
│ shop · needs you ││
╰─ n new · m msg · ? keys ────╯│
- lea is the tool: the
leacommand and its host daemon, the container the agents run in, the egress proxy, the providers, roles and the Control Tower, messages between agents, allowances and grants, and the MCP tools agents use to talk to lea. - lea deck (the deck, for short) is lea's interface: the terminal
leaopens, its rows, keys, menus and dialogs, and the same deck in your browser withlea web. It runs on your machine, outside the container, so no agent can drive it.
Both come in the one lea binary. lea works without the deck (lea config deck off, see
Without the deck); the deck does nothing without lea. leadeck.dev is lea's
site.
A coding agent does more when you stop approving every command, and a few agents in parallel do more than one. Both are risky on your workstation: an agent runs as you, with your keys, your tokens and your network. lea moves the boundary from the prompt to the container.
- Isolated by construction. What an agent can reach is fixed by the container and the proxy,
not by its good behaviour. A prompt-injected agent with every permission granted still cannot
read
~/.sshor call your intranet. - Many agents, one screen. lea deck shows states, context use, branches and each agent's own task report at a glance; one key to reach the next agent that needs you.
- Your agent CLI, unchanged. lea runs the real Claude Code or Codex with your subscription
or API key, or Codex on an endpoint of your own (see Other providers).
For Claude Code, your settings, permission rules, skills, plugins, hooks and agents come along:
/plugin installworks inside lea, on lea's own copy, and nothing reaches your host. - Local and open. No account, no server, no forge lock-in. Apache 2.0.
flowchart LR
subgraph host["Your machine"]
keys["~/.ssh, ~/.aws, ~/.kube<br/>Docker socket"]
lan["Private network<br/>192.168.0.0/16, 10.0.0.0/8 …"]
proj["~/projects"]
cfg["~/.claude (allow-list)"]
subgraph lea["lea container"]
a1["agent: lead"]
a2["agent: dev"]
a3["agent: reviewer"]
podman["rootless Podman"]
end
proxy["egress proxy"]
end
net["Internet: GitHub, npm, model APIs …"]
proj <-->|read/write| lea
cfg -->|read-only| lea
lea --> proxy -->|HTTPS, pinned SSH| net
proxy -.-x|refused| lan
keys -.-x|not mounted| lea
Contents: Quick start · lea deck · Git and forges · Databases · Queues and files · Logs · SSH hosts · Web requests · Teams of agents · Commands · Configure · Safety · FAQ · Troubleshooting · Development
brew trust davidgodefroid/tap # Homebrew asks you to trust a third-party tap once
brew install davidgodefroid/tap/lockfamily # the Lock Family: lea, lox and the Locks' launchers
cd ~/projects # lea's projects directory, not a project inside it
lea # the first run sets everything up
lox add locksql # when your agents need a database (lockmq, lockfile, locklog, lockssh, lockhttp likewise)brew install davidgodefroid/tap/lea installs lea alone. The journey is brew, lea,
lox add: there is no separate setup command to run first.
On a first run lea initialises itself: it checks that Docker answers, pulls and verifies the
images, installs its AppArmor profile on Linux hosts that use it (it needs sudo once: when
sudo would prompt, lea stops with "the AppArmor profile 'lea' needs sudo once: run lea init,
then lea"), records the projects directory, then opens the deck. Before all that, on a
terminal and while LEA_DECK is not set, it asks once whether you want the deck or your own
tool in the lea container (see Without the deck): it records the answer
and the command that switches it, and opens that tool instead of the deck on a no. The projects directory is LEA_PROJECTS_DIR
when you preset it (in the environment or in ~/.config/lea/lea.conf: a preset value wins over
the working directory); when it is unset, it is the directory you ran lea from. If that
directory cannot be one (/, your home directory or a parent of it, or one that overlaps
~/.claude or a credentials directory), lea says why and to
cd into the directory that holds your projects and run lea again, or LEA_PROJECTS_DIR=DIR lea.
Lock approvals live outside lea, in lox run. Two kinds of approval are told apart: the
agents' own permission prompts (Claude Code's "may I run this?") are answered in the deck; the
Locks' tickets (a database connection, a write) are answered in lox run. lea runs no lox
command but lox version in lea doctor: it starts no hub (no lox init) and shows no lock
approval, ticket or lock console. Keep
lox run open in a
terminal of its own, outside lea (a recent lox: lea doctor warns when it is older than the
release lea pins in config/locks.lock; brew install davidgodefroid/tap/lox):
it starts the projects directory's hub and locks, shows every request of the agents, approves
reads on its own and asks you for connections and writes. When the projects directory declares
locks (.lockfamily/lockfamily.yaml) and no lox run serves them, lea says, as it starts:
"Open another terminal (outside lea) and run lox run to approve the agents' connections and
writes." lea starts anyway: the agents reach the locks' sockets, and their requests wait at the
hub until lox run decides them. The deck's status line and lea doctor say the same while it
does not serve. LEA_LOX_UP is obsolete: lea warns when it is set, and ignores it.
lox add is how a Lock
gets set up for lea's agents, run in lea's projects directory (lea reads .lockfamily/up.json
only there; a plain claude on the host uses the nearest one from the project up). A tool
(locksql, lockmq, lockfile, locklog, lockssh) is on for lea once lox run runs a lock of its type there: you
need not turn it on, and LEA_<TOOL>=0 in ~/.config/lea/lea.conf keeps it off. A lock added
while lea runs reaches the agents once lea restarts (lea stop, then lea): restarting an
agent or the deck does not give a running container a new mount. Without Homebrew,
lea's own installer:
curl -fsSL https://leadeck.dev/install.sh | sh
leaThe installer checks the requirements, downloads the release for your platform and verifies its
checksum and the release's signature (see Verify a release), links
~/.local/bin/lea, then runs lea init, which asks for your projects directory and pulls the
images. The first agent is a Control Tower (see Control tower); in it, run
/login once (Claude Code's own login, kept per projects directory; the Control Tower runs on
Claude Code). Press n for another agent, P for one on another provider, N for another
Control Tower.
- Linux, macOS, or Windows with WSL2 (run lea from WSL).
- Docker Engine (Linux) or Docker Desktop, running, usable without
sudo; a patched host kernel (see How lea keeps your machine safe). - On macOS, tmux 3.2 or later (
brew install tmux); the Linux release brings its own. Without the deck (--no-deck), onlylea newneeds it. curl,tar,ssh-keygen, andsha256sumorshasum.- A subscription or API key for your agent: Claude Code (the default, and needed for the Control Tower), Codex, or an OpenAI-compatible endpoint of your own run through Codex.
lea never runs sudo itself, except in lea init on Linux hosts, and only when what it
installs changed: lea's AppArmor profile where Docker uses AppArmor, and lea's
egress log (/etc/lea/egress-log.nft and lea-egress-log.service) where Docker
runs rootful and nft and systemd are installed. The first lea does the same installs when
sudo -n works without a prompt; when sudo would prompt, it stops for the AppArmor profile
and skips the egress log, and says to run lea init. lea doctor only runs non-prompting
sudo -n checks of the egress log.
Each release is signed keyless with cosign (Sigstore, GitHub
OIDC) by the release workflow, on its v* tag: checksums.txt (bundle
checksums.txt.sigstore.json, a release asset) and the lea and lea-proxy images, by digest.
The installer verifies checksums.txt with cosign before trusting it: the cosign on your
PATH, else cosign v3.0.6, which it downloads from Sigstore's GitHub release and checks against
the SHA-256 pinned in install.sh (it never fetches a "latest" cosign). It stops on a bad
signature, on a missing signature, and when no cosign can be had: it never installs on the
checksum alone. The only exception is v0.1.0 and v0.1.1, which predate signing: their
checksums.txt must then be the genuine one, whose SHA-256 the installer pins (it stops
otherwise), and the install goes on by checksum, with a warning. LEA_REQUIRE_COSIGN=1 removes
that exception too. lea update and the background update verify the signature the same way
before they run the new release's installer. Each tag also bumps the lea formula of the
Homebrew tap (brew trust davidgodefroid/tap, then brew install davidgodefroid/tap/lea), from the same signed checksums.txt.
curl -fsSL https://leadeck.dev/install.sh | LEA_REQUIRE_COSIGN=1 shBy hand, with the same identity and issuer. The images are signed in the Sigstore bundle
format: verifying them needs cosign v3 or later, or cosign v2.6 or later with
--new-bundle-format. Without that flag cosign v2 answers no signatures found, although the
image is signed. verify-blob --bundle works with either:
cosign verify-blob --bundle checksums.txt.sigstore.json \
--certificate-identity-regexp '^https://github\.com/DavidGodefroid/lea/\.github/workflows/release\.yml@refs/tags/v[0-9]' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
checksums.txt
cosign verify \
--certificate-identity-regexp '^https://github\.com/DavidGodefroid/lea/\.github/workflows/release\.yml@refs/tags/v[0-9]' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
ghcr.io/davidgodefroid/lea:<version> # and ghcr.io/davidgodefroid/lea-proxy:<version>
# cosign v2 (2.6 or later): cosign verify --new-bundle-format, then the same argumentsThe limit: the installer comes from the same GitHub account as the release. The signature protects against a tampered asset or mirror, and every signature is logged publicly (Rekor), so it can be audited; it does not replace trusting that account.
lea opens lea deck, lea's interface. Each agent is its provider's CLI (Claude Code, Codex) running in the lea
container under abduco, so
closing the deck, or the terminal, does not stop it: the next lea reattaches.
| Key | Action |
|---|---|
j / k, ↓ / ↑, 1–9 |
select an agent (the right side follows) |
enter |
type into the selected agent |
ctrl+space |
back to the column (and forth) |
space |
the next agent that needs you (a permission, a message for you) |
n |
start a new agent |
N |
start a new Control Tower: a lead on Claude, labelled Control Tower, running /lea:control-tower |
P, then a digit |
start a new agent on another provider (any other key cancels) |
e |
rename the selected agent (enter saves, esc cancels, empty clears) |
m / t |
send the selected agent a message / read its messages (see below) |
a / d / A |
allow / deny / always allow the selected agent's permission request |
r, then l / d / r |
make the selected agent a lead, a dev or a reviewer |
s |
open a shell in the container (exit or x closes it) |
- / | |
split: a shell below the selected agent, or at its right, in its directory |
S |
sounds on or off (the top border says muted while they are off) |
T |
pick the deck's theme: the arrows preview each one live, enter keeps it (saved as LEA_THEME), esc puts the old one back |
p, then y |
pause the selected agent (any other key cancels); p alone resumes a paused one where it stopped (its conversation stays), and enter on it resumes it before focusing it |
H |
hold the messages other agents send the selected agent (they wait in its inbox); H again releases them |
Q |
the selected Control Tower's questions to you: the open one, then the queue (picking a queued one drops it) |
< / > |
narrow / widen the deck's column |
, |
settings (also in a row's right-click menu) |
g |
the allowances (lea allow) in force |
x, then y |
stop the selected agent |
f |
new folder (enter names it) |
o |
move the selected agent into a folder, or to another one |
u |
take the selected agent out of its folder |
J / K |
move the selected folder, or an agent within its folder, down / up |
enter, h / l on a folder |
fold / unfold it (e renames it, c colours it, x, then y deletes it: its agents go back, never stopped) |
h on an agent in a folder |
fold its folder |
q |
leave the deck; agents keep running |
? |
list the keys |
The mouse works too: click a row to select it, scroll to move, right-click a row for its menu (Split horizontally / Split vertically open a shell beside the agent, as Terminator does; the shell shows with its agent and steps aside while another agent is shown). A right-click anywhere else in the column opens the deck's own menu: new agent, new Control Tower, new agent on another provider, new shell, new folder, sounds, theme, keys, detach; a click on a folder folds or unfolds it; ctrl + right-click makes a folder, holding the agent under the pointer. The pointer over a row shows its whole name (cut in the row when long) with the agent's name, role, profile and state in the bottom border.
- States. A red
●needs you (a permission, or a blocker the agent named withtask_update, until you answer: lea clears the blocker when you type to the agent or when a message from you, its lead or lea reaches it, and the dot turns back to the spinner), an orange spinner is working or waiting (its subagents, or a next step it named: CI, a review, a reply), a green●has finished with nothing pending, an empty○has been quiet for 30 minutes, a grey‖is paused (p: lea freezes the agent's processes, tool calls included, until you resume it), a lavender◷stopped on its usage limit (see below). Agents stay in the order you started them. - Usage limits. When a Claude Code agent stops on its provider's usage limit, the row shows
◷andusage limit, resumes 15:02: lea resumes the agent at that time, the limit's reset (from the status line's 5-hour and 7-day windows) plusLEA_RESUME_DELAYseconds (60) and a few seconds of jitter, or after a backoff (5 minutes, doubling, at most an hour) when no reset time is known. Resuming wakes the agent with one fixed line of lea's ("the usage limit … should have reset. Continue your task"); lea never types into its terminal. After 6 resumes without progress, or withLEA_AUTO_RESUME=0, the row saysusage limit, resume itand the agent waits for you. A pending resume surviveslea stopand the next container: the agent comes back with--resumeand lea resumes it at the same time (at least a minute after the restart; given up past 8 days). Codex agents are not detected yet: Codex gives no structured signal for its limit (its failed turn runs no hook, and the error is not kept in its session file). - Messages. Typing into an agent's pane (
enter) talks to it now, in its conversation.m(Send message) instead leaves it a note in its inbox, as another agent would: it reads it on its next turn, or is woken for it once its turn is over.t(Messages) shows everything the agent sent and received: your notes, its reports to you, and its messages with other agents, questions (ask) included; an answer names the message it answers (result to #12). Highlighted in a row's menu, each says what it does. No agent but a Control Tower asks you a question (itsuser_ask, see Control tower): the others write to you withmsg_send, and you answer withm. - Folders. Folders come first, in your order, then the agents in no folder. A folder's
header sums up its agents, folded or not: how many it holds, then how many need you (red,
bold), work, wait on their usage limit and are done (
2 ● 1 ✓ 1;!,+,~and=in ASCII). Its agents are indented under it, and a blank line sets each folder apart. A folder's colour (c) tints its arrow and its name, never its agents or its summary. An agent a lead starts joins the lead's folder, also when it starts while no deck is attached; once you move it, it stays where you put it. The layout is yours: the deck keeps it on the host (~/.local/share/lea/host/deck/<container>.json), out of every container's reach. Each row shows the agent's context use, its directory and branch, and its own report on its task. The pane that has the keyboard is the bright one: the deck's frame turns blue when it has it; otherwise the terminal on the right shows a blue▶ <agent> · typing herebar on its top border (grey, with the keys that give it the keyboard, while the deck has it). - Scrolling. The wheel scrolls an agent's history; the bar then reads
history 251/256: type or q to go back, the line at the top of the view out of the history's lines, counting down as you scroll up. Any typed key (q,Escape,Enter, a letter…) goes back to the prompt; that key is not typed, the next ones are. - Sounds. lea plays a sound only when it needs you, while a deck shows the agent: a
permission dialog or an approval card waits, an
agent sends you a request (
msg_sendtouser, kindrequest, or aneeds_userreply), or an agent reports it is blocked on a human (task_updatewhoseblocked_onbecomes non-empty), or lea pauses an agent on its spend budget. A turn that simply ends rings nothing.lea sound on|offand the deck'sSswitch it at runtime;LEA_SOUND=0starts with it off;LEA_SOUND_ATTENTIONpicks the file, or mutes it with0. - Names. An agent you have not renamed is named after its first prompt, by a short
claude -prun on the host with a small model (LEA_AUTONAME_MODEL,haikuby default;LEA_AUTONAME=0in the environment turns it off), whenclaudeis on the host'sPATH; without it, agents keep their plain names. The prompt is not stored. An agent started with a brief (a lead'sagents_spawn) is named after its brief instead, unless the lead gave it alabel. A row shows the label, then the agent's name dimmed (lea#350 spawn reuse dev-4): the name is never cut, and the tower,lea boardandlea agentsname the agent the same way,label (name). Labels are unique among the running agents: a clash gets2,3…, and a rename to a running agent's label is refused.user,leaandControl Tower…are reserved: only the user gives them, never a lead'slabelnor the automatic name. - Copy and paste. Drag to select text in an agent's terminal: releasing the button copies it
and flashes "Copied". A program that takes the mouse (Claude Code in its fullscreen mode,
/tui fullscreen) selects and copies itself; in any other pane (Claude Code's default mode, Codex, a split shell, the scrolled-back history) lea selects. On Linux lea's copy bridge puts the copy on your clipboard (withwl-copyorxclip; without them, copying from lea reaches no clipboard). On macOS the bridge has nopbcopypath yet, so use your terminal's own selection, which bypasses the mouse (option+drag in iTerm2,fn+drag in Terminal.app;shift+drag elsewhere).ctrl+vpastes your clipboard's text into the pane that has the keyboard (the agent's input, a shell, the deck). lea reads your clipboard only when you pressctrl+v(withwl-paste,xcliporpbpaste); agents never read it. - Permissions. When an agent asks for a permission, its row shows the request and the deck
answers it (Claude Code agents: lea does not see Codex's dialogs, which stay in its pane).
Unanswered after
LEA_APPROVAL_TIMEOUTseconds (60), Claude asks in its own terminal as usual;LEA_APPROVALS=panekeeps Claude's dialog only.
lea web, from your projects directory, serves the deck in your browser while it runs
(ctrl+c stops it):
lea web # prints http://127.0.0.1:PORT/?token=…, a link that signs one browser in, once, within 2 minutes
lea web --open # also signs your browser in, without the link
lea web --port 8414The page shows this lea instance's agents as a tree, each lead with the agents it started, and for each
one its state, its own report on its task (status, next step, and in red what blocks it), its
branch, context use, cost, unread messages and whether it is paused or its inbox held. It updates
live, with no reload. Click an agent (or j/k, then enter) to read its messages and write
to it (m; ctrl+enter sends), rename it (e), pause it (p), hold its inbox (h), change its
role or stop it (x, confirmed). New agent (n) starts one on a provider, in a repository,
with a role, a label and a brief; N starts a Control Tower. Tower (t) opens the control
tower's chat: what you write there is a request to it, and its open and queued questions to you
show above it. A permission an agent asks for shows at the top of the page with Allow,
Deny and, when offered, Always (a, d, A answer the first one). While a browser
shows the page, permission prompts wait for it as they do for the deck in tmux; once it is
closed, the agent's own dialog asks at once, as without a deck. The page works at phone width,
in a light and a dark theme (it follows your system; the ◐ button switches it), and ? lists
its keys. See How lea keeps your machine safe for what
protects it.
The other decisions lea requests, lea approve, lea allow and lea egress take on the host
show on the page too:
- Spawn requests (
sN, an agent asks for another when no lead runs): Accept or Decline, aslea approve sN/lea deny sN. They have no durable form. - Grant requests (
gN, a lead asks for a grant for itself and its children): grouped in one card, each with the capability it maps to, Approve / Deny each or Approve all, aslea approve gN/lea deny gN. Under them, in three lines built from lea's capability table: the one-off answer, the onelea allowcommand that covers them all for every agent of the lea (andlea allow off Nto undo it), and what that command does not cover. Allow durably… opens the allowances screen with that command filled in. - The control tower's questions: its open question shows with a box to answer it, and the queue behind it. The tower gets your answer as your message, with lea's note that the question is answered (and to whom to relay it); the next question opens, as after a prompt in its terminal.
- Allowances (
g): what this lea instance's agents may do without asking, each with Revoke (lea allow off N), and a form to add one: capabilities or thedeliverpreset, repositories (empty: every one with a forge origin), branches, one agent, release tags, a duration. Preview reads each repository's origin on the host, aslea allowdoes, and flags a pin you have not recorded yet (agents can rewrite.git/config); Record records exactly the pins you saw. - Egress (
w): the hosts lea-proxy refused in the last 24 hours, who asked, and Allow for each; a host field with Allow and Deny, the same aslea egress allow|deny HOST, applied live. There is no one-off egress approval: an allowed host stays allowed until you deny it.
An agent's Terminal tab (v) shows its terminal live, as its pane in tmux shows it, colours
included: read-only, nothing you type there reaches it. The 🔔 button turns on browser
notifications: while the tab is in the background, each new permission (pN), spawn request (sN),
grant request (gN) and question from the control tower raises one, and the tab's title counts
what waits for you. Folders are the deck's own: a folder made, renamed, coloured, folded or
deleted in the browser (an agent's Folder menu, a folder's ⋯) shows in the deck within two
seconds, and the deck's in the browser.
From another machine (a laptop or a phone, lea on a server), forward lea web's port over SSH: the page stays on the server's loopback and SSH carries it.
ssh -L 8414:127.0.0.1:8414 server # on your laptop; then, on the server:
lea web --port 8414 # and open the printed link on the laptopWhere SSH will not do, lea web --listen ADDR:PORT listens on one address of the server, and
refuses to start without TLS and a lasting token:
lea web --listen 192.168.1.20:8443 --tls-self-signed # a certificate lea makes and keeps
lea web --listen 192.168.1.20:8443 --tls-cert c.pem --tls-key k.pem
lea web --listen 192.168.1.20:8443 --tls-self-signed --new-token # a new token: sign in againIt prints the certificate's SHA-256 fingerprint (check it in the browser before you sign in) and,
the first time, the token, which it keeps in ~/.local/share/lea/host/web/token (0600). The page
asks for the token; each browser that signs in gets its own session, for 7 days or until lea web
stops. Whoever has the token drives your agents and answers their permissions: keep it as you
would an SSH key, and prefer the tunnel.
The deck is optional. lea config deck off (or sh install.sh --no-deck [--tool CMD], or
answering no to the deck question of the first run or of lea init) makes lea run your own tool inside the lea container instead:
Claude Code by default, or any command (lea config tool codex, lea config tool aider --model x; a command and its arguments, never run through a shell). Arguments after lea go to it
(lea --resume). lea config deck on brings the deck back. Either switch applies at the next
lea, with the same container: nothing is rebuilt and running agents are not touched. An install
made before the deck was optional (no LEA_DECK in its user config) is asked once, at its next
lea on a terminal, and the answer is recorded.
What stays the same: the container and its confinement (proxy and egress allowlist, seccomp,
AppArmor, no host secrets), grants, lea's daemon and MCP server, and the Locks' sockets. The
docker run arguments are the deck's, to the byte. tmux is not needed (lea new still needs it,
for its agents' terminals).
- Your tool from an IDE or another terminal.
lea attachruns the tool in the container likeleadoes;lea attach --printprints thedocker execcommand that does it in the running container, as is, for a second terminal or an IDE's terminal (VS Code Dev Containers and JetBrains can also attach to the runninglea-<id>container). - lea's agents.
lea newand a lead's spawns still run under the daemon.lea board(--watch: again every 2 s) follows them, andlea attach AGENTjoins one agent's terminal (detach with abduco'sctrl+\). - What waits for you. A permission request of one of lea's agents, a spawn request routed to
you, a request or a blocked agent comes as a desktop notification (
notify-send, orosascripton macOS) instead of the deck's sound.lea requestslists the permissions (pN) and spawn requests (sN);lea approve pN [always],lea deny pN,lea approve sNandlea deny sN [reason]answer them. Unanswered afterLEA_APPROVAL_TIMEOUTseconds, the agent asks in its own terminal. Lock requests (locksql, lockmq, lockfile, locklog, lockssh, lockhttp) are not lea's:lox rundecides them, deck or not. - No notifications with
LEA_CTL=1. lea-ctl runs lea's daemon in a container, which has neithernotify-sendnorosascript: without the deck nothing shows when something waits for you. Checklea requests(orlea board --watch), orlea config ctl offto get the notifications back.lea doctorwarns in that configuration, and when the host has no notifier. - Off without the deck: the agent column, lea's sounds and the deck's keys.
lea doctor shows the mode, does not flag a missing tmux with LEA_DECK=0, and says whether
lea's notifications can show.
lea needs no forge account, and works with any of them.
-
HTTPS, by default.
git clone,pullandpushover HTTPS reach GitHub and GitLab through the proxy out of the box; another forge (Gitea, Codeberg, Bitbucket, a self-hosted one) needslea egress allow DOMAINonce (see the egress allowlist).ghandglabare in the image; what they keep lives in lea's state, never in your home directory. -
GitHub: the token stays in the proxy. Give lea a GitHub token on the host, once:
gh auth token | lea github login # or: lea github login < token-file lea github status # is there one (never shows it); lea github logout removes it
It is kept in
~/.local/share/lea/proxy/forge/github.com(mode 0600) and mounted in the proxy container only. The agents'gh(through a relay socket,/run/lea-forge/gh.sock) andgit(https://github.com/goes tohttp://lea-proxy:4401/) send their requests without it; the proxy's forge forwarder drops whatever credential they carry, adds the token forapi.github.com,uploads.github.comandgithub.com, and goes on over HTTPS through the egress proxy (or the LockHTTP gate).ghsends every request through the socket, the redirects it follows included: the forwarder sends each to its own host, with the token for those three only (a job log's or an artifact's redirect to*.blob.core.windows.netgoes there without it; that domain is not in lea's default allowlist:gh run view --logandgh run downloadneedLEA_EGRESS_ALLOW="default,blob.core.windows.net"). Onlylea-proxy:4401(git) meansgithub.com. An agent can use the token for what it allows, never read it, and only for the calls lea'sghandgitworkflows make: the forwarder keeps an allowlist and refuses (403) everything else. Onapi.github.com, among others: reads of the API root, the user, users,repos/{owner}/{repo}/…,orgs/{org}/…, search, rate limit, meta, notifications and a few static lists (emojis, licenses, gitignore templates…); writes underrepos/{owner}/{repo}/on issues, pull requests, labels, milestones, contents, git data (refs, blobs, trees, commits, tags), releases, check runs and suites, statuses, merge-upstream, and of Actions a run's rerun (failed jobs included), cancel, force-cancel or deletion, a job's rerun, and a workflow's dispatch, enabling or disabling; GraphQL queries, and only the mutations ofgh issue,gh prandgh project(issues, pull requests and their reviews, comments, labels, assignees, project items). Onuploads.github.com, a release asset; ongithub.com, git's protocol (and Git LFS, archives, raw files, release downloads). So no collaborator, invitation, transfer, repository or organisation setting, membership, key, webhook, Actions secret, variable or runner token, nor the ID aliases (/repositories/{id},/organizations/{id}) of any route; a path with an empty,.or..segment, an escaped slash or a;is refused too. Make those on the host. A GitHub token in the agents' state (/lea/state/gh/hosts.yml, or agithub.comline of git's store) is removed at eachlea. Any agent can write that state, so such a token never replaces the proxy's: it is discarded with a warning (lea github loginchanges lea's token). Only the firstleaof this version, when the proxy has no token yet, adopts the one an earlier lea left (the marker~/.local/share/lea/proxy/forge-migratedthen stops it, even afterlea github logout). Prefer a fine-grained token limited to the repositories of the projects directory, without administration or workflow permissions. -
Other forges. Log in from a shell in lea (
lea shell, orsin the deck):glab auth login, or a token in git's credential store. Those tokens stay readable by the agents (see What an agent can read). -
SSH, if you prefer. List the endpoints in
~/.config/lea/lea.conf, pin their host keys, and rerunlea init: it creates lea's own key and prints the public key to add to your forge.echo 'LEA_GIT_SSH="github.com:22 gitlab.com:22"' >> ~/.config/lea/lea.conf ssh-keyscan github.com gitlab.com >> ~/.config/lea/git_known_hosts # compare the fingerprints lea init
Each endpoint gets its own forwarder in the proxy; agents use lea's key, never yours.
-
Container registries.
podman login(ordocker login) in lea; the login is kept for the next sessions.
The image ships Go 1.26 with staticcheck and govulncheck, and agents run go, staticcheck
and govulncheck without a permission prompt. Go never downloads another toolchain
(GOTOOLCHAIN=local); its module and build caches, and what go install builds, live in lea's
state (/lea/state/go) and are kept for the next sessions. A permission rule never matches a
command that starts with GOOS=… GOARCH=…, so cross-compile with go-cross <GOOS> <GOARCH> …
instead, for example go-cross darwin arm64 vet ./....
lea comes with locksql: a console that stands
between your agents and your databases. The agents propose SQL; you approve each statement, and
the console alone holds the credentials. The console runs hub-attached only, under the Lock
Family's lox run (lockhub's docs/lox-run.md),
in a compose service of its own: lea starts no locksql console. Add a locksql lock to your projects
directory (lox add locksql NAME: with lea on your PATH, lox add puts your uid in the lock's
allowed_uids in .lockfamily/lockfamily.yaml, because lea's agents run as your uid, which has
no account in locksql's image); lox run applies it. lea's agents then reach that lock's socket volume (read-only, once docker
confirms it is lox run's, see below); without such a lock they get no locksql socket and lea says
"no such lock yet: lox add locksql". locksql is on for lea as soon as lox run runs a locksql
lock for the projects directory: lox add locksql is all there is to it
(LEA_LOCKSQL=0 in your configuration keeps it off; lea init --locksql or LEA_LOCKSQL=1
turns it on without a lock). A lock added while lea runs reaches the containers started afterwards
only (Docker cannot add a mount to a running container): the deck says "lock NAME added: restart
lea to use it (lea stop, then lea)", the agents' status lines say "+lock NAME: restart lea", and
the fix is lea stop, then lea: restarting an agent or the deck does not give a running
container the mount. lea locksql and lea doctor say which applies. With several locksql
locks, each reaches the agents on /run/locksql/<instance>; a Codex agent gets one MCP server
per lock (locksql-<instance>), and lea's MCP server tells a Claude agent, which calls the
client itself, "several locksql locks: orders stock; pass --instance NAME" (the lock names are
yours). The lock clients themselves also refuse a call that names no lock when several are
mounted: "several locksql locks: orders stock; pass --instance NAME (or set LOCKSQL_INSTANCE)".
lea init builds and installs no locksql (lox runs the lock's own image): with locksql on
(LEA_LOCKSQL=1 or lea init --locksql), on a terminal, when the projects directory declares no
locksql lock and has no database profile yet, it walks you through a first one with the locksql client of
lea's image (the release of config/locks.lock; engine, host, TLS, where the password comes from;
never the password). lox run reviews that profile (.locksql in your projects directory) and copies it into
the lock; the agents see .locksql read-only, even with LEA_LOCKSQL=0 or before lox add locksql: lea makes it, empty, when missing, so no agent creates it, and refuses a symbolic link
or a file in its place. For a profile that reads its login from Vault, lox run passes
VAULT_ADDR to the locks added with vault: true (lox add locksql). lea puts no locksql command on the host (it removes the link older releases
made).
Each query of an agent waits for lox run's decision, in its terminal outside lea: lea shows no
ticket and answers none. The decision reaches the agent as a new turn once its turn is over,
also for a query it ran through the shell (lea knows which agent waits on each pending ticket of
the hub). The deck's top border counts the container's requests that wait (locksql 2 wait for lox run). The console's own questions (its policy review on a first start or after a loosening,
a production profile's typed name, the credentials its profile does not take from Vault) are
lox run's too; lea shows no lock console and lea lock is gone.
The two projects are independent: lea runs without locksql, and locksql works with any agent.
Off (the default, lea init --no-locksql or LEA_LOCKSQL=0), lea leaves no trace of locksql
but the empty, read-only .locksql above.
lockmq (RabbitMQ) and
lockfile (files on S3, SFTP or a local directory)
keep a human between the agents and production the same way: the agents ask, a console that alone
holds the credentials shows each request and waits for your approval. Both are pre-releases, so
they are off by default, and on for lea as soon as lox run runs a lock of their type for
your projects directory (lox add lockmq or lox add lockfile; LEA_LOCKMQ=0 /
LEA_LOCKFILE=0 in your configuration keeps one off). lea init asks (no by default; a no
records nothing, so lox add still turns the tool on), or lea init --lockmq /
lea init --lockfile; lea init --no-lockmq / --no-lockfile record the opt-out.
Their console runs hub-attached only, in a container of its own that the Lock Family's lox run
starts for your projects directory (lox add lockmq <name> or lox add lockfile <name>, which
applies at once; lockhub's docs/lox-run.md): no host account, no sudo <tool> install. lea's agents run
as your uid, which has no account in the console's image: the console serves it
only when your uid is in the lock's allowed_uids (.lockfamily/lockfamily.yaml). lox add puts
it there when lea is on your PATH; lox run reviews it with you; without it the agents get no
console. Edit it by hand only for a lock added without lea on your PATH. No agent can.
lea installs nothing for them; their launchers update themselves (lockmq update,
lockfile update). lea init points to the launcher when it is missing, then runs lockmq's
profile wizard (lockmq profile add, never a password); for lockfile it names lockfile profile add --profile NAME --source ..., which writes the profile lox run reviews. A
LEA_LOCKFILE_REF (a development override of the client) below v0.1.1 is refused (a plugin
sandbox escape); the console's release is lox's choice.
lea never starts, sees or drives these consoles. Its containers get only the socket volume of
lox run's lock of the tool (.lockfamily/up.json) on /run/<tool> (each of several locks on
/run/<tool>/<instance>), read-only, and the tool's
clients group (lockmq-clients 10010, lockfile-clients 10030): lea's image names the console
accounts with the ids of the tools' images, so the client checks that the socket is the console's.
The agents reach the socket and nothing else (no credential, no profile, no audit log). A tool
that is on without a lock of lox run in the projects directory gets no socket, with a warning
that says "no such lock yet: lox add <tool>": there is no fixed <tool>-run volume of a console started by the
tool's own launcher any more. lea lockmq / lea lockfile tell you whether the tool is on and how
its console runs. Restart lea (lea stop, then lea) after adding a lock or turning one on.
When an agent's Lock client finds no console (a console that waits at its terminal for its start
questions, after its idle session ended, has no socket yet), the agent asks lea (its lock_hint
tool) and reports what you must do, from what lea knows of the lock rather than a guess: "lock
NAME waits for you: answer in lox run (or lox attach NAME)" while lox run runs the lock, and
"start lox run in the projects directory" when no lox run serves; never a command that restarts
or recreates the lock. The agents' status line says "no lox run: start it in the projects
directory" while none serves.
locklog lets the agents read the logs (files,
journald, containers, Loki, Elasticsearch) without the people in them: its console masks every
record it gives an agent (e-mail addresses, IPs, tokens become pseudonyms), counts, patterns and
searches are free, and the clear value of a span (locklog_unmask) waits for your approval at
lox run. It is wired exactly as lockmq and lockfile: off by default, and on for lea as soon
as lox run runs a locklog lock for your projects directory (lox add locklog, which finds this
host's logs and writes the profile, .locklog/config.toml, that lox run reviews with its mount
plan); LEA_LOCKLOG=0 keeps it off, lea init --locklog / --no-locklog record the choice.
lea's containers get only the socket volume of lox run's lock on /run/locklog (each of
several on /run/locklog/<instance>, LEA_LOCKLOG_INSTANCES naming them), read-only, and the
clients group locklog-clients (10050; the console account is 10051, as in locklog's image): no
log, no key, no audit reaches them. They see .locklog read-only: it holds the profiles and the auto
rules lox run applies, so no agent widens what is decided without you (lea makes it when
missing, and refuses a symbolic link or a file in its place), with LEA_LOCKLOG=0 and before
lox add locklog too: no agent creates it to stage a profile. The client is lea's image's (config/locks.lock); Codex
agents get it as the locklog MCP server; lea locklog tells you whether it is on, and
lea doctor compares it with the lock lox run runs.
lockssh lets the agents run commands on your SSH
hosts without holding the key: its console, under lox run, holds the key and the host's
known_hosts in its own home, runs the commands of the profile's allow list, and asks you, at
lox run, for anything else (a command outside the list waits on the hub, and nothing runs on
the host before you decide) and for the first connection of a session; the output it gives an
agent is masked (e-mail addresses, IPs, tokens become pseudonyms). It is wired as locklog:
off by default, and on for lea as soon as lox run runs a lockssh lock for your projects
directory (lox add lockssh, which asks for the host, its login and key, and the allowed
commands, and writes the profile, .lockssh/config.toml, that lox run reviews);
LEA_LOCKSSH=0 keeps it off, lea init --lockssh / --no-lockssh record the choice. lea's
containers get the socket volume of lox run's lock on /run/lockssh (each of several on
/run/lockssh/<instance>, LEA_LOCKSSH_INSTANCES naming them), read-only, the clients group
lockssh-clients (10040; the console account is 10041, as in lockssh's image), and the profile
directory .lockssh read-only, as locksql's .locksql: it holds the allow list and the auto
rules lox run applies, which no agent may widen (lea makes it when missing, and refuses a
symbolic link or a file in its place), with LEA_LOCKSSH=0 and before lox add lockssh too:
no agent creates it to stage a profile. No key, no known_hosts, no audit reaches them.
The client is lea's image's (config/locks.lock); Codex agents get it as the lockssh MCP
server; lea lockssh tells you whether it is on, and lea doctor compares it with the lock
lox run runs.
LockHTTP puts a human between the agents and the
web: every outbound HTTP(S) request of an agent goes through a LockHTTP gate beside lea's proxy,
which lets through what its policy trusts and asks you, on the Lock Family hub (lox run, outside lea, or
a paired phone), about the rest.
It is off by default (LEA_LOCKHTTP=0): lea then behaves as before.
LockHTTP runs in Docker only (docs/docker.md in the lockhttp repository). To turn it on,
install lockhttp's launcher with the Lock Family (brew install davidgodefroid/tap/lockfamily,
or lockfamily's install.sh; brew upgrade updates it, and lea doctor warns about one older
than the release lea pins in config/locks.lock). The launcher pins its release image by digest, and lea runs
that image as the gate. lea looks for the launcher in /usr/local/bin, then ~/.local/bin, then
brew's bin ($HOMEBREW_PREFIX, else /opt/homebrew or /home/linuxbrew/.linuxbrew), and
uses the first it finds. A launcher owned and writable by root only in /usr/local/bin is
trusted as it is. Anything else may be rewritten by your own account, so lea does not trust the
digest written in it: it runs it only when it is the image config/locks.lock pins for that
release (checked with cosign when lea pinned it), or when cosign verify proves it is the image
lockhttp's release workflow signed at the launcher's launcher_version tag. That check needs
cosign on the PATH (the lockfamily formula installs it) and the registry on each start. A
launcher whose digest does not verify, or one of a clone (launcher_version=dev, the local image)
outside /usr/local/bin, is refused, and so is the start. Then add a lockhttp lock to your
projects directory (lox add lockhttp <name>, which applies at once and starts the hub and the lockhttp
console; its policy in .lockhttp/config.toml, which lockhttp profile add --trusted HOSTS
writes: list the hosts of your egress allowlist one by one, as hosts or .domain for a domain
and its subdomains; default, * and commas are not accepted). Then set
LEA_LOCKHTTP=1 in ~/.config/lea/lea.conf and restart lea (lea stop --all, then lea);
lea doctor checks each step (its lockhttp line says off, or on with the gate's state).
LEA_LOCKHTTP=1 lea is not enough: the configuration wins, and lea warns that the environment's
value is ignored. lea-proxy and its gate are shared by every lea on the machine, so LockHTTP is
on or off for all of them at once, and once it is on, a lea whose projects directory has no
lockhttp lock does not start. The gate runs hub-attached only: without a trusted
.lockfamily/up.json naming a lockhttp lock, lea does not start (it says to run lox run). Nothing else on the host: no account, group or socket directory.
With it on, squid listens on the proxy's loopback only, behind the gate (its floor stays: DoH
resolvers, IP literals and private ranges are refused; the allowlist is the gate's policy now).
lea runs the gate as a container of its own, lea-lockhttp-gate, in the proxy's network
namespace, from the image the launcher pins (never a tag), as the image's gate account (never
root), without capabilities, on a read-only root; it is the only container with the console's
socket volume (lox run's <project>_<name>-run): no agent container gets it. Its audit stays in the volume
lea-lockhttp-audit, its status (for the deck) in ~/.local/share/lea/lockhttp/status/. A proxy
started again gets a new gate. The gate names the calling container from the network the
request arrives on, which no agent can forge: the container is the trust boundary. Each
agent also has its own proxy password, and the daemon tells the gate whose it is
(sources.json, under ~/.local/share/lea/lockhttp/), but the agents of one container share a
uid and can read each other's environment: that name is for the audit and the console's display
(attribution), never a permission, and one agent can pass for another of the same container.
lea-keyproxy goes through the gate too, and so do the forge calls of grants, with the calling
agent's own password. The daemon also tells the gate which Claude login each container holds
(credentials.json: hashes of the OAuth access token in its state, and of the keys lea-keyproxy
injects); under MITM the gate denies a Claude API key that is not the caller's (E_SECRET_EGRESS).
That login file is the agent's to write: the check stops a key sent from the wrong container,
not an agent that rewrites its own login file. LEA_GIT_SSH and LEA_OTEL_UPSTREAM are refused (their raw TCP forwarders
would bypass the gate: use git over HTTPS), and claude.ai's connectors are turned off in the
agents' Claude Code (WebSearch and WebFetch stay).
The hub (lockhub's docs/lox-run.md): lox run runs a lockhttp lock for the projects
directory (its .lockfamily/up.json), and the gate asks the Lock Family hub about every held
request. It mounts that lock's socket volume and gate volume (--home), and reads
lea's read-only copies (in /run/lockfamily) of the hub's key; of the host facades' keys, for a
lock lox run lets reveal (reveal: true: --facade-keys-file, so that a reveal, is
sealed only to them); and of the paired phones, for a lock that pins them (devices: true:
/run/lockfamily/devices.json, with --require-device and --seal-clear as hub.mobile says;
without it, a phone's decision is refused). Only the proxy joins the hub's network, whose
addresses the gate refuses as targets: no agent reaches the hub. lea checks first the volumes' and
the network's labels, the key, and the facade keys and devices as the gate reads them (lockkit's
parsers; it writes them in canonical form); anything it cannot trust stops lea, which says why and
to run lox run; so does an up.json that does not say what the gate pins (lockhttp_gate 1: a
lock's devices, required and sealed, its reveals), and a lock whose required or sealed devices lea
cannot pass. The pinned lockhttp release decides too: the hub needs v0.3.0 (an older one stops
lea), the devices v0.4.0, the facade keys v0.5.0; lea passes no flag that release lacks, and says
so. One
lockhttp lock at a time: the gate serves every projects directory, and asks the hub of the one
whose lea started it last; lea refuses to switch it to another hub while agents of another
projects directory run.
LEA_LOCKHTTP_MITM=1 (with LEA_LOCKHTTP=1) lets the gate decrypt HTTPS, but for the policy's
splice hosts, so that it decides on methods, paths and bodies. lea makes a local CA on first use
with lockhttp ca init in the gate's verified image (90 days, in ~/.local/share/lea/lockhttp/ca/; lea doctor fails once fewer than 7 days are left: lockhttp ca init --force --dir <it>, then lea stop --all
and lea). Its key goes to one container only, lea-lockhttp-signer (the image's signer
account, no network), through the volume lea-lockhttp-ca (key owned by signer, 0600); the
signer hands leaf certificates to the gate on a socket in the volume lea-lockhttp-signer. The
certificate, never the key, goes to the gate, to lea-keyproxy and into the agents' trust stores
(system store, NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE, PIP_CERT, SSL_CERT_FILE).
Every agent has a role: lead, dev (the default) or reviewer. The first agent is a lead: a
Control Tower (see below).
Only you change a role (r in the deck, lea role <agent> <role>, lea new -r reviewer).
Agents get lea's tools through MCP:
- a lead starts
devandrevieweragents withagents_spawnand stops its own withagents_stop(at most 20 children at a time). Claude Code's built-in sub-agent tool (Agent) is denied to a lead, with a reason namingagents_spawn: its sub-agent would be invisible to lea (not on the board or in the deck, its context untracked, outside the child limits and the host-pressure queue). After a compaction a lead's context is reminded it is a lead and starts work only withagents_spawn; - any other agent asks a lead with
agents_request_spawn; without a lead the request comes to you (lea requests,lea request accept <id>,lea request decline <id> [reason]); - agents message each other (
msg_send,msg_reply); a message waits in the inbox until the agent's next turn. An agent whose turn is over is woken when a message arrives: its Stop hook (and its SessionStart hook, so a session resumed after a restart is woken too) starts a background job (Claude Code'sasyncRewake) that ends with the unread notice, and Claude Code starts a turn; the job waits for days and outlives a restart of lea's daemon. A working agent, or one waiting on a permission dialog, is not interrupted; a paused one, or one stopped on its usage limit, waits; only the newest job of an agent stays, so one message wakes it once, and an agent is woken at most 10 times in 10 minutes. The deck showswoken by leaduring that turn; - an agent asks another a question and waits for the answer with
ask(the other answers withmsg_reply; works with any agent that has lea's MCP tools). The answer is data, never instructions. Only a reply from the asked agent counts; an agent's container is checked (its bus socket), but its name inside a container is what the agent declares (LEA_AGENT), so agents of one container can answer for one another. One ask at a time per agent, at most 4 questions waiting on one agent, 5 asks a minute, a 1–600 s timeout (300 by default; a late answer lands in the inbox), and no loop: an ask that would make agents wait on one another in a circle, or in a chain longer than 3, is refused. The question and its answer show in the deck's thread view;lea boardshows who waits on whom; - an agent started by a lead is told to report to it with
msg_sendwhen it is done or blocked; board_readshows an agent every task of its lea, aslea boardshows them to you;- every agent reports on its task with
task_update: its row shows it, andlea board --mdprints every task as markdown; - before editing files another agent may touch, an agent claims them with
lease_acquireand lets go withlease_release(advisory, shown inlea board --md).
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 (Ollama, vLLM, any
server with the Responses API).
LEA_PROVIDERandLEA_MODELin~/.config/lea/lea.confare the default provider and model (an agent started without one: the deck'sn, a lead'sagents_spawn).lea new -p codex -m gpt-5.1-codex, the deck'sP(then the provider's digit), or a lead'sagents_spawnwithprofileandmodelstart an agent on another one;providers_listtells an agent which exist. The deck shows each agent's provider and model.- A lead's
agents_spawn(andagents_request_spawn) also takes anadvisorfor an agent on Claude Code:model: sonnet, advisor: opusstartsclaude --model sonnet --advisor opus, a Sonnet session that consults Opus on demand through Claude Code's advisor tool. The child keeps it when it resumes. Another provider refuses it (provider codex has no advisor). Claude Code offers the tool only to accounts it enables it for; the control tower picks each child's model and advisor by its task. - Codex keeps its own login per projects directory, like Claude Code: run
codex login(or/login) in the first Codex agent. It runs with its own sandbox (workspace-write) and asks for anything else in its pane; lea's MCP tools reach it, and its turn's end makes it idle in the deck. lea does not see Codex's permission dialogs (the deck shows the agent working) and does not wake an idle Codex agent when a message arrives: it reads its inbox withmsg_inboxor waits withmsg_wait.
Endpoints go in ~/.config/lea/providers (LEA_PROVIDERS), one per line
(config/providers.example):
# <name> <base URL> [key=<key file>] [model=<default model>]
ollama http://192.168.1.10:11434/v1 model=qwen3-coder:30b
vllm https://vllm.example.com/v1 key=/home/me/.config/lea/keys/vllm
- An endpoint's API key never reaches the agents. The file names a key file, not a key: it must
be yours, at a clean absolute path without a comma, with no group or other permission bits
(
chmod 600, or400), a regular file with a single hard link, and outside every directory lea mounts into the agents' container (the projects directory, lea's data,~/.claude,~/.codex; real paths are compared). Do not keep it in a Docker volume lea mounts there either, such as the nested engine's storage (<prefix>-podman-<id>, under Docker's own data directory): every agent reads it, and lea does not check Docker's data directory. lea mounts it into the proxy container only, wherelea-keyproxyadds it to the agents' requests; an agent reaches the endpoint athttp://lea-proxy:4400/<name>and sees neither the key nor the upstream. The key is read at each request: to rotate it, rewrite the file in place (cat new-key > file); a file replaced by a new one (mv, most editors) is seen once the proxy restarts, which the nextleadoes. Every agent of every lea container can use a configured endpoint (none can read its key); the proxy's egress network (your host, other containers there) cannot. lea-keyproxysends every request through the proxy's own egress rules: an endpoint on your network (an Ollama on your LAN, or on this machine at its Docker bridge address) must be listed inLEA_INTERNAL_HOSTSwith its port, as any internal host; nothing is open by default, and private, loopback,localhostand link-local addresses are refused unless that file lists them with the port. A key goes over HTTPS only, except to a host you listed there. A public endpoint's domain must be in the egress allowlist too (LEA_EGRESS_ALLOW:default,<its domain>). The forwarder answers the agents' networks only, never the proxy's egress network (your host, other containers there).- Codex needs the endpoint to serve the Responses API (
/v1/responses): Ollama 0.13.3 or later, a recent vLLM. - A change of the providers file restarts the proxy at the next
lea.
This section is about Claude Code agents. Each projects directory's container has its own writable copy of your ~/.claude/settings.json
and ~/.claude/plugins, made from yours on the host when it first starts. Inside lea,
/plugin install, /plugin marketplace add and the marketplaces' auto-update work as on the
host, on that copy, for every agent of that projects directory. Permission rules are the exception:
they come from your host's settings.json only (below).
-
Kept across restarts. The copy lives in lea's data (
state/claude/<id>/);lea stopand the nextleakeep what the agents installed or allowed. -
It follows your host while it is untouched. When you change your host's settings or install a plugin on the host, the next start takes it into a copy the agents did not change. When both changed, lea keeps the copy and says so once; to take the host's, remove the copy (the path lea prints) and restart lea.
-
Nothing is ever written back to your host. The host's
settings.jsonandpluginsare not mounted at all; lea reads them on the host to make the copy, and never copies your plugins' own data (plugins/data). To use a plugin you tried in lea on the host, install it there yourself (claude plugin install <plugin>@<marketplace>): lea has no path from an agent to your host's configuration, so a prompt-injected agent cannot plant a hook or a plugin that would run the next time you startclaudeoutside lea. -
lea's guards cannot be undone from there. lea's hooks (the shell guard and its hard denies, your grants, the approvals in the deck) are in Claude Code's managed settings,
/etc/claude-code/managed-settings.json, root's in the image: Claude Code ranks them above the agents' settings and runs their hooks even when those setdisableAllHooks. An agent that deletes lea's hooks or allows every command in its copy is still guarded. The same hooks also come in through--settings(an organisation's server-managed settings replace the file-based ones); Claude Code runs each once.lea doctorchecks the managed settings in the image and in every running container, and that Claude Code is the version lea's CI verified them with. -
Permission rules come from your host only. The managed settings make their own rules the only ones Claude Code honours (
allowManagedPermissionRulesOnly), disable bypass mode (disableBypassPermissionsMode): an agent that writesallowrules into its copy or into a project's.claude/settings*.jsongains nothing. lea sets no default mode of its own (#333): the agents start in the mode Claude Code starts in on your host (its own default, auto on the accounts that have it), or in yours when yoursettings.jsonsets one. AdefaultModean agent writes into its copy can change its own mode, never to bypass. At each start the container's root adds your host's ownpermissions(allow,ask,deny,additionalDirectories, anddefaultModeunless it isbypassPermissions) to lea's, read from your host's~/.claude/settings.jsonby lea on the host and mounted read-only, never from the copy. So a rule you add with/permissionsinside lea, or the deck's "always", is not kept: add it withlea config claude(below) or to your host'ssettings.json, then restart lea (lea stop --all, thenlea). -
Your base settings for lea:
lea config claude(#334). Without editing a file, and without touching your own Claude Code outside lea:lea config claude # every effective setting, with its source lea config claude defaultMode auto # default, acceptEdits, plan, dontAsk or auto lea config claude defaultMode --unset # back to your settings.json's, else Claude Code's lea config claude allow add 'Bash(make *)' # allow, ask, deny, additionalDirectories lea config claude allow remove 'Bash(go *)' # lea's built-in rules and your host's can go too lea config claude env MY_TOOL_HOME /opt/tool lea config claude model opus # also language, outputStyle, alwaysThinkingEnabled
They are kept in
claude.jsonnext to yourlea.conf(never in~/.claude/settings.json), outrank your host'spermissions, which outrank lea's image, and apply to the containers started from then on (lea stop --all, thenlea).lea doctorlists them;lea config exportnever carries them (--include-personalneither). lea keeps what keeps it working and its guards effective, and refuses it with the reason: its hooks,allowManagedPermissionRulesOnly,disableBypassPermissionsMode(so nobypassPermissions:dontAskorautodrop the prompts and keep the guards), the status line and its own variables (LEA_*,OTEL_*,SSH_AUTH_SOCK,GH_CONFIG_DIR,GLAB_CONFIG_DIR, the proxy's, telemetry and update switches). The command runs on the host only, and the agents' guard denies editing lea's configuration. -
The guard fails closed. lea's PreToolUse hook denies a call it cannot check: lea missing, a crash or a timeout (
onFailure: "block"), a bus that does not answer, a Claude Code without a lea agent identity (LEA_AGENT: run Claude in lea as an agent, from the deck orlea-agent run). The variables the hooks read that lea sets alike in every container (LEA_BUS_SOCK,SSH_AUTH_SOCK,GH_CONFIG_DIR,GLAB_CONFIG_DIR) are pinned in the managed settings and the--settingsfile, above an agent's ownenv.
The worst a compromised agent can do is change its own container's copy, which it could already
do by running code in its container: there is no persistence on your host, and no wider
permission. The agents of one container share one user, so they are one trust domain: an agent
that names another agent of its container in LEA_AGENT is still guarded by the same hard denies
and the container's grants.
Every agent of a projects directory shares its copy of your plugins and MCP servers, so a lead's
child loads the skill listing of every plugin and the tool listing of every server you have, even
those that have nothing to do with its repository, and re-reads them on each of its turns. Two
keys of ~/.config/lea/lea.conf leave them out of the children (dev and reviewer agents a lead
spawns):
LEA_CHILD_PLUGINS='my-plugin,other-plugin@my-marketplace' # plugins: a name (every marketplace) or name@marketplace
LEA_CHILD_MCP='claude.ai Gmail,my-server' # MCP servers, by the name /mcp lists- Children only. Leads (a control tower) and the sessions you start yourself keep everything. Empty keys (the default) change nothing.
- Read at each spawn. The daemon reads the keys when a lead's child starts: an edit applies to the next child without a restart, and a running child keeps what it started with.
- Your copy is untouched. A child gets lea's
--settingswith those plugins disabled (enabledPlugins) and those servers denied (deniedMcpServers); the container'ssettings.jsonandpluginsstay as they are for every other agent. - lea's own are kept. lea's plugin and MCP server, and the Locks' clients (
locksql,lockmq,lockfile,locklog,locksshand their instances), are never left out, whatever the keys say.
lea draws the agents' status line itself (lea statusline: model, context and 5-hour/7-day
usage), since it reports each agent's context use to the deck and feeds limit auto-resume. When
your ~/.claude/settings.json has a statusLine command, lea runs it after its report and shows
its output instead (#374):
- Your command gets the same JSON on stdin as on your host, and runs inside the container, in
the agent's directory: no host-only tool or path. A script below
~/.claudethat the command names (~/.claude/statusline.sh,bash ~/.claude/bin/line.py...) is mounted read-only, when it is a real file (no symbolic link on its path) and executable or named as a script. Nothing outside~/.claudeis mounted: such a command fails and lea's own line shows. - When the command exits non-zero, prints nothing or takes more than 1.5 s (it is killed, with what it started), lea prints its own line. The context report is sent whatever it does.
- The command is read from the container's copy of your settings, at every refresh; the script
is mounted when lea starts, as your host's
settings.jsonnames it (never as an agent's copy does, so an agent cannot get another host file mounted), and never one of Claude Code's own state directories (projects,shell-snapshots,todos...). After adding one, restart lea (lea stop, thenlea). Remove thestatusLineentry to get lea's line back.
lea brings its own Claude Code plugin, lea, loaded in every Claude Code agent (from the image, for the
session only: nothing is installed in your ~/.claude). Its skill /lea:control-tower turns a
lead into your control tower: you talk to it only, it splits your requests into tasks, starts
dev and reviewer agents with self-contained briefs, answers their questions when it can, and
follows them with board_read, and briefs you in one line per agent. Between your requests an
agent's report wakes it, as it wakes every agent whose turn is over:
fix-login · done · PR #42, 18 tests pass
dark-mode · blocked · which palette: Catppuccin or Nord?
Needs you: palette for dark-mode
Ask it for the board, the detail of an agent, or to stop one, in your own words.
It replies in the language of your latest message, and switches as soon as you do; its agents' messages, mostly in English, never change it. In tower mode lea reminds it on every prompt.
It asks you one question at a time, whatever the number of agents with a question for you: its
user_ask tool opens a question when none is open and queues the others (an incident first,
then what blocks an agent, then the rest, in order); the agents keep working meanwhile. Your next
prompt, or your answer to its AskUserQuestion, answers the open question, and the tower relays the answer to the agent it came from, then
asks the next one. While you have a question, lea denies the tower a second AskUserQuestion. A
question left unanswered LEA_QUESTION_REMIND minutes (120) is asked once more, prefixed with
reminder:. The deck shows the tower as ❓ 1 · 3 queued; lea questions lists the questions,
lea questions drop ID drops a queued one; in the deck, Q (or the tower's right-click menu,
Questions…) lists them and drops a queued one. The tower's status line shows the same count.
To answer in peace, pause the tower's inbox: H in the deck (or Hold messages in its menu), or
lea hold (lea hold --off releases it). The messages its agents send it wait, and the row
shows ⏸ N; your own notes and the replies to what the tower sends during the pause still
arrive, and an agent's ask to it fails at once (the agent sends instead and keeps working).
On release the tower gets them all and briefs you once. lea releases a pause on its own after
LEA_HOLD_MAX minutes (30; 0: never). Only you can pause or release an inbox, never an agent.
When lea opens the deck on a container with no agent running (the very first launch, or every
agent ended), the agent it starts is a Control Tower: a lead on Claude, labelled
Control Tower, whose first prompt runs /lea:control-tower (lea deck-open --no-default
starts nothing). In the deck, N starts another one (Control Tower 2…). A Control Tower
always runs on the claude provider, whatever the default one, since the skill and its hook ship
in the Claude plugin. Only you start one: agents cannot.
The tower never does the work itself, not even a git push: every request goes to an agent. The
plugin enforces it with a hook: once /lea:control-tower runs, the session may only use lea's
team tools (agents_spawn, agents_list, agents_stop, agents_request_spawn, msg_send,
msg_reply, msg_inbox, msg_wait, board_read, task_update, grants_list,
grants_request), ask you questions (user_ask, AskUserQuestion), use ToolSearch and
TodoWrite, write and read back its own handoff file (see /lea:clear-ct below) and run
lea inbox --agent --wait; any other tool (ask included) (Bash, Edit, Read, git, gh, the web…) is denied with a
reminder to delegate. /lea:control-tower off gives the session its tools back. Tower mode
belongs to the agent and survives its resumes, in a new container too (lea after a stop, a
usage-limit resume): the guard is on from the first turn, without running the skill again. An
agent created later under the same name does not inherit it.
A tower runs for hours and its context keeps growing. Type /lea:clear-ct to clear it without
losing the board: the tower writes a short snapshot of what the board cannot give back (its
ledger, your open questions and decisions, the approvals you gave) to a private file outside any
repository (<agent>.handoff.md in the container's ~/.claude/lea-tower, which is lea's
per-projects-directory copy of ~/.claude, ~/.local/share/lea/state/claude/<id>/lea-tower on
the host; rewritten each time), then asks you to type /clear (Claude Code does not let a skill clear the
context itself). After the clear the session is still a tower, with no gap: the hook carries
tower mode over to the new session, and tells it to load /lea:control-tower, read the snapshot,
and rebuild its ledger from agents_list and board_read (its children are the agents whose
parent it is); your next message, or a child's report, gets one line per agent. Its children
keep running, none is respawned, and what they send during the clear reaches the new session. A
plain /clear (or a compaction) in a tower comes back the same way, from the board alone. The
tower suggests /lea:clear-ct once its context passes 50%. Outside a tower, /lea:clear-ct
refuses in one line and changes nothing.
Type /lea:check (or ask for a status, a "point", a "topo") for the state of the work in
progress, in at most 10 lines: done since the last check, in progress, left, and what is blocked
or yours to decide. A tower builds it from the board and the agents' reports, without doing any
work; any other agent from its own task. Nothing new since the last check: one line.
✅ Done
dev-1: login fix merged, CI green
🔄 In progress
dev-2: dark mode, tests being written
⚠️ Blocked / to decide
dev-2: palette, Catppuccin or Nord?
Claude Code judges each action from its own conversation: "you may merge" told to a lead does
not reach its children, and relayed in a lea message it is rightly distrusted. An allowance
is that decision recorded by you on the host, with lea allow, and applied the same way to every
agent it covers. lox run approves what agents do with your data through Locks; lea allow says
which forge actions they take without asking.
To let every agent of a lea push its own branch, open its pull request (GitHub) or merge request (GitLab) and merge it without a prompt, on the host, in the projects directory:
lea allow deliver: lea reads each repository'soriginand lists the forge repository each one is pinned to (github.com/OWNER/NAMEorgitlab:HOST/GROUP/…/NAME).- Check them and answer
y(off a terminal, run it again with the--yes DIGESTit printed). It says what it recorded:allowance #1: agents of lea-myproj may push their branch, open PRs, merge PRs and delete their branch on api (github.com/me/api), web (gitlab:git.example.com/g/web), until lea allow off 1. lea allow(orgin the deck) shows what agents may do, the time left and the last uses;lea allow off 1(orxin the deck's Allowed screen) stops it.
lea allow # this lea's allowances, one line each, and the last 10 uses
lea allow log # the last 200 recorded uses: agent, capability, target, when
lea allow deliver # push pr merge delete-branch, on every forge repository here
lea allow deliver --gitlab git.example.com # also a self-hosted GitLab (gitlab.com is known; a host once pinned stays known)
lea allow merge issues --repo api --repo web
lea allow push --branch 'feat/*' --agent dev-1 --for 2h
lea allow stop-finished
lea allow release --repo api --tag 'v0.15.*' # gh release create v0.15.N --verify-tag [--notes-file F|--generate-notes]
lea allow off 12 # allowance #12; or a capability (lea allow off merge), deliver, or nothing: everything of this lea| capability | covers |
|---|---|
push |
git commit -m M (no --amend), git push [-u] origin <own branch> |
pr |
gh pr create --head <own branch> --title T (--body B | --body-file F) [--base B] [--draft], glab mr create --source-branch <own branch> --title T [--description D] [--target-branch B] [--draft] [--remove-source-branch] [--yes] |
merge |
gh pr merge <n>|<own branch> [--squash|--merge|--rebase] [--delete-branch] (or -s, -m, -r, -d), glab mr merge <n>|<own branch> [--squash] [--remove-source-branch] [--yes] |
delete-branch |
git push origin --delete <own branch> |
issues |
gh issue close|reopen|comment N |
stop-finished |
agents_stop on an idle or ended child |
release-tag |
git push origin refs/tags/vX.Y.Z (a new semver tag on a commit of the default branch, see below) |
release |
gh release create <tag> --verify-tag [--title T] [--notes-file F | --generate-notes] [--prerelease] [--latest], for tags --tag GLOB matches (see below) |
A lead may also push its team's branches (#406). It can push branch B when B is the recorded
branch of one of its own direct children, that child is idle, done or stopped, no other live
agent of the lea works on B, and B is not the default branch. The lead runs git push [-u] origin B from that child's worktree root (.lea/worktrees/<repo>/<child>). The child's push
allowance has to cover it: same repository, --branch glob and --agent. lea pins the push
exactly as it pins the child's own. A lead still cannot commit, delete, merge or open a PR for a
child's branch, cannot push another lead's child's branch, and cannot push tags (release-tag
covers tags). When a lead is refused a push, the refusal lists the branches it may push and the
worktree to run each from.
deliver is push pr merge delete-branch. The container is always this projects directory's lea
(LEA_PROJECTS_DIR=~/other lea allow … for another one). Every capability but stop-finished is
pinned to each repository's origin, read from its .git/config (as a file: no git runs on the
host) at that moment, on github.com, gitlab.com or a --gitlab host: every repository here with
such an origin, or the ones --repo names (repeatable; one without a forge origin is an error).
--branch (a glob on the agent's branch, never the default branch) and --agent NAME (that
agent and its children) narrow it. An allowance holds until lea allow off, or for --for
(1m to 30 days); every line of lea allow says which. A company policy
(managed.toml) can cap that time (lea.grant_ttl_max) or suspend
the allowances that hold until revoked (lea.standing_grants = false).
Agents can write a repository's .git/config (or add a repository): lea records nothing while a
pin is new or differs from the last one recorded for that repository in this lea instance (revoked ones
included). On a terminal it lists them and asks record these? [y/N], and reads the origins again
after your y: a pin that changed meanwhile records nothing. Off a terminal it lists them and
exits 1 with a digest; --yes DIGEST records exactly those pins. Once confirmed, the same command
applies without a question. Running lea allow deliver again (after adding a repository or
changing an origin) updates the same allowance when it holds until revoked and names the same
capabilities, --branch and --agent: rows of unchanged repositories keep their ids, and
repositories no longer here are dropped. With --for, or other caps, it records a new one.
lea doctor checks the allowances: each pinned repository's origin still matches its pin (an
origin rewritten since, or a forge repository no allowance covers, is a warning), and each forge
host has credentials (GitHub's in lea's proxy, lea github login; GitLab's in lea's state, glab auth login --hostname HOST; git's credential store alone covers pushes only, a warning); without
them it fails. It only reads.
lea delivery on|off|status and lea grant add|ls still work for this minor release: they are
translated to lea allow deliver, lea allow off deliver, lea allow and lea allow <capability>,
with a notice. lea grant add --github X is refused when X is not the repository's origin.
Whenever lea asks you to approve something, it gives both routes, in at most three lines (#412):
- One-off:
lea approve ID(orlea deny ID, with a reason forsNandgNonly:lea deny gN [reason]) answers that request only;lea requestssays what each waitingpN(permission),sN(spawn) orgN(a lead's grant request) asks. - Durable: the
lea allow …command that covers the same need for every agent of this lea instance, untillea allow off N(or for--for). Grant requests waiting together are grouped into one command: a lead'spr-create,release-create(tagv0.15.*) andclose-issueonlearead aslea allow pr issues release --repo lea --tag 'v0.15.*'. The action names a lead files map to the capabilities above:commit-identityispush,pr-createpr,delete-own-branchdelete-branch,close-issueissues,release-createrelease;mergeandrelease-tagkeep their names. - Not covered: what that command leaves out.
deliveris push, pr, merge and delete-branch only: it does not coverissues,release-tagorrelease.
g5 lead (lead in lea-myproj) asks for a pr-create grant on repo lea (gh github.com/me/lea) for itself and its children, 8h0m0s
g6 lead (lead in lea-myproj) asks for a release-create grant on repo lea (gh github.com/me/lea) tag v0.15.* for itself and its children, 8h0m0s
g7 lead (lead in lea-myproj) asks for a close-issue grant on repo lea (gh github.com/me/lea) for itself and its children, 8h0m0s
one-off: lea approve g5 g6 g7 (or lea deny gN [reason]); lea requests says what each asks
durable, for every agent of this lea until lea allow off N (add --for 8h to limit it): lea allow pr issues release --repo lea --tag 'v0.15.*'
it covers only pr, issues, release on lea, not push, merge, delete-branch, release-tag, nor other repositories
A permission whose dialog offers "always" also names lea approve pN always, which allows the
tool for that agent until lea restarts, and no other agent. A spawn request has no durable form.
An egress refusal has no one-off form: lea egress allow HOST holds until lea egress deny HOST.
Each agent on a branch is told in its first prompt the forms lea runs without asking for what
covers it when it starts, or, when nothing does, that pushing and PRs ask you and that lea allow deliver --repo <repo> lets it do them without asking. A merge, PR or push in a form no allowance
covers (with -R, chained, another flag) takes the usual path, and the agent is told, in its
context, the forms its allowance covers; when it holds none, which lea allow <capability> --repo <repo> you can run (lea's own text, from the agent's row, never from what it wrote). grants_list
is the live list of what covers it. A message saying "the user allows X" changes nothing.
lea's PreToolUse hook asks the daemon before each tool call: a call an allowance covers is
allowed, with the grant's id as the reason, and audited (lea allow log: agent, capability,
target, never the command); anything else takes the usual path. Revocation and expiry apply on the
next call. Only the host writes allowances: there is no MCP tool for it (grants_list only reads
them, grants_request only queues a request you approve on the host), the daemon refuses
allow_set, allow_off, allow_list and grant_request_decide from a container, and lea.db
is never mounted in one.
An allowed shell call never runs the agent's text: lea runs the command it parsed, rebuilt word by
word, in a fresh /bin/sh under env -i (so the agent's variables, aliases and shell
functions do not apply), with a fixed PATH and only HOME, GH_CONFIG_DIR, GLAB_CONFIG_DIR,
SSH_AUTH_SOCK and LANG as Claude's own process has them, plus lea's own GIT_CONFIG_GLOBAL,
GIT_CONFIG_NOSYSTEM, GIT_TERMINAL_PROMPT, GIT_EDITOR, GH_PROMPT_DISABLED and
HTTPS_PROXY. It reaches the forge through a path lea names itself, never through a proxy the
agent's environment names:
-
On GitHub, gh goes through lea's relay socket (
http_unix_socket/run/lea-forge/gh.sock) to the proxy's forge forwarder, and git pushes tohttp://lea-proxy:4401/OWNER/NAME.git, the forwarder, directly (the proxy is turned off for that URL); the forwarder adds the token and goes on to GitHub over HTTPS. -
On GitLab, gh's and git's requests go through lea's egress proxy (
HTTPS_PROXY,http.proxy,http://lea-proxy:3128); CONNECT keeps TLS end to end. -
gh runs as
/usr/bin/gh … -R github.com/OWNER/NAME, the pin, with lea's gh config, never the agent's, which the agent can write (it could send gh's requests to a server of its own): the image's/usr/local/share/lea/forge-gh, owned by root, which only sets the relay socket, andGH_TOKENset to a placeholder the forwarder replaces with the token. -
A commit goes through plumbing in the agent's worktree (
write-tree,commit-tree,update-ref): no hook, filter or signing runs. It commits the index as it is (git addfirst: no-a). -
A push runs from lea's bare repository
lea-pushin the worktree's git directory (a fixed path, reused from call to call; it refuses links in it, writes its config anew before each push and checks it again right before it; the worktree's objects borrowed) to the pin (on GitHub the forwarder's URL above, on GitLabhttps://…git) with the full ref (refs/heads/<branch>:refs/heads/<branch>): the remote's config never decides where it goes. -
git's hooks, fsmonitor, askpass and pager are off, ssh is
/usr/bin/ssh, https and ssh are the only transports,~/.gitconfigis not read; and lea refuses a repository whose own config holds aurl.*.insteadOf,include, URL-specific credential helper,pushurl, push refspec, mirror, filter, textconv or anyhttp.*key. Two keys pass:core.hooksPath(lea's git runs withcore.hooksPath=/dev/nullwhatever it says) andremote.origin.pushurlwhen it is the grant's own repository (https://github.com/OWNER/NAME, with or without.git; no pinned push reads it). Every worktree of a repository shares its.git/config, so they all get the same answer. A refusal names the keys it found, or says thatgit configitself failed, with git's message. -
gh pr create --body-file F:Fis a path relative to the agent's worktree that must resolve to a plain file inside it, outside.git(lea checks it is a plain file, opens it once and gh reads that open file; a quoted heredoc,--body "$(cat <<'EOF' … EOF)", is not covered: write the body to a file).gh pr mergechecks that the PR's head is the agent's branch before the merge, so--delete-branchdeletes that branch only. -
On GitLab lea does not run glab, whose config the agent can write (it could send glab's requests elsewhere): glab only reads the token of its config for HOST, from
/, and lea calls the project's API (https://HOST/api/v4) with curl (no.curlrc, https only, no redirect, no proxy variable), its answers read by jq, both with noHOMEof the agent's. A merge first reads the MR: it must be open and come from the agent's branch of the project itself, not a fork (by branch: the one open MR of that branch); the merge then names the head commit it checked, so GitLab refuses it if the branch moved in between (an MR whose pipeline is still running is set to merge once it passes, asglab mr mergedoes;--rebaseis not covered). Pushes go tohttps://HOST/PATH.gitwith glab's credential helper. A multi-line description is not covered (no file option): it takes the usual path.
A call is allowed only when it is exactly one plain
command lea parses (no ;, &&, |, $(…), backticks, redirections, VAR= prefixes,
--repo), run at the root of the agent's own worktree (<projects>/.lea/worktrees/<repo>/<agent>,
so gh and git act on its repo), whatever is allowed. A branch is an agent's own only while no other
live agent of the lea works on it. Some calls are denied outright, allowed or not: gh pr merge --admin, force-push (-f, --force*, +refspec, --mirror, --prune), any push to main or
master however its refspec spells it, a push to any branch but the agent's own (named: a bare
git push, HEAD or @ follows whatever is checked out), a refspec whose destination git would
infer (<src>:<branch> with neither side refs/heads/…: a tag's source makes refs/tags/<branch>),
a bare git push origin <branch> where the repository it runs in has no local branch of that name
or a tag of it (lea reads its refs; after a command that may change them, refs/heads/<branch>
only), a push of every branch or tag (--all,
--branches, --tags, --follow-tags, a wildcard or a bare :), other git transports (send-pack, http-push,
remote-<helper>, svn, p4), a push lea cannot read (an unknown option, a shell glob, a push run
through another program, or a git … push in the arguments of any program but grep, egrep,
fgrep, rg, ag, echo, printf, gh pr|issue, glab mr|issue), git run by xargs, parallel, find (or by another program without a subcommand), a git
program, subcommand or push argument computed by the shell ($…, backticks; a substitution's own
command is checked too), a program computed by the shell or run by env/sudo/… from a computed
word, submodule foreach, bisect run, filter-branch, git options that run a
program (--upload-pack, --receive-pack, --exec, --extcmd, -O, rebase -x), git options
before the subcommand other than -C, -c user.name|user.email|color.ui|core.quotepath and display
options, setting GIT_* (but GIT_EDITOR/GIT_SEQUENCE_EDITOR=true|:, GIT_PAGER=cat,
GIT_TERMINAL_PROMPT=0), HOME or XDG_CONFIG_HOME, deleting a branch that is not the agent's own, repointing git or gh (git remote set-url|add|…, writes with git config, gh repo set-default, GH_REPO=/GH_HOST=), and
writing a file that makes a later command run something else: Claude's settings, hooks and shell
snapshots, git's config and hooks (.git/config, .git/hooks/, ~/.gitconfig), the shell's
startup files (~/.bashrc…), /usr/local/share/lea or /lea/state. A command that hides
words behind escapes or expansions (\, $…, backticks) and touches any of these is denied
too: run it plainly.
Branch protection on the forge (required reviews, required checks) stays the control that decides whether a merge goes through: an allowance only removes the prompt.
Approving a merge for your team. You usually say it to a lead, in its chat ("your team may
merge on api"). The lead turns those words into a grant request (grants_request): it records
nothing, and you decide on the host, once:
lea requests # g12 claude-1 (lead in lea-myproj) asks for a merge grant on repo api (gh github.com/me/api) …
lea approve g12 g13 # record them, for that lead and its children (--expires 30d: a longer life)
lea deny g14 not this one # the lead is told, with your reason
lea grant requests|approve|deny # the same, under lea grantThe approved request is an allowance of the lead's subtree (--agent the lead): its children then
merge their own PRs (gh pr merge N --squash --delete-branch) without a prompt, and no agent
outside that lead's team is covered. The lead gets a message when you decide, and when a request
expires (a day without an answer). Only leads file requests; no agent can approve one
(grant_request_decide is host-only). A child whose merge nothing covers is told to ask its lead
for one, or you for lea allow merge --repo <repo>.
Release tags. A tag push is a hard deny, but for the one form release-tag covers:
git push origin refs/tags/vX.Y.Z (an optional pre-release, -rc.1), one plain command at the
root of the agent's worktree. lea pushes it from the same lea-push bare repository, only
when the tag's commit is on the default branch of the remote (fetched at that moment), and without
force, so a tag the remote already has is refused. --tags, --follow-tags, force, a refspec,
another remote and a non-semver tag stay denied. deliver never includes it.
Release publication. A repository with no workflow that publishes a release on tag push needs
gh release create after the tag push; the release capability covers exactly
gh release create <tag> --verify-tag [--title T] [--notes-file F | --generate-notes] [--prerelease] [--latest],
one plain command at the root of the agent's worktree, for a semver tag that --tag GLOB matches
(none given: any semver tag). --verify-tag is required, so gh never creates the tag (that stays
release-tag's job). lea runs it pinned like every allowed gh call (env -i, -R the pin,
lea's gh config, through lea's proxy); a notes file follows the rule of
gh pr create --body-file. --draft, --target, --notes, assets, --latest=false (use the
plain flags) and every other gh release subcommand (edit, delete, upload, delete-asset)
stay uncovered; a lead asks for it with grants_request (action release-create, tag
the glob). deliver never includes it.
Allowances and hard denies keep a confused agent (one that misreads a message, a brief or its
own transcript) from merging, pushing or deleting where you did not say it may; they are not a
sandbox against a hostile one. An agent can still write and run code through the tools it is
allowed (go run, a test, a script), and it can read the token of glab's config (GitHub's is the
proxy's: it can use it, not read it): what keeps a hostile agent in check is the container, its
network rules and the scope of the tokens you give lea, not allowances. Two ways a hostile agent
gets past them, among others: a shell function named /usr/bin/env in Claude's shell snapshot
replaces the pinned call, and a loop rewriting the lea-push bare repository's config (same user)
between lea's check and the push can send the push elsewhere. Revoking is your lever: lea allow off, or x in the deck's Allowed screen.
To check that a Claude Code release runs the command lea rebuilds (the hook's updatedInput)
before relying on allowances, in a lea: lea allow push --repo <r> --for 10m, ask an agent working
on a branch of <r> to git add a file and run git commit -m test, then check that git reflog -1 in its worktree says commit (lea grant) (a plain git commit writes commit: test); lea allow log lists the use.
lea new --brief FILE gives a new agent its first message; --repo NAME starts it in a
directory of the projects directory; --branch B has it work in its own git worktree under
<projects>/.lea/worktrees/<repo>/<agent>.
lea # the deck, for $LEA_PROJECTS_DIR (unset: the working directory, on the first run)
# (LEA_DECK=0: your own tool in the lea container, see Without the deck)
lea attach [--print] [AGENT] # the tool in the lea container, or an agent's terminal (--print: the command)
lea web [--open] [--port N] # the deck in your browser, on 127.0.0.1 (see lea deck in your browser)
lea web --listen ADDR:PORT (--tls-self-signed | --tls-cert F --tls-key F) [--new-token]
# on the network, behind TLS and a lasting token (prefer ssh -L)
lea requests # what waits for you; lea approve ID [always], lea deny ID (sN, gN: [reason])
lea questions [drop ID] # the control towers' questions to you: the open one, then the queue
lea hold [--off] [AGENT] # hold the messages agents send the tower while you answer it; --off releases them
lea limits [get [KEY] | set KEY VALUE | reset KEY] # the live limits (max_running, relay_tokens, budget_5h_pct,
# budget_usd_agent, budget_usd_total, budget_usd_step), changed on the running lea at once
lea config deck on|off # the deck, or your own tool (lea config tool CMD...), from the next lea
lea config claude [KEY ...] # Claude's base settings for your agents (defaultMode, allow, deny, env...)
lea new [-r role] [-p provider] [-m model] [--repo R] [--branch B] [--brief file] [name] [-- args]
# one more agent (its CLI's arguments after --)
lea role AGENT ROLE # make an agent a lead, a dev or a reviewer (only you can)
lea board [--md] [--watch] # every agent's task; lea agents lists them
lea msg AGENT TEXT # a note to an agent's inbox; lea inbox reads yours
lea shell [-- cmd...] # a shell, or one command, in the same lea
lea stop [--all] [--forget] # stop this lea (--all: every lea); the next lea resumes its agents
# in their Claude conversations (--forget: drop them for good)
lea update [--deps ask|all|none] # the latest release and its images (--deps is kept and installs nothing)
lea rollback # back to the previous version; the background update skips this one
lea doctor # check the setup
lea init [--locksql] [--lockmq] [--lockfile] [--locklog] [--lockssh] [--deck|--no-deck] [--tool CMD]
# set up again (idempotent; --no-<tool> records an opt-out)
lea egress allow DOMAIN...|deny DOMAIN...|list|denied [--since 24h] # the egress allowlist, live
lea kube refresh # mint a read-only Kubernetes token (8 h)
lea locksql|lockmq|lockfile|locklog|lockssh # whether agents reach that Lock, and how it runs
lea request accept|decline ID [reason] # a spawn request routed to you (no lead)
lea sound on|off # the deck's sounds, at runtime
lea heavy -- CMD... # a heavy job (tests, builds), in a free slot (see Heavy jobs)
lea config ctl on|off # lea's daemon in a container of its own (LEA_CTL)
lea version # the version
lea config export > team.json # your team's shared settings, as one file
lea config import team.json # take them on another workstation (see Configure)
LEA_PROJECTS_DIR=~/other lea # another projects directory, for this call only
lea allow [deliver|CAPABILITY...|off N|log] # what agents may do without asking (see Allowances)
lea approve gN [--expires 30d] # approve a lead's grant request (lea requests lists them; see Allowances)
lea grant requests|approve|deny # the same, under lea grant
lea github login|logout|status # lea's GitHub token, in the proxy only (see Git and forges)One command per install method; each pulls the new version's images, then names the Lock clients
(update-deps):
- Homebrew:
lea updaterunsbrew updateandbrew upgrade davidgodefroid/tap/lea, then the new version pulls its images. It never installs a second lea beside Homebrew's, and fails with brew's status when brew fails.brew upgrade leaalone works too: the nextleapulls the images it lacks and restarts the daemon on the new binary. Old versions arebrew cleanup's. - install.sh:
lea update, or the daily background update below. - git checkout:
lea updatepulls and rebuilds (see Install from source).
A release install updates itself: at most once a day, lea looks for a new release in the
background. A newer minor or patch release is installed beside the current one (its signature
checked with cosign) and becomes active at the next lea; a newer major
release is only announced in the deck, and so is a newer minor release while lea is 0.x (only
its patch releases install themselves). Running containers keep their image until they stop.
LEA_AUTOUPDATE=0 in ~/.config/lea/lea.conf turns it off; the log is
~/.local/share/lea/host/update.log. A Homebrew install has it off (its formula sets
LEA_AUTOUPDATE=0); turned back on, it only announces a new release, which lea update installs
with brew.
The agents' CLIs, Claude Code and Codex, update themselves too, between lea releases. lea's image
pins the version its CI verified; in each lea container, a check at its start and then every 6
hours asks registry.npmjs.org (in the default egress allowlist) for the latest release of each,
and a newer one is installed in /lea/cli, beside the image's, checked (its --version), then
made current with an atomic link swap. The agents started after it run it; a running agent keeps
its version, which is never removed while a process runs it, and a release older than the
image's pin is never installed. The check runs as lea-cli, a user of its own: the agents read
/lea/cli but cannot write it, so no agent can leave the next ones a CLI of its making, and a
/lea/cli someone else could write is ignored. Claude Code's own updater stays off
(DISABLE_UPDATES). agents_list shows the version each Claude agent runs (cli_version), and
lea-cli-update status in the container both versions of each CLI; the log is
/lea/cli/update.log. LEA_CLI_AUTOUPDATE=0 in ~/.config/lea/lea.conf turns it off for the
agents started after lea stop --all: they run the image's CLIs.
The Locks' clients in lea's image (locksql, lockmq, lockfile, locklog, lockssh) come from one set of releases,
config/locks.lock: for each Lock, the client's release, the protocol its handshake speaks, the
release's image by digest and the identity that signed it. lea's CI bumps the set as a whole
(tools/locks-bump checks every signature with cosign), and a lea release ships it as it is: lea update moves the clients together, never one by one, and installs, builds or starts no Lock: lox
does (brew upgrade lox, lox add TYPE NAME --version vX.Y.Z, lox run). lea doctor compares
each lock lox runs with lea's client of its type, from the image lockfamily.yaml pins or, for
another image, from the lock console's own hello handshake (lea lock-hello, run in lea's image
with only that lock's socket volume), and says what to run: lea update for a lock newer than
lea's client, brew upgrade lox then lox add TYPE NAME --version for an older one; a pair whose
protocols differ fails (every call of the agents would be refused). The handshake speaks the
protocol of lea's client (lea lock-hello --protocol N): a console of another protocol refuses it
("protocol mismatch", naming its own), and lea doctor fails that lock with the fix. lea warns at the start about
a lock that lockfamily.yaml pins to an image of another release. LEA_LOCKSQL_REF,
LEA_LOCKMQ_REF, LEA_LOCKFILE_REF, LEA_LOCKLOG_REF and LEA_LOCKSSH_REF remain for this release as a dev override of a client's
version (lea doctor warns while one is set); LEA_LOCKSQL_IMAGE is obsolete.
After an update only the current and the previous versions stay in
~/.local/share/lea-install (never the one a running daemon still uses). lea rollback links the
previous version again and sets LEA_AUTOUPDATE_SKIP=<this version> in ~/.config/lea/lea.conf,
so the background update does not reinstall it (lea update still does); it fails when there is
no previous version.
Each projects directory gets its own container, internal network, Claude history and login. The
projects directory cannot be /, your home directory or one of its parents, nor overlap
~/.claude, a credentials directory (~/.ssh, ~/.gnupg, ~/.aws, ~/.config/gh, ~/.kube,
~/.docker), the directory of your user configuration or lea's own directories.
~/.config/lea/lea.conf holds your settings as KEY=value lines (lea init writes it);
config/lea.conf in the installation documents most keys and their defaults (the table below
lists more).
The deck's , opens a settings screen over the same file: the keys that matter, grouped, each
with its value, where it comes from (default, your file, the environment) and a one-line help.
enter or space flips a toggle, takes the next choice or opens a field (enter saves, esc
cancels); a value is checked before it is written. Sounds, the theme, the deck width and the
live limits (the Limits group, set through the running daemon) apply at once; the screen says
when the others apply (after lea stop --all, or at the next lea). A key the environment sets
(LEA_PROJECTS_DIR, LEA_APPROVALS, LEA_APPROVAL_TIMEOUT) wins over the files, so it is shown
read-only. The screen runs in the deck on the host: agents cannot open or drive it.
| Key | Default | What it does |
|---|---|---|
LEA_PROJECTS_DIR |
asked by lea init |
the directory lea's agents see |
LEA_GIT_SSH |
empty | git SSH endpoints (host:port …) |
LEA_GIT_KNOWN_HOSTS |
~/.config/lea/git_known_hosts |
their pinned host keys |
LEA_LOCKSQL |
0, on when lox run runs a locksql lock |
1: wire lea for the locksql console of lox run (lea init --locksql) |
LEA_LOCKMQ, LEA_LOCKFILE, LEA_LOCKLOG, LEA_LOCKSSH |
0, asked by lea init; on when lox run runs a lock of the type and the key is unset (=0 keeps it off) |
let the agents reach a lockmq / lockfile / locklog / lockssh console on this host |
LEA_LOCKSQL_REF, LEA_LOCKMQ_REF, LEA_LOCKFILE_REF, LEA_LOCKLOG_REF, LEA_LOCKSSH_REF |
empty: the set of config/locks.lock |
a dev override of a client's release (lockfile v0.1.1 or later), for this release only; lea doctor warns while one is set |
LEA_LOCKHTTP |
0 |
send the agents' web requests through a LockHTTP gate (refuses LEA_GIT_SSH and LEA_OTEL_UPSTREAM) |
LEA_HUB |
1 |
follow the Lock Family approval hub (lockhub's facade socket: LEA_HUB_SOCKET, else $XDG_RUNTIME_DIR/lockhub/facade.sock): an agent whose Lock call waits for a decision there is suspended until it comes, and lox run, outside lea, decides them (lea shows and answers no ticket); while no hub answers, no agent is suspended, the deck says lockhub unreachable and lea doctor warns. 0: lea reads no hub and resumes the agents it suspended. Upgrading from v0.2: the default was 0; put LEA_HUB=0 in ~/.config/lea/lea.conf to keep that, then restart lea |
LEA_HUB_KEEPALIVE |
300 |
seconds (0 to 3600) an agent suspended on a hub ticket keeps its process before lea stops it alone, keeping its session for the decision or a message to resume it; read only with LEA_HUB=1 (changing it while the hub is off restarts nothing) |
LEA_LOX_UP |
none | obsolete (#300): set, lea and lea doctor warn and ignore it. Run lox run in another terminal instead |
LEA_INTERNAL_HOSTS |
config/internal-hosts of the installation |
the path of the file listing the private hosts the proxy may reach, one <host or IPv4> <ports> line each (its comments give the format) |
LEA_EGRESS_ALLOW |
empty (lea's default list) | the only web domains agents may reach, comma separated (subdomains included); default stands for lea's list, * opens the web |
LEA_NESTED_NETWORKS |
empty | networks your compose files expect, created at start |
LEA_RUNTIME |
empty (the engine's default, runc) | the OCI runtime of the agent containers only: runsc (gVisor) or kata (Kata Containers) puts a second kernel between the agents and the host's (a second kernel); applies to a container started after the change (lea stop, then lea) |
LEA_CPUS, LEA_MEMORY, LEA_MEMORY_SWAP, LEA_PIDS_LIMIT |
75%, 50%, no swap, 16384 |
the lea container's limits: CPUs (a share of Docker's, at least 2, a number such as 8, or 0), memory (a share of Docker's, a size such as 16g, or 0), memory plus swap (-1: no limit), processes and threads (0: no limit); the next lea applies them to a running container, or restarts it with them once no agent or session runs in it; rootless Podman needs Delegate=cpu cpuset io memory pids for user@.service (lea doctor checks it) |
LEA_APPROVALS, LEA_APPROVAL_TIMEOUT |
deck, 60 |
who answers permission requests |
LEA_PROVIDER, LEA_MODEL |
claude, empty |
the default provider and model of a new agent (providers) |
LEA_PROVIDERS |
~/.config/lea/providers |
your OpenAI-compatible endpoints and their key files |
LEA_CHILD_PLUGINS, LEA_CHILD_MCP |
empty | lean children: the host plugins and MCP servers a lead's children start without, comma separated; read at each spawn |
LEA_AUTO_RESUME, LEA_RESUME_DELAY |
on, 60 |
resume agents stopped on a usage limit, so many seconds after its reset (0: off) |
LEA_STACK_IDLE |
10 |
minutes an agent stays idle before lea stops (not removes) the containers it started in the nested Podman (0: never); lea board lists what it freed |
LEA_QUESTION_REMIND |
120 |
minutes a control tower's question waits for your answer before the tower asks it again, once, prefixed with reminder: (0: never) |
LEA_MAX_RUNNING |
3 |
the most children of leads that run at once, host-wide (0: no cap); a live limit: lea limits set max_running N applies it without a restart |
LEA_RELAY_TOKENS |
120000 |
the context size, in tokens, at which the control tower relays a child to a fresh agent (0: above 50 % of its window); a live limit: lea limits set relay_tokens N applies at the tower's next board check |
LEA_BUDGET_5H_PCT |
60 |
the account's 5-hour usage (%) at or above which new children of leads wait (0: off); a live limit: lea limits set budget_5h_pct N |
LEA_HOLD_MAX |
30 |
minutes a pause of an inbox (the deck's H, lea hold) lasts before lea releases it (0: never) |
LEA_AGENT_CPUS |
4 |
each agent's CPU window, the least shared CPUs: the agent, its tools and its nested containers run there, so nproc, PHPStan, Go… see that many CPUs (0: no window) |
LEA_HEAVY_SLOTS, LEA_HEAVY_WORKERS |
0 (¾ of the CPUs ÷ workers), 4 |
heavy jobs (lea heavy -- <command>): how many run at once per container, and the CPUs and workers each gets |
LEA_ADMIT_CPU_PSI, LEA_ADMIT_MEM_PCT, LEA_ADMIT_MEM_PSI, LEA_ADMIT_IO_PSI, LEA_ADMIT_LOAD |
70, 85, 10, 40, 2 |
host pressure above which new agents wait: PSI in percent, memory in percent of the lea container's limit (the host's from 90 %), the host's load per CPU (0: that one off) |
LEA_SHED_MEM_PCT, LEA_SHED_MEM_PSI, LEA_SHED_CPU_PSI, LEA_SHED_AFTER, LEA_SHED_RESUME |
95, 30, 80, 30, 60 |
host pressure that pauses the lowest-priority agent once it lasts LEA_SHED_AFTER seconds (0: never), resumed after LEA_SHED_RESUME seconds of calm |
LEA_BUDGET_USD_AGENT, LEA_BUDGET_USD_TOTAL, LEA_BUDGET_USD_STEP |
0, 0, 20 |
spend budgets in USD: the most one agent, and all agents together, may spend before lea pauses them (0: off), and how much more (in percent) an agent you resume over a budget may spend; live limits |
LEA_DECK, LEA_TOOL |
1, empty (claude) |
the deck, or (0) your own tool in the lea container (without the deck); lea config deck on|off, lea config tool CMD |
LEA_DECK_WIDTH |
34 |
the deck column's width (24 to 60, at most half the window); < and > in the deck, or a drag of its border, change it |
LEA_CLIPBOARD |
1 |
the copy bridge from the agents to your host clipboard (0: off); applies after lea stop --all |
LEA_AUTOUPDATE, LEA_CLI_AUTOUPDATE |
1, 1 |
the daily background update of lea, and the agents' CLIs updating themselves (Update) |
LEA_CTL |
0 |
1: lea's daemon, tmux and deck run in a control container, lea-ctl (lea config ctl on|off) |
LEA_LOCKHTTP_MITM |
0 |
1 (with LEA_LOCKHTTP=1): the gate decrypts HTTPS with a local CA (LockHTTP) |
LEA_LOCK_TOOL_TIMEOUT |
1500 |
seconds (60 to 86400) a Codex agent waits on one Lock call |
LEA_K8S_NAMESPACE |
lea |
the namespace of the read-only Kubernetes token (lea kube refresh) |
LEA_IMAGE, LEA_PROXY_IMAGE, LEA_RELEASES_URL |
the release's images, GitHub releases | the agent and proxy images, and where lea update finds releases |
LEA_SOUND |
on | the deck's sounds (0: off) |
LEA_SOUND_ATTENTION |
freedesktop sound | the file of the sound lea plays when it needs you (0: off) |
LEA_OTEL_UPSTREAM |
empty | send Claude Code usage telemetry to this OTLP collector |
LEA_AUTONAME, LEA_AUTONAME_MODEL, LEA_ASCII |
on, haiku, off |
automatic names (LEA_AUTONAME=0: off) and their model; ASCII marks in the deck (LEA_ASCII=1). Environment variables only for now: set in lea.conf, these three are not applied |
LEA_THEME |
catppuccin (mono when NO_COLOR is set) |
the deck's colours: catppuccin, gruvbox, nord, tokyo-night, solarized, high-contrast or mono (no colour: bold, faint and reverse video); T in the deck picks one with a live preview, and the tmux pane borders follow it. An unknown name gives catppuccin |
lea config export [--output FILE] [--include-personal] writes the shared part of your
configuration as one JSON file, fit to commit in a team repository: the keys your
~/.config/lea/lea.conf sets among LEA_GIT_SSH, LEA_EGRESS_ALLOW, LEA_OTEL_UPSTREAM,
LEA_IMAGE, LEA_PROXY_IMAGE, LEA_LOCKSQL, LEA_LOCKSQL_REF,
LEA_RELEASES_URL, LEA_NESTED_NETWORKS, LEA_K8S_NAMESPACE,
LEA_APPROVALS and LEA_APPROVAL_TIMEOUT (LEA_SOUND too with --include-personal), and the
content of your pinned git_known_hosts and of your internal-hosts file. Never exported:
LEA_PROJECTS_DIR and every path, the workstation's own keys (LEA_PREFIX, LEA_DECK,
LEA_TOOL, the known-hosts and internal-hosts paths…, skipped silently), any other key (skipped
with a warning), lea's SSH key, forge
tokens, locksql and Vault credentials, ~/.claude and lea's state. A value or a line that does
not pass the import's checks (a locksql checkout's path, a @cert-authority line…) is skipped
with a warning.
lea config import FILE|- [--dry-run] [--replace] [--yes] reads such a file as data, never as
shell: only those keys and the two files are taken, and every value and line is checked with
lea's own rules (an approval mode, a timeout of 1 to 600 s, host:port endpoints, plain host
names and pinned keys without wildcards, https:// URLs, image references…). Anything else, a
value on more than one line or holding shell syntax, or a format newer than this lea reads, is
refused and nothing is written. The configuration it gives is loaded once more before any write.
It prints what changes (KEY: old -> new, + and - lines of the files), then:
- a change that widens what the agents reach (
[egress]:LEA_GIT_SSH,LEA_EGRESS_ALLOW,LEA_OTEL_UPSTREAM,internal-hostslines), pins SSH host keys ([host key]) or chooses the code lea runs ([code]: images,LEA_LOCKSQL_REF,LEA_RELEASES_URL) or wires a lock tool ([lock tool]:LEA_LOCKSQLturned on) needs its own flag,--allow-egress,--allow-host-keys,--allow-codeor--allow-lock, on top of--yes;--dry-runshows which and writes nothing (LEA_LOCKMQ,LEA_LOCKFILE,LEA_LOCKLOGandLEA_LOCKSSHare not shared); - without
--yesit asks on the terminal (and refuses without one).
By default the import merges: the keys it carries replace yours, the others (LEA_PROJECTS_DIR,
your sounds…) stay; its files' lines are added to yours, and a host you already pinned to another
key is refused (--replace replaces your pins). --replace replaces the shared part: shared keys
the file does not set are removed, and the files it carries replace yours. The files are written to
~/.config/lea/git_known_hosts and ~/.config/lea/internal-hosts (LEA_GIT_KNOWN_HOSTS or
LEA_INTERNAL_HOSTS then points there), only when the import adds lines: a file you use at its
own path (an organisation's shared file) stays in use, untouched, when the import adds nothing to it; every file it replaces is kept as *.bak; every write is private (0600), at once,
and refused through a symbolic link. A key the environment sets beats the file: the import says
so. It prints when each change applies: after lea init (LEA_GIT_SSH, keys, images,
locksql), once the proxy restarts (LEA_EGRESS_ALLOW, LEA_OTEL_UPSTREAM), after lea stop --all (approvals, networks, sounds), at the next lea update (LEA_RELEASES_URL) or at the next
lea kube refresh (LEA_K8S_NAMESPACE).
A company can set rules for lea on every workstation with the Lock Family's managed
configuration: one file, /etc/lockfamily/managed.toml on Linux and
/Library/Application Support/lockfamily/managed.toml on macOS, deployed by the administrator
(MDM, Ansible, a package) and owned by root (lockfamily.dev/docs/managed).
Its [lea] section is read after your lea.conf and wins over it: you may tighten what it
allows, never loosen it.
version = 1
organisation = "ICTools"
[lea]
approvals = "deck" # LEA_APPROVALS, enforced
autoupdate = true # LEA_AUTOUPDATE=1, enforced
grant_ttl_max = "7d" # no grant lives longer
standing_grants = false # every lea allow needs --for
egress_allow = ["default", "corp.example"] # the agents reach these domains at most
[lea.claude_enforced] # Claude Code settings of every agent
defaultMode = "default"approvals("deck"or"pane") andautoupdate = truesetLEA_APPROVALSandLEA_AUTOUPDATE; your own value, in a file or the environment, is ignored with a warning that cites the managed key. Every release lea installs is checked with cosign anyway: there is no way to turn that off.egress_allowbounds the egress allowlist: the agents reach the domains of yourLEA_EGRESS_ALLOWthat it covers (each domain covers its subdomains,defaultis lea's default list), and the model API (anthropic.com, claude.ai, claude.com) always. Your entries beyond it are ignored with a warning,lea egress allowrefuses a domain outside it, andlea egress listshows the list in force. Withegress_allowset,LEA_LOCKHTTP=1is refused unless the managed file has a[lockhttp]section for the gate.grant_ttl_max = "7d"bounds every grant:lea allow --forandlea approve --expiresbeyond it are refused, a lead's grant request is shortened to it, and a grant recorded before lives at most that long from its creation.standing_grants = falserefuseslea allowwithout--for, and the allowances already recorded until revoked stop applying (lea allowshows them as suspended by company policy);grant_ttl_maxalone refuses them too. Each allowance and each use of one records the managed file's sha256. If the file stops loading, no grant applies and none is recorded until it is fixed.[lea.claude_enforced]sets Claude Code settings in every agent's managed settings, overlea config claude, which then refuses to change them:defaultMode(notbypassPermissions),model,language,outputStyle,alwaysThinkingEnabled, anddisableBypassPermissionsMode = "disable"(lea keeps it so anyway). Any other key, lea's own (hooks, status line) included, is refused.modelis the agents' default: a lead's choice of a child's model still applies. It applies to lea containers started after the change.lea config importrefuses a file beyond the managed configuration as a whole, nothing written; the deck's settings screen shows the enforced keys as set by company policy.lea doctorprintsManaged by <organisation> (sha256:…)and the active rules, and the deck's header shows the organisation.
Fail closed: a managed file that is badly owned (not root's, or writable by others), invalid, not
signed when it must be, or with a [lea] key this lea does not know, stops lea and its daemon from
starting; it is never ignored. Without the file, lea runs on your configuration alone.
lea weblistens on the host's127.0.0.1only, which no lea container shares, and acts as you through the daemon's host socket, as the deck does: an agent reaches neither. The link it prints carries a random one-time token (32 bytes), valid for 2 minutes, that the browser exchanges for anHttpOnly,SameSite=Strictcookie; every API call needs that cookie, and a request whoseHostorOriginis not127.0.0.1:PORTorlocalhost:PORTis refused (another site's page, DNS rebinding). The API forwards a fixed list of the daemon's methods, for this lea's agents only (a request, grant request or question is answered only when the daemon lists it for one of them; allowances are always this lea's); the daemon methods behind requests, grants, allowances and questions (question_answeramong them) are host-only, refused on any agent's bus socket, andlea allowandlea egressfrom the page run on the host itself; there is no CORS, and a strict Content-Security-Policy keeps any other script or origin out of the page.lea web --opennever puts the token in a command line, which any local user can read (ps): it writes a page that posts the token to a private file (0600, in a0700directory of$XDG_RUNTIME_DIR, removed whenlea webstops) and opens that file. A browser that cannot open local files (some snap packages) needs the printed link. To use it from another machine, forward the port over SSH (ssh -L 8414:127.0.0.1:8414 host, thenlea web --port 8414on the host).lea web --listen ADDR:PORT(#416), the explicit opt-in to the network, refuses to start unless it serves TLS (your certificate and key, or--tls-self-signed: an ECDSA P-256 certificate lea makes once, keeps 0600 in its host data dir and renews near its end; TLS 1.2 or later, and its fingerprint printed at each start) and has a lasting credential: a 256-bit token kept 0600 in the host data dir, replaced by--new-token. The browser signs in by typing it into the page (a POST, never in an address, which history and logs keep: a link with?token=is refused on the network); each sign-in gets its ownSecure,HttpOnly,SameSite=Strictsession cookie, held in memory for 7 days (stopping lea web signs every browser out), and wrong tokens make that source (an IP address, an IPv6 /64) wait longer and longer, up to a minute, without locking anyone else out. It never listens where an agent could reach it: a wildcard address (0.0.0.0,::), the address of a container bridge (docker0,br-*,veth*,podman*,cni*…), an address inside a container network's subnet (Docker's, lea's agent networks included) and an address the host does not have are refused, and so is a start when the container networks cannot be listed. It warns on every start.- lea web's terminal view reads an agent's pane through the daemon (
agent_capture, host only: tmuxcapture-pane), and only reads it: no lea code types into an agent's terminal. What the pane shows is drawn as text in the page; its colour escapes are applied, every other escape (links, titles, cursor moves) is dropped, and nothing in it is ever run as markup. - The container sees the projects directory, a read-only allow-list of
~/.claude(keybindings.json,hooks,skills,mods,dev-mods,output-styles,agents,commands, the top-level*.mdfiles and yourstatusLinescript), this projects directory's transcripts (~/.claude/projects/<slug>, read/write, so its sessions resume on the host and in lea), its own writable copies ofsettings.jsonandplugins(never written back: Plugins and permissions in lea) and, with locksql, lockmq, lockfile, locklog or lockssh, the socket volume of theirlox runlock (and locksql's.locksql, locklog's.locklogand lockssh's.lockssh, read-only, whatever the switch). Besides, it gets lea's own mounts: its state (/lea/state/…), the daemon's bus socket, the copy bridge's FIFO, theinternal-hostsfile and the Kubernetes token (see What an agent can read). None of your other files. .lockfamilyin the projects directory (the Lock Family hub's config, the locks' public keys, the routing) is read-only in the container: lea makes it, owned by you on the host, when it is missing, and refuses to start when it is a symbolic link or a file.- With the Lock Family's
lox runin the projects directory, its locks are the consoles lea's agents reach (locksql, lockmq, lockfile, locklog, lockssh and LockHTTP run underlox runonly): for each tool that is on (LEA_LOCKSQL,LEA_LOCKMQ,LEA_LOCKFILE,LEA_LOCKLOG,LEA_LOCKSSH), lea mounts the socket volumelox runnames in.lockfamily/up.json(lockhub'sdocs/lox-run.md) on/run/<tool>, read-only, once docker confirms it is that lock's socket volume for this projects directory (compose project,dev.lockfamily.role=socket, instance and workspace labels): never a lock's home or the hub's network. lea ignores anup.jsonthat is a link, that others than you can write, or that names another projects directory. Several locks of one tool each get/run/<tool>/<instance>,LEA_<TOOL>_INSTANCESnames them, a Codex agent gets one MCP server per lock (<tool>-<instance>, run with--instance), and lea's MCP server tells every agent to pass--instance NAME. A lock lea cannot use (a bad name, a volume docker does not confirm) gets no socket at all, never the fixed one of another console; a warning says so. - Egress goes through a proxy: HTTPS (and plain HTTP) to an allowlist of public domains (plus
LEA_INTERNAL_HOSTS), SSH only toLEA_GIT_SSH. Private and link-local addresses are refused, but thehost portpairs the internal-hosts file lists.LEA_EGRESS_ALLOW='*'opens every public domain, and withLEA_LOCKHTTP=1the LockHTTP gate's policy replaces the allowlist. - By default the allowlist is lea's own:
github.com,githubusercontent.com,ghcr.io,gitlab.com(git,gh,glab, release assets),golang.org(Go modules and checksums),registry.npmjs.org,registry.yarnpkg.com,pypi.org,pythonhosted.org,docker.io,docker.com,quay.io(images for nested builds),fedoraproject.org,alpinelinux.org(their packages),openai.com,chatgpt.com(Codex), and alwaysanthropic.com,claude.ai,claude.com(the model API and its login). Each domain covers its subdomains. Anything else (documentation sites fetched by an agent, another forge, a Fedora mirror outsidefedoraproject.org) is refused. The refusal's first line names the host and the command that allows it (lea-proxy refused deb.debian.org: not in the egress allowlist. To allow it, run on the host: lea egress allow deb.debian.org (applies live, no restart; there is no one-off form: it stays until lea egress deny deb.debian.org).). HTTPS clients hide that page behindCONNECT tunnel failed, response 403: lea's agents are told to recognise it and to hand you that command, never to work around the proxy. - To allow a domain, run on the host
lea egress allow deb.debian.org(several at once if you like): the running proxy takes it at once, without restarting the proxy, the containers or the agents, and the domain is kept inLEA_EGRESS_ALLOWin~/.config/lea/lea.conf(defaultkept).lea egress deny DOMAINtakes back a domain added so;lea egress listshows the list and where each entry comes from;lea egress denied [--since 24h]lists the hosts the proxy refused lately, with the containers that asked and the command for each. The command runs on the host only: no agent, MCP tool, grant or file in an agent's reach can change the list. - Egress log. An agent has no route but its own network, so it can
reach nothing but the proxy. If something gets around that (a container with
NET_ADMINon an agent network, a misconfigured network) and sends a packet past the proxy, for example a direct connection to1.1.1.1or to169.254.169.254, the host still drops it, and lea's egress log records it in the kernel log. Read it withjournalctl -k -g lea-egress; each line names the source and the destination (SRC=,DST=,DPT=). The log is an nftables table of lea's own,bridge lea_egress. It logs only, rate-limited to 20 packets a minute, the IP packets alea*bridge takes up to the host instead of across to the proxy: traffic between the agents and the proxy stays on the bridge and is never logged. Every internal network lea creates gets a bridge namedleaplus 12 hex digits, so one rule covers all of them, and nosudois needed when an agent starts.lea initinstalls it on Linux hosts with a rootful Docker,nftand systemd.lea-egress-log.serviceloads it at boot and again whennftables.servicerestarts or reloads.lea doctorchecks that it is installed, current and active, and loaded whensudo -nworks. It names any internal network the log does not cover (made by an older lea:lea stop --all,docker network rmit, thenlea), and warns with a count when packets were logged in the last 24 hours. Hosts with a rootless engine or Docker Desktop get no egress log, because the agents' bridges are not in the host's network namespace there, andlea doctorsays so. HTTP and HTTPS that go through the proxy are not logged here: the proxy refuses what is not on the allowlist (lea egress denied). - You can also edit
LEA_EGRESS_ALLOW="default,corp.example,docs.example.org"yourself (defaultkeeps lea's list); withoutdefault, only the domains you list (and the model API) are reachable. The nextleaapplies an edited list to the running proxy live, the same way. To open the web to any domain, as lea did before, setLEA_EGRESS_ALLOW='*'(lea doctorwarns): a change to or from*restarts the proxy. Internal hosts are not affected.lea doctorshows the active list. - Whatever
LEA_EGRESS_ALLOWsays, the proxy refuses public DNS-over-HTTPS resolvers (dns.google,cloudflare-dns.com,quad9.net,nextdns.io, anydoh.*name …), which would reopen the DNS channel the internal network closes, and public IP literals (https://1.1.1.1/, decimal or hex forms, IPv6): a public host is reached by its name. A host of your network is reached by its address once listed inLEA_INTERNAL_HOSTS. - An internal host name grants that name only, not every vhost of the ingress behind it: the proxy
peeks at the TLS handshake (no decryption) and passes a tunnel only when its SNI is the allowed
name, so a tunnel to an internal name must be TLS with SNI. The proxy cannot see the
Hostheader inside: if your ingress serves aHostother than the SNI, require SNI = Host on it. An IPv4 literal grants the whole address, every vhost on it included. - The API keys of your providers' endpoints stay in the proxy container: no agent mounts a key
file, and the key forwarder reaches an endpoint only through the proxy's egress rules. So does
lea's GitHub token (
lea github login, see Git and forges). - The proxy container, the only one on both the agents' networks and the egress network, runs
confined: every capability dropped but
SETUIDandSETGID,no-new-privileges, a read-only root (tmpfs on/run,/tmpand/var/cache/squid), a pids and a memory limit. No service in it runs as root: squid assquid, the SSH and OTel forwarders asnobody,lea-keyproxyas you (the owner of the key files; under rootless Podman, the container's root, which is you on the host); only its entrypoint, PID 1, stays root to wait, or squid is PID 1 when no endpoint is configured. A proxy that could not read a key file stops at start and says which. This confinement applies to a proxy image labelledlea.confine=1(lea's own); an older or pinnedLEA_PROXY_IMAGEwithout the label runs unconfined, with a warning, and on rootless Podman without the memory or pids cgroup controller the matching limit is left out. - lea never gets the Docker socket; the agents' own containers run in a rootless Podman inside
lea, under seccomp and, on Linux, AppArmor. lea's seccomp profile (
image/seccomp.json) is Docker's default (moby/profiles, vendored and pinned inimage/seccomp/) with a reviewed list of changes, each with its reason, inimage/seccomp/lea.json;image/seccomp/generate.pybuilds the profile from them and CI fails on any other difference. It allows what the nested rootless Podman needs and Docker's default keeps forCAP_SYS_ADMIN(cloneandunshareof namespaces,setns,mount,umount2,open_tree,move_mount,mount_setattr,pivot_root), so unprivileged user namespaces are available in lea (unshare -U -rworks: the rootless Podman runs in one). The rest stays refused as in Docker's default: the kernel keyring (keyctl; nested containers join no keyring),perf_event_open,bpf,reboot,syslog, the new mount API'sfsopen... It also refusessocketcall, the kernel crypto API sockets (AF_ALG, CVE-2026-31431), audit netlink sockets (NETLINK_AUDIT, as lea dropsCAP_AUDIT_WRITE), and what lea's earlier profile refused that Docker's default allows (vmsplice,cachestat,map_shadow_stack, the futex2 calls,io_pgetevents). 32-bit x86 (i386) programs do not run in lea: theirsocketcallhides the socket family from seccomp, so the profile leaves that architecture out. seccomp compares 64-bit registers where the kernel reads anintargument's low 32 bits, so the generator refuses any test of anintargument that high bits could get past (socket(16, 3, 0x100000009)is an audit socket to the kernel). The AppArmor profileleais docker-default with its/procwrite denies, plus mounts and user namespaces for the nested Podman. - No way back to root in lea: the entrypoint drops to your uid with no capabilities, the image has
no
sudoand no setuid or setgid file.newuidmapandnewgidmapkeep their file capabilities, which the rootless Podman maps its sub-ids with; that is why lea runs withoutno-new-privileges. - Every lea container shares the host kernel (unless
LEA_RUNTIMEputs the agents on gVisor or Kata: a second kernel), so the host's patch level is part of the containment. The kernel must carry the fixes for CVE-2026-74753, CVE-2026-80521 and CVE-2026-80841; on Ubuntu, check withapt changelog linux-image-$(uname -r) | grep -E 'CVE-2026-(74753|80521|80841)'.lea doctorshows the kernel, Docker Engine, containerd and runc versions and would fail below a kernel minimum ofconfig/host-minimums, but that file has no kernel line yet: every distribution gets a warning (check the changelog yourself), never a failure. On a Podman host (dockeris Podman),lea doctorwarns that lea is built for Docker Engine, and below Podman 5.8.4 (CVE-2026-57231) the launcher warns too. - Each agent container's internal network has
gateway_mode_ipv4=isolated(Docker Engine 28.0 or later): the host has no address on it, so host services listening on0.0.0.0(databases, dev servers, a Docker API over TCP) are out of the agents' reach. When the engine cannot give it (an older Docker Engine, Podman, an engine whose version lea cannot read, or a network left without it by an older lea), lea refuses to start the container, for a network that already exists as for a new one; it also refuses one whose bridge, as the host sees it, holds a host address, whatever its option says;LEA_ALLOW_GATEWAY=1(in your configuration or the environment) accepts a plain internal network instead, with a warning.lea doctorprints the gateway mode of each internal network and fails on one that is not isolated (a warning underLEA_ALLOW_GATEWAY=1). When Docker has no free address pool left for lea's network (all predefined address pools have been fully subnetted), lea says so with Docker's message: remove unused networks (docker network prune) or adddefault-address-poolsin/etc/docker/daemon.json;LEA_ALLOW_GATEWAY=1does not help there.lea doctorcounts the free pools (Docker's defaults hold 31 networks). - The agents resolve no external name: lea starts each agent container with
--dns 192.0.2.1(TEST-NET-1, never routed; not a loopback address, which Docker may query from the host's namespace), out of reach of its internal network, so Docker's embedded resolver answers the names of the containers on its network (lea-proxy) and forwards nothing to the host's resolver, which would otherwise carry a query name past the proxy. lea-proxy resolves the names the agents reach; nested containers use the same resolver.lea doctorfails on a running container that resolvesexample.com, and warns about one an older lea started without this resolver. - Work in lea, not on the host, inside the projects directory: an agent can write files your host
tools would run. When the last session closes, lea reports changes to git hooks, risky git
configuration,
.mcp.jsonand.claude/settings. - Change Claude Code's configuration on the host: it is read-only in lea, but for lea's own
copies of
settings.jsonandplugins. After editing a single file (settings.json, a top-level*.md,keybindings.json), restart lea (lea stop).
Nothing of your machine's credentials: no API key or token is in the agent container's
environment or image. What lea gives the agents, though, they run as the owner of, so any agent
(or anything it runs: a test, a postinstall, a nested container with the directory mounted) can
read it. lea doctor lists what is there, by path (never a value):
| Credential | Path in the lea container | Readable by the agents |
|---|---|---|
| Claude Code's OAuth login (access and refresh token) | ~/.claude/.credentials.json |
yes, read-write: Claude Code refreshes it. It is lea's own login for this projects directory, never your host's; with LockHTTP's MITM, the gate refuses on the Claude API a token that is not this container's. |
| Codex's login | ~/.codex/auth.json |
yes, read-write (Codex refreshes it) |
| GitHub token | none: the proxy's (lea github login) |
no; usable through gh and git |
GitLab and other forges (glab auth login, git's store) |
/lea/state/glab-cli/config.yml, /lea/state/git/credentials |
yes |
Container registry logins (podman login) |
/lea/state/containers/auth.json |
yes |
| Kubernetes | ~/.kube/lea/config |
yes, read-only: a view token of lea kube refresh, 8 h |
lea's SSH key (LEA_GIT_SSH) |
none: its ssh-agent container's (<container>-ssh, no network); the agents get the agent's socket, /run/lea/ssh/agent.sock |
no: usable through the ssh-agent socket only (not under a virtual machine runtime, where a socket cannot cross into the VM) |
Provider API keys (~/.config/lea/providers) |
none: the proxy's | no; usable through the key forwarder |
Claude Code has no way, today, to take a short-lived token or one a proxy adds: its refresh token stays on disk, so scope what that login reaches. Keep the readable ones narrow: a GitLab token limited to its projects, registry logins for the registries the agents need.
By default the agent container runs on the engine's default runtime (runc): one kernel, shared
with the host, so a single kernel bug reachable from the container is enough to escape, whatever
seccomp and AppArmor refuse. LEA_RUNTIME puts a second kernel in the way, for the agent
containers only (the proxy and the gates run no agent code and stay on the default runtime):
LEA_RUNTIME=runsc: gVisor, a user-space kernel (the Sentry) that answers the agents' system calls; the host kernel sees a few of its own.LEA_RUNTIME=kata: Kata Containers, a lightweight virtual machine with its own guest kernel per container (needs hardware virtualisation:/dev/kvm).
The runtime is installed and registered with dockerd first (lea installs nothing on the host);
then set the key (~/.config/lea/lea.conf) and restart lea's containers (lea stop --all, then
lea). An unknown runtime refuses the start and names those the engine knows; a running
container left on another runtime gets a warning; lea doctor shows LEA_RUNTIME, whether the
engine knows it, the runtime of each running lea container (docker inspect -f '{{.HostConfig.Runtime}}' <container> shows it too), and warns when the runtime would leave lea's
seccomp profile out (a runsc registration without --oci-seccomp, a Kata configuration.toml
without disable_guest_seccomp = false). tests/integration/install-runtime.sh runsc
(or kata) does the installation the way lea's CI does (sudo, pinned releases checked against
digests pinned in the script: gVisor's sha512 for release-20261102.0 on x86_64 and aarch64
(GVISOR_SHA512 required for any other release or architecture), Kata's sha256 for 4.3.1 on
amd64 and arm64 (KATA_SHA256 required for any other version or architecture); it restarts dockerd), and LEA_TEST_RUNTIME=runsc make test-isolation runs the isolation checks on it.
gVisor (runsc) |
Kata (kata) |
|
|---|---|---|
| Minimum release | release-20260803.0, the first weekly release after gVisor's 30 July 2026 change to file descriptors passed over Unix sockets (the fix tied to OpenAI's sandbox report); lea's CI runs release-20261102.0 | 3.27.0 (CVE-2026-24834, guest privilege escalation through virtio-pmem); 4.2.0 or later recommended, the first release after the two Kata changes of August 2026 that the same report cites; lea's CI runs 4.3.1 (runtime-rs, QEMU) |
| dockerd registration | "runsc": {"path": "/opt/gvisor/runsc", "runtimeArgs": ["--oci-seccomp", "--host-uds=open", "--host-fifo=open"]} |
"kata": {"runtimeType": "io.containerd.kata.v2"}, and in Kata's configuration.toml, disable_guest_seccomp = false and "--xattr" in virtio_fs_extra_args (the nested Podman's newuidmap needs its file capability) |
Nested Podman (docker, docker compose in lea) |
works, but its containers share lea's network namespace (gVisor refuses the bind mount Podman keeps a network namespace with): their ports are lea's, and a port below 1024 cannot be bound | works, with its own network namespaces; its images and Buildah's /var/tmp live in tmpfs inside the VM (rootless Podman cannot unpack a layer, nor Buildah make a RUN step's root, on virtio-fs), so they count against the container's memory and are pulled again after each restart |
| lea's bus (messaging between agents), the Lock consoles' sockets | work (--host-uds=open lets the sandbox connect to host Unix sockets) |
unavailable: a host Unix socket does not cross into the VM (lea says so at start; make test-isolation prints info lea's bus socket is not reachable) |
| Clipboard (copy from an agent to the host) | works (--host-fifo=open) |
off: a host FIFO cannot be bound into the VM (lea leaves it out and says so) |
| seccomp, AppArmor | lea's seccomp profile is applied inside the sandbox only with --oci-seccomp (runsc ignores it otherwise); runsc ignores the AppArmor profile, the Sentry runs under gVisor's own seccomp filter |
lea's seccomp profile is applied in the guest only with disable_guest_seccomp = false; the AppArmor profile is not applied in the VM |
| Cost | syscall-heavy work (builds, git, package installs) is slower; little memory |
a VM per container: its memory (the guest's default size) and a few seconds more at start |
--host-uds=open and --host-fifo=open widen what the sandbox may open on the host (gVisor
advises against host sockets where they are not needed): they are what lea needs (its bus socket, the Lock consoles' sockets, the clipboard FIFO), on paths lea
mounts; leave them out and lea starts, but without messaging between agents, the Locks or the
clipboard. Keep the host patched anyway: the second kernel narrows the shared kernel's surface,
it does not remove it.
Is lea a replacement for Claude Code or Codex? No. lea runs the real agent CLI, Claude Code by default or Codex, with your own configuration, and gives it a safe place to run and a deck to run several at once.
What is the difference between lea and lea deck? lea is the tool: the lea command, its
daemon, the container, the proxy, the agents, their messages and allowances. lea deck is its
interface: the terminal lea opens (and lea web in a browser). Both come in the one lea
install, and lea runs without the deck (see lea and lea deck).
Which agents does lea run? Claude Code (the default), OpenAI's Codex CLI, and through Codex any
OpenAI-compatible endpoint that serves the Responses API: Ollama, vLLM, a server of your own (see
Other providers). Without the deck, lea runs any command
you give it (see Without the deck). The Control Tower and lea's plugin run on
Claude Code only.
Why not --dangerously-skip-permissions on the host? On the host that flag hands an agent
everything your user can reach. In lea an agent can go just as fast, but what it can reach is fixed
by the container and the proxy.
How is lea different from a devcontainer? A devcontainer isolates a toolchain; lea isolates the agent: an egress proxy that refuses private networks, none of your host's credentials (see What an agent can read), a nested container engine, an audit of risky changes on exit, and a deck for many agents.
Does my code leave my machine? Only to what the egress allowlist reaches: your agent's model
API, as it already sends it (the Claude API for Claude Code, OpenAI's for Codex, your own endpoint
for a local model), and the forges and registries your agents push to or fetch from. lea
has no server and no account, and sends no telemetry of its own; Claude Code's usage metrics go
nowhere unless you set LEA_OTEL_UPSTREAM.
Can an agent reach a service on my LAN? Not by default. List the hosts it may reach in the
internal-hosts file, one <host or IPv4> <ports> line each: LEA_INTERNAL_HOSTS is that file's
path (by default config/internal-hosts of the installation, whose comments give the format).
- Start with
lea doctor. It checks lea's managed settings, Docker and the host versions (kernel, Docker Engine, containerd, runc), the images, the proxy and the internal networks, the egress log, tmux, the AppArmor profile, the projects directory and the configuration, then each lock lox runs against lea's client of its type (config/locks.lock), with the fix to run when they differ. - An agent cannot reach a host. Private and link-local addresses are refused on purpose; add
the host to
LEA_INTERNAL_HOSTS. A public domain outside lea's default list goes inLEA_EGRESS_ALLOW(default,<domain>); a public IP literal or a DNS-over-HTTPS resolver is always refused. The proxy's refusal page says which host it refused and why. - A change to
~/.claudedoes not show. Single files are mounted as they were at start:lea stop, thenlea. docker composefails with a network error. Known limitation, below;docker runworks.
git clone https://github.com/DavidGodefroid/lea.git ~/.local/share/lea-src
~/.local/share/lea-src/bin/lea init # builds build/lea and the images (needs git, make and Docker; Go runs in Docker)
lealea update in a checkout pulls and rebuilds. On a Linux host without a recent tmux, make tmux-build builds a static tmux 3.5a (a Linux binary) into build/tmux; on macOS, brew install tmux.
lea stop --all --forget
docker ps -a --filter label=lea.prefix=lea # lea-proxy and anything left: docker rm -f them
docker network ls --filter label=lea.prefix=lea # lea's networks: docker network rm them
docker volume ls --filter name=lea- # lea-podman-<id>, lea-lockhttp-*: docker volume rm them
docker image ls 'ghcr.io/davidgodefroid/lea*' # then docker image rm the ones listed
rm -rf ~/.local/bin/lea ~/.local/share/lea-install ~/.local/share/lea ~/.config/lea
brew uninstall lea # a Homebrew install, instead of ~/.local/bin/leaWhat lea init installed as root on Linux stays until you remove it:
sudo apparmor_parser -R /etc/apparmor.d/lea && sudo rm /etc/apparmor.d/lea
sudo systemctl disable --now lea-egress-log.service
sudo rm /etc/systemd/system/lea-egress-log.service /etc/lea/egress-log.nft && sudo systemctl daemon-reload
sudo nft delete table bridge lea_egress # when the stop left it loadedA source install also leaves ~/.local/share/lea-src, ~/.cache/lea-go and the lea:dev,
lea-proxy:dev and lea-ctl:dev images.
go test ./... # Go unit tests (the tmux ones need tmux 3.2+)
make test # shellcheck + shell unit tests, in a container
make build # the lea:dev, lea-proxy:dev and lea-ctl:dev images
make test-proxy # proxy rules against fake DNS and decoys
make test-isolation # isolation checks (needs make build and, on Linux, lea init)
make test-pressure # host resources on the real engine (ENGINE=podman for rootless Podman)A tag vX.Y.Z publishes a release: the archives for Linux and macOS (amd64, arm64), their
checksums (checksums.txt and its cosign bundle checksums.txt.sigstore.json), install.sh,
and the images on ghcr.io/davidgodefroid, signed with cosign.
Docs are 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.
Test suites, static analysis and builds start one worker per CPU they see. lea gives each agent a
window of LEA_AGENT_CPUS CPUs (4), the ones fewest agents share. The agent, its tools and the
containers it starts in the nested Podman run there: nproc, PHPStan, php-cs-fixer, Go, pytest-xdist
and Node's os.availableParallelism() see that many CPUs, without anything in your projects. (lea
runs the nested Podman's crun through a wrapper that pins an agent's containers, podman exec
included.) Tools that count /proc/cpuinfo still see every CPU. The window is not a hard limit:
the lea container's LEA_CPUS is. lea doctor lists the windows.
Test suites, static analysis, builds and browsers start one worker per core of the host: a few
agents running them at once take every core. Agents run them through lea heavy:
lea heavy -- vendor/bin/phpstan analyse
lea heavy -- go test ./...lea heavy waits for one of the container's LEA_HEAVY_SLOTS slots, in order, saying who holds
them, then runs the command on LEA_HEAVY_WORKERS CPUs of its own (tools that count the CPUs
they may use, such as nproc, see that many) with GOMAXPROCS, MAKEFLAGS=-jN,
CMAKE_BUILD_PARALLEL_LEVEL, CARGO_BUILD_JOBS, PYTEST_XDIST_AUTO_NUM_WORKERS and
LEA_HEAVY_WORKERS set. A slot whose job was killed frees itself within three minutes; a job holds its slot two hours at
most. lea board
lists the jobs that run and wait.
Some limits change while agents run, without a restart: models change fast, a plan changes, a
heavy day needs a tighter cap than a quiet one. lea limits shows each one with its value, its
default and where the value comes from (lea's default, your file, the environment):
lea limits # max_running 3 (default 3, from lea's default; 2 in use)
lea limits set max_running 2 # applies now, kept in ~/.config/lea/lea.conf
lea limits reset max_running # back to the environment's value, else lea's defaultThe running daemon checks the value, writes it to your file and applies it at once; the next
lea keeps it and does not restart the daemon for it. The deck's settings screen (,) lists the
same keys in its Limits group and sets them the same way. A key set in your file wins over the
environment, which stays a fallback. Agents read the limits with the limits_get tool, so a
tower can adapt; no agent can set one.
| Limit | Default | What it caps |
|---|---|---|
max_running (LEA_MAX_RUNNING) |
3 |
the children of leads that run at once, host-wide (0: no cap). Your own sessions and the leads do not count. At the cap a lead's agents_spawn is refused (3 children already running (limit max_running 3): retry with queue: true or wait for one to end), or with queue: true waits and starts once a child ends; lea board and agents_list show why (queued: max_running 3/3). A spawn request a lead accepts goes through the same check |
relay_tokens (LEA_RELAY_TOKENS) |
120000 |
the context size, in tokens, at which the control tower relays a child: it asks the child for .tower-handoff.md, stops it and starts a fresh successor on the same branch (0: above 50 % of the child's context window). agents_list marks the tower's children past it with relay: true, falling back on the percent when a child's tokens are unknown (Codex, an older Claude Code). The tower reads it at each board check |
budget_5h_pct (LEA_BUDGET_5H_PCT) |
60 |
new children of leads while the account's 5-hour usage is at or above it (0: off). The usage comes from the agents' status lines (Claude subscription accounts; an API account reports none, and unknown usage never holds a spawn). Above it a lead's agents_spawn is refused (5h usage 64 % ≥ budget_5h_pct 60: retry with queue: true…), or with queue: true waits and starts once the 5-hour window resets or you raise the value; each lead gets one note per crossing. Running agents are never stopped or paused |
budget_usd_agent (LEA_BUDGET_USD_AGENT) |
0 (off) |
the most one agent may spend, in USD, as its status line reports it (cost_usd). Over it lea pauses that agent |
budget_usd_total (LEA_BUDGET_USD_TOTAL) |
0 (off) |
the most all agents may spend together, in USD, since the last lea limits reset budget_usd_total. Over it lea pauses every running agent and holds new spawns: agents_spawn is refused (budget reached: total spend $50.20 ≥ budget_usd_total $50 …), or queued with queue: true (queued: budget_usd_total $50.20/$50) |
budget_usd_step (LEA_BUDGET_USD_STEP) |
20 |
in percent of a budget: how much more an agent you resume by hand over that budget may spend before lea pauses it again |
A change never stops a running agent: a cap lowered below what runs holds new spawns until enough children end; a raised one starts the queued spawns at once, up to the new cap (one per pressure sample).
The account's usage shows at the top of the deck (5h 42% (14:05) · 7d 18%, with the 5-hour
window's reset time when there is room), amber once it reaches budget_5h_pct; lea limits
prints it on its last line (usage: 5h 42 % (resets Sat 14:05) · 7d 18 %) and limits_get
answers it, read-only. Nothing shows before an agent's status line reported it. When your plan
changes, lea limits set budget_5h_pct 80 applies at once and starts the spawns that waited if
the usage is now below it. A queued spawn still waits at most 30 minutes, as under pressure.
Every turn of an agent re-reads its whole context (cache reads), so usage grows with
concurrent agents × context size × model: seven children at 200–300 k tokens each burn a
5-hour subscription window in about two hours. The live limits bound the first two factors:
max_running caps the children that run at once, relay_tokens the context a child carries
before the tower hands its task to a fresh agent. The deck and agents_list show each agent's
context size next to its percent (182k · 18%), so a big one is easy to spot. The model is the
tower's choice per task. On API billing, the spend budgets below cap the bill itself.
On API billing (pay per token), nothing else stops a runaway agent: a loop, a huge context read again each turn, or a tower left running overnight. The two budgets are a kill switch:
lea limits set budget_usd_agent 10 # no agent spends more than $10
lea limits set budget_usd_total 50 # all agents together, since the last reset
lea limits reset budget_usd_total # a new period: what was spent no longer countsOver a budget, lea pauses the agent (budget_usd_agent) or every running agent
(budget_usd_total), the way it does under host pressure: its processes are frozen, its session
and its work are kept, nothing is stopped. The deck's row turns red and says why
(budget reached: $12.40 ≥ budget_usd_agent $10), lea board lists it under "Paused on a spend
budget", the alert sound plays and the agent's lead gets one note. While budget_usd_total is
on, the deck's header shows the total spent against it ($12.40/$50), red once reached.
The total counts each agent's spend since the period began; when an agent's cost counter starts
again (a new session), what it spent before still counts. It outlives a restart of the daemon.
lea limits reset budget_usd_total starts a new period and keeps the value; lea limits set budget_usd_total 0 turns it off.
To go on: raise the budget (lea resumes what it paused on it and starts the queued spawns), reset
the total, or resume an agent by hand (p in the deck). An agent resumed by hand over a budget is
paused again only once it spends budget_usd_step percent more of that budget, so resuming does
not loop. An agent whose status line reports no cost (cost_usd unknown, as with some providers)
is never paused: lea limits and lea doctor name the running agents the budgets do not cover.
No agent can change a budget (limits_set is the host's); limits_get shows them, with the
spend, read-only.
The lea daemon samples the host and each lea container every 5 seconds: PSI (cpu some,
memory full, io full, avg10), the memory in use against the container's limit (page cache the
kernel drops first left out), and the host's load. It reads /proc and the container's cgroup v2,
found from its process, so it works the same with Docker and rootless Podman.
Above a threshold a lead's agents_spawn is refused with the reason, for example
under pressure (container cpu PSI 76% > 70%, memory 92% of 24.0 GiB > 85%); 14 agents run, 2 heavy slots busy. With queue: true the spawn waits instead, up to 30 minutes, and the lead gets a
message when it starts; one calm sample starts one queued agent at most. The queue lives in the
daemon's memory: a daemon restart drops it without a message. agents_request_spawn is not
refused: a request starts nothing, the lead's agents_spawn is the gate. Meanwhile each container gets half its heavy slots (at least one): jobs
that run keep theirs, new ones wait.
When a container (or the host) stays critical for LEA_SHED_AFTER seconds (30: memory at 95 % of
the limit, memory PSI 30 %, or cpu PSI 80 %), lea pauses its lowest-priority agent together with
the containers it started in the nested Podman (SIGSTOP: the nested Podman has no cgroup freezer).
A frozen process keeps its memory, so when memory is what is critical lea first stops those
containers, and starts them again when it resumes the agent. It pauses another one every
LEA_SHED_AFTER only while each pause makes the reading better, and at most half the agents it
may pause: no cascade when what weighs is elsewhere. Idle agents go first, then the newest dev,
reviewers after devs; never a lead, never an agent that holds a heavy slot. A busy agent is paused
only once no idle one is left: it carries on where it stopped when resumed. Its lead gets a message, and lea board lists it
under "Paused under pressure". Once the pressure stays under the admission thresholds for
LEA_SHED_RESUME seconds (60), lea resumes them one by one, the last paused first; one you
resumed yourself (the deck's p) is left alone. The list survives a daemon restart.
lea doctor checks that PSI is readable, that each running lea container's cgroup is, and that
the shedding thresholds sit above the admission ones.
lea board shows the host's gauge and each container's
(CPU 14.8/16 · PSI 22% · mem 18.1/24.0 GiB · heavy 3/4 (+2 queued)); the deck shows the
container's on its last line, amber near a threshold, red over one.
-
What an agent starts in the nested Podman (
docker,docker compose,podman, through its own Podman service) is removed when the agent ends, and stopped (not removed) once the agent has been idleLEA_STACK_IDLEminutes (10): the agent starts it again when it needs it. What you start from a deck shell is neither. Everylearemoves what the agents that are gone left, stops the stacks of agents idle for that long already, and names the containers no agent started. -
docker composewith its own networks does not work inside lea yet: the nested Podman's network backend (netavark) setsnet/ipv4/conf/<bridge>/route_localnetto 1 in its rootless network namespace, which Docker's read-only/proc/sysrefuses. It skips the write when the value is already 1, but that namespace takes its defaults from the host'snet.ipv4.conf.default, where it is 0 on most hosts.docker runworks. -
The AppArmor profile (
apparmor/lea.tmpl) carries docker-default's/procand/syswrite denies, but allowsmount,umountandpivot_root, which the nested rootless Podman needs (#100); seccomp still filters those calls.
Apache 2.0. lea is an independent project, not affiliated with Anthropic. Claude and Claude Code are trademarks of Anthropic.
The brand assets (logo, demo) are in assets/, generated by tools/brand;
the website is site/, published by .github/workflows/pages.yml.