How lockhttp works

Where each piece runs

 agent container  (internal network, no other route)
 ┌──────────────────────────────────────────────────────┐
 │ claude code · curl · git · npm · chromium            │
 │ HTTP(S)_PROXY=http://<agent>:<token>@lea-proxy:3130 │
 └──────────────────────────┬───────────────────────────┘
                            │ the only way out
 lea proxy network namespace  ▼  (gate + signer sidecars)
 ┌──────────────────────────────────────────────────────┐
 │ lockhttp gate :3130   (own uid, never 0)             │
 │   source → container · policy → FREE / ASK / DENY    │
 │   lockhttp signer     (optional: holds the CA key)   │
 │   squid 127.0.0.1:3128 (network floor) ──▶ Internet  │
 └──────────────────────────┬───────────────────────────┘
                            │ Unix socket, volume lockhttp-run:
                            │ the gate and the console only
 console container          ▼
 ┌──────────────────────────────────────────────────────┐
 │ lockhttp console --profile default                   │
 │   account lockhttp, volume lockhttp-home (policy)    │
 │   approvals · policy review · auto mode · audit      │
 └──────────────────────────────────────────────────────┘

The agent containers never see the console socket. The console authenticates the gate by its uid (SO_PEERCRED) and never goes on the network itself.

How a request is decided

The first step that decides wins:

1. Network floor (DENY, cannot be loosened): IP literals, DNS over HTTPS, private ranges and metadata addresses, ports other than 80/443, an SNI that differs from the host, Upgrade: h2c, nested CONNECT.
2. Internal hosts you declared (CI, registry): decided at the domain, FREE only when you marked them read, only on their declared ports.
3. A single-use authorisation left by an approval whose client had already given up.
4. Exfiltration heuristics (data in the URL, high-entropy values and labels, unusual headers, known secrets, PII): logged only by default (heuristics = "shadow"); with heuristics = "enforce" a score of 3 or more asks, never in auto mode.
5. Policy rules, from the most specific to the least.
6. Defaults: body-less reads of trusted hosts are FREE; reads of unknown hosts, writes, uploads, messaging and WebSockets ASK; a body over the buffer limit (10 MiB) is denied.

The life of a held request

1. Agent → gate: POST https://api.unknown.io/v1/upload
2. Gate: source → container; policy → ASK; body buffered (up to the limit); local queue
3. Gate → console: summary, masked preview, warnings, correlation (container, agent, task, session)
4. Console → you: approval screen
5. You → console: y, or n <reason>
6. Gate → upstream: the held request (on y), or 403 E_DENIED with your reason

The gate holds a request for 60 s. If nobody answered by then, the agent gets 403 E_PENDING and the item stays on the console; once you approve, the same request (same fingerprint) goes through within 10 minutes, once. Without a console, an ASK is refused at once with E_NO_CONSOLE, while FREE traffic continues on the last approved policy.

HTTPS, with or without decryption

Hosts in the policy’s splice list (clients that pin their certificates) and internal hosts are never decrypted: they are decided at the domain, and never in auto mode.

The Claude API is a relay

Rules and auto mode

The policy lives with the console, never in the project: the gate reads no policy file, it uses what the console serves. A rule applies to all containers or to one, never to an agent (an agent name is a claim, not an identity).

[[profiles.default.rules]]
id      = "github-api-read"
host    = "api.github.com"
methods = ["GET", "HEAD"]
verdict = "free"

[[profiles.default.rules]]
id        = "npm-audit"
container = "lea-ab12cd34ef"
host      = "registry.npmjs.org"
methods   = ["POST"]
path      = "/-/npm/v1/security/advisories/bulk"
verdict   = "auto"        # asks, but auto mode may answer
max_body  = "256KiB"

A rule shape from the design document; the exact schema is settled with v0.1.0. Any loosening (a new host, a wider method or path, ask → auto → free, a wider scope) is confirmed by you in the console’s review. An auto rule is refused for uploads, messaging, registry publishing, git-receive-pack, spliced hosts, heuristic hits, secrets and production profiles.

Refusal codes

A refusal is a 403 with X-LockHTTP-Code and X-LockHTTP-Request headers and a text body saying why and what to ask. The codes are part of the protocol and never renamed.