Let an AI agent running in lea use the web: reads of trusted hosts pass,
anything that sends data or reaches an unknown host waits for you.
Quick start · How it works · Docs · Lock Family · lockhttp.com
lockhttp is a Lock of the Lock Family, harness security for AI agents. It is the proxy every outbound HTTP(S) request of an agent running in lea goes through. Reads of hosts you trust pass; anything else waits for your approval on lockhub, where the agent cannot reach it.
Important
The agent must run inside lea. lockhttp guards only the containers lea
starts with LEA_LOCKHTTP=1, whose only way out is lea's proxy. An agent
you start directly on your machine (outside lea) does not go through the
gate: lockhttp sees none of its requests and protects nothing there.
Note
0.x: the policy format may still change between minor versions. Built on lockkit v0.20.0. Command names are fixed; flags may still move. Design decisions: docs/decisions.md.
- Per request, not per domain. An allowlist lets a host's writes through with its reads. lockhttp keeps reads free and holds writes, uploads and unknown hosts for a human.
- Approval outside the agent. Each held request becomes a
NeverAutoticket on lockhub, answered by a human inlox run. Nothing in the agent's process can switch it off. - Credentials the agent never holds. With TLS decryption (or plain HTTP to an internal host), the gate can inject an API token for one host and port; a known credential format sent to the wrong host is refused once the gate sees the request (decrypted or plain HTTP).
- Traced. Every decision is tied to the container, the agent and the session that asked.
In-agent approval is a convenience; a separate approval process is a boundary.
lockhttp needs lockhub's lox v0.12.1 or later (it passes
--runtime-gids to the lockhttp v0.12 console), cosign v2.5.0 or later
(lox add and lox run verify every image with it) and
lea v0.16.0 or later. The
lockhttp formula pulls in none of them: name them with it.
brew trust davidgodefroid/tap
brew install davidgodefroid/tap/lockhttp davidgodefroid/tap/lox cosign
brew install davidgodefroid/tap/lealockhttp runs in Docker: Homebrew installs the lockhttp launcher, which runs
every command in the release's signed image. lox is lockhub's CLI, and the
gate runs inside lea. The whole
family instead, lox and cosign included:
brew install davidgodefroid/tap/lockfamily.
Without Homebrew, the Lock Family's installer puts the same tools in
~/.local/bin (lockfamily install);
cosign v2.5.0 or later must be on PATH:
curl -fsSL https://lockfamily.dev/install.sh | shLEA_LOCKHTTP=1 needs lea v0.16.0 or later to use this launcher. Linux and macOS; on Windows, WSL 2 with Docker Desktop. The launcher, its
commands and the setup by hand: docs/install.md.
-
In lea's projects directory, add the lock.
lox add lockhttpasks only for its name, writes the policy and starts the console:cd ~/projects lox add lockhttp
-
In a terminal of its own, outside lea and any agent, keep
lox runopen. Every held request shows up there:lox run
-
Turn lockhttp on in lea's configuration, then restart lea.
LEA_LOCKHTTP=1 leais not enough: lea's configuration wins over the environment.echo LEA_LOCKHTTP=1 >> ~/.config/lea/lea.conf lea stop --all lea
lea-proxy and its gate are shared by every lea on the machine: 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.
lea doctorreports the gate's state. -
Ask your agent to read the docs of a trusted site: it goes through. Ask it to post somewhere: the request waits for your
y.
lockhttp is a proxy, so inside lea's containers it works with any agent and any HTTP client (lea runs Claude Code today). Outside lea it is not on the path at all. The contract with lea: docs/lea.md.
|
👤 Never answered automatically |
🔑 Credentials injected |
|
🔁 LLM APIs checked as a relay |
🧱 Fail closed |
More: the verdicts, refusal codes and the Claude API rules, and the policy keys. A company bounds lockhttp with the Lock Family's managed configuration (lockhttp's section).
Three pieces, each in a container of its own, and the hub.
agent container (internal network only)
│ HTTP(S)_PROXY
▼
lockhttp gate ── FREE ──▶ squid ──▶ Internet
│ ASK ▲
▼ │ on y
lockhub ── ticket ──▶ you, in lox run
·
lockhttp console: serves the approved policy to the gate
- The agent's HTTP client sends every request to the gate. In lea the agent's container has no other route out.
- The gate decides each request with the policy the console serves it. It never reads a policy file.
- A free request goes out through squid. A request that needs a human is held (60 s by default) as a signed ticket on the hub.
- With a local CA and the signer, the gate decrypts HTTPS and decides
each request by method, path, headers and body. Without them, it decides
a
CONNECTat the domain only.
The full diagram, verdicts, refusal codes, the Claude API checks and the limits: docs/how-it-works.md.
- The gate is the enforcement point. The console is the only place the policy loosens; the hub's facades the only place a request is approved.
- OS separation. The console runs as its own account in its own container; the kernel checks the gate's uid on its socket.
- Confined agents only. An agent that does not run confined (outside
lea, or with the host's container runtime in reach) is refused, at the
console and at the gate, unless a non-production profile sets
unconfined = true(docs/policy.md). - The AI tightens, the human loosens. Any change that widens what passes
without a human waits for your
:reviewin the console. - Audit. The gate audits every decision and every hub ticket's outcome
in its JSONL log, with a
request_id; never a body, a query string or a header value (a decision's warnings may name a/v1/messagesbody'smcp_servers). The console approves no request: it audits policy reviews. - Known limits. Without decryption a
CONNECTopens reads and writes, and whoever can rundockercan reach the console's container.
Every rule: docs/safety.md. Threat model: docs/security-model.md.
| Doc | What it covers |
|---|---|
| docs/install.md | install paths, the launcher's commands, the setup with lea by hand |
| docs/how-it-works.md | the pieces, verdicts, what the agent sees, the Claude API checks, limits |
| docs/configuration.md | the policy file, every profile key, policy examples, the company's managed configuration |
| docs/policy.md | the policy reference: evaluation order, credential injection, shadow mode, loosenings |
| docs/usage.md | every command and flag, exit codes, files, audit records |
| docs/docker.md | the image, its accounts and volumes, update, migrating from a host install |
| docs/lea.md | the integration contract with lea |
| docs/safety.md | the safety model in full |
| docs/security-model.md | threats, parades, residual risks |
| docs/decisions.md | design decisions |
| CHANGELOG.md | what changed, release by release |
The site, lockhttp.com, is built from site/.
| Repo | What it does |
|---|---|
| lockfamily | The family site (lockfamily.dev) and the one-line installer. |
| locksql | SQL databases: the agent queries, PII comes back masked; connections and writes wait for you. |
| lockmq | RabbitMQ: masked queue inspection; connections, peeks and unmasked reads wait for you. |
| lockfile | Files (S3, SFTP, disk): the agent asks yes/no questions about files it never reads. |
| lockhttp | Outbound HTTP(S) of agents in lea: reads of trusted hosts pass; anything that sends data or reaches an unknown host waits for you. |
| locklog | Logs: masked, bounded log search; the agent reads the logs, not the people in them. |
| lockssh | Commands over SSH: allow-listed commands run at once, the rest waits for you; the key never leaves the console. |
| lockhub | The approval hub and its lox CLI: lox run approves outside the agent's harness and never sees values in clear. |
| lockkit | The shared Go core of every Lock: console, policies, masking, signed tickets, audit, MCP. |
| lea | Runs many agents in containers, wired to the Locks. |
- Contributing: CONTRIBUTING.md. Build with
CGO_ENABLED=0 go build ./cmd/lockhttp(Go 1.26+). - Docs: 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'sdocs-site/nav.toml: open a lockfamily PR, or the nightly docs build fails. - Security: report a vulnerability privately, see SECURITY.md.
- License: Apache License 2.0, see LICENSE and NOTICE.