How it works
How lea works
One container per projects directory holds your agents. A proxy beside it is their only way out, and lea deck, lea’s terminal interface, is how you drive them.
The container
your machine
┌───────────────────────────────────────────────────────────┐
│ ~/projects ─────────── read/write ────────────┐ │
│ ~/.claude (allow-list) ─── read-only ─────────┤ │
│ ~/.claude/projects/<slug> ─ read/write ───────┤ │
│ ▼ │
│ ~/.ssh ~/.aws ~/.kube ──╳ ┌─── lea container ───┐ │
│ Docker socket ──────────╳ │ agent: lead │ │
│ │ agent: dev │ │
│ │ agent: reviewer │ │
│ │ rootless Podman │ │
│ └──────────┬──────────┘ │
│ ▼ │
│ 192.168.0.0/16, 10.0.0.0/8 ◄──╳── egress proxy │
│ │ │
└───────────────────────────────────────────┼───────────────┘
▼
public allowlist: GitHub, npm, the model API
The container sees the projects directory (read/write) and a read-only allow-list of ~/.claude: keybindings.json, hooks, skills, mods, dev-mods, output-styles, agents, commands, the top-level *.md files and your status line script. One host directory is mounted read/write: ~/.claude/projects/<slug>, the Claude Code transcripts of this projects directory. settings.json and plugins are lea’s own copies, never written back.
lea config claude, on the host, sets your base settings for Claude Code in lea: the default mode, the allow, ask and deny rules, the model, the environment. They are kept beside lea.conf, never in your ~/.claude, and lea’s own guards stay. A statusLine command in your settings.json draws the agents’ status line, inside the container.
Each projects directory gets its own container, internal network, agent history and login. Agents run under abduco, so closing the deck does not stop them.
The proxy
Every request of an agent goes through lea’s proxy. HTTPS reaches an allowlist of public domains: the forges, the package registries, the model APIs. Anything else is refused, with a first line that names the host and the command that allows it.
lea egress allow DOMAIN, on the host, adds a domain to the running proxy: no restart, and no agent can run it. Private and link-local addresses, public IP literals and DNS-over-HTTPS resolvers are refused whatever the allowlist says; only the host and port pairs you list in the internal-hosts file (LEA_INTERNAL_HOSTS) reach a private address.
The proxy is also the agents’ only resolver. Their container gets a DNS address that is never routed, so a lookup cannot carry data out through your host’s resolver.
The proxy also holds what the agents must use but not read: lea’s GitHub token, your providers’ API keys, and the SSH forwarders to the git endpoints you pinned.
lea deck
lea deck is lea’s interface, not a separate tool: the container, the proxy, the agents and their messages are lea’s and run with or without it. lea opens it in your terminal, on your machine, outside the container; no agent can drive it.
One keyboard-first terminal: your agents in a column on the left, the selected agent’s terminal on the right. The mouse works too.
| Key | Action |
|---|---|
| n | start a new agent |
| N | start a new Control Tower |
| j k | select an agent |
| enter | type into the selected agent |
| space | the next agent that needs you |
| a d A | allow, deny, always allow a permission request |
| m t | send the agent a message, read its messages |
| Q H | the tower’s questions to you, pause its inbox |
| g | what you allowed the agents, and revoke it |
| T | pick a colour theme, previewed live |
| s | a shell in the container |
| q | leave the deck; agents keep running |
The deck comes in seven colour themes, high-contrast and mono among them; LEA_THEME sets one and NO_COLOR gives mono. A red dot needs you, a spinner works, a green dot is done. A sound plays only when an agent needs you, or when lea pauses one on its budget. The deck is optional: lea config deck off runs your own tool in the container instead, with the same confinement.
lea web serves lea deck in your browser, on 127.0.0.1 only: the live board of your agents, their messages, the control tower’s chat and its questions, new agents, the permissions, spawn and grant requests they wait on (with the one-off and the durable lea allow answer), allowances and the egress allowlist. The link it prints signs one browser in, once; no agent container can reach it.
Each agent’s Terminal tab shows its terminal live and read-only; browser notifications tell you of new permissions, requests and tower questions while the tab is in the background; folders are the deck’s own, in both views. From a laptop or a phone, an SSH tunnel (ssh -L) reaches it; lea web --listen is an explicit opt-in to the network that refuses to start without TLS and a lasting token, and never listens where an agent could reach it.
Teams of agents
Every agent has a role: lead, dev or reviewer. Only you change one. A lead starts devs and reviewers through lea’s MCP tools; any other agent asks a lead. An agent a lead starts works where the lead works, unless the lead names another repository, and joins its folder in the deck.
Agents message each other, report on their task (the deck and lea board show it) and lease the files they edit. An agent whose turn is over is woken when a message arrives.
The Control Tower
When the deck opens with no agent running, its first agent is a Control Tower: a lead on Claude Code that runs /lea:control-tower. You talk to it only. It splits your requests into tasks, starts the agents that do them, follows them and briefs you in a line per agent. It never does the work itself; a hook keeps it to lea’s team tools. It answers in the language of your latest message, whatever language its agents write in.
It asks you one question at a time. The others queue, an incident first, then what blocks an agent, then the rest; your next prompt answers the open one, and the tower relays it to the agent that asked. Q lists the queue, H (or lea hold) pauses the messages agents send it while you answer. N starts another tower.
Allowances
An allowance is a decision you record on the host and lea applies to every agent it covers: merge a pull request, close an issue, push the agent’s own branch. Each one is pinned to the repository’s origin, and no agent can record one.
lea allow deliver # push, pull request, merge, delete the branch, on every repository here
lea allow push --branch 'feat/*' --agent dev-1 --for 2h
lea allow # what you allowed, the time left, the last uses
lea allow off 1 # take allowance 1 back
An allowance holds until you revoke it, unless --for says otherwise. In the deck, g shows the same list.
Providers
Claude Code is the default provider. Codex is in the image, with its own login per projects directory, and runs any OpenAI-compatible endpoint that serves the Responses API: Ollama, vLLM, a server of your own.
An endpoint’s key file is mounted in the proxy only. Agents reach the endpoint at http://lea-proxy:4400/<name> and see neither the key nor the upstream.
The Locks
A Lock is a console that stands between your agents and a resource and alone holds its credentials. lea starts none of them: lox run does, for the projects directory, and decides their requests.
For each lock lox run runs (locksql, lockmq, lockfile, locklog, lockssh), lea mounts that lock’s socket volume read-only on /run/<tool>, once Docker confirms it belongs to this projects directory. The agents reach the socket and nothing else: no credential, no profile, no audit log.
lockhttp works differently: its gate sits in the proxy’s network and every outbound request goes through it. Only the proxy joins the hub’s network; no agent reaches the hub.
Containers inside lea
lea never gets the Docker socket. docker and podman in lea reach a rootless Podman of the agent’s own, so tests and builds run as usual.
What an agent starts there is stopped once it has been idle 10 minutes, and removed when the agent ends. docker compose with its own networks does not work yet; docker run does.