lockhttp

Let your AI agents use the web
without letting them send anything out behind your back.

Quick start · How it works · Security model · Configuration · Install · Docs · Website

LockHTTP is the proxy every outbound HTTP(S) request of an AI agent goes through. Reads of hosts you trust pass. Anything that sends data, triggers an action or reaches an unknown host waits for your approval, in a console that runs on the host under its own account, where the agent cannot reach it. Every decision is traced to the container, the agent and the session that asked.

[!NOTE] Pre-release (v0.1.0). Built on lockkit v0.2.1. Design decisions: docs/decisions.md.

Why LockHTTP?

An agent that can read the web can also write to it: a POST to a webhook, a git push, a package publish, a secret tucked into a query string, a Claude API call that hands an MCP server to the model. An allowlist of domains does not tell these apart from a documentation read, and approval prompts inside the agent's own process can be configured away by that process.

LockHTTP moves the decision out of the agent and onto the network path:

How it works

Three pieces, in three places. Only the console decides what needs a human, and only the human answers.

 agent container  (internal network only, no route out)
   HTTP(S)_PROXY=http://<agent>:<token>@lea-proxy:3130
          │
          ▼
 proxy container
   lockhttp gate :3130   (uid 10003, never root)  ──▶  squid 127.0.0.1:3128  ──▶  Internet
   lockhttp signer       (uid 10004, holds the CA key; only with decryption)
          │  Unix socket /run/lockhttp/user-<profile>.sock
          │  (bind-mounted in the proxy container only; peer uid checked by the kernel)
          ▼
 host
   lockhttp console      (account "lockhttp", its own login session, your terminal)
     reads the policy file · shows approval screens · audits

1. The agent's HTTP client sends every request to the gate, a Go HTTP(S) proxy. In lea the agent's container has no other route out: the proxy variables are a convenience, the network is the boundary.
2. The gate decides each request with the policy the console serves it (policy.get, polled every 2 s). It never reads a policy file.
3. A request that is free goes out through squid, which keeps its own floor (DoH, IP literals, private ranges, ports). A request that needs a human is held (60 s by default) while the console shows you an approval screen.
4. 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 CONNECT at the domain only (see Limits).

Verdicts

What an ASK becomes depends on what the gate sees:

• A CONNECT decided at the domain (no decryption, or a spliced or internal host): y opens container × host × port for connect_grant (10 minutes by default), for reads and writes, content unseen. The screen says so.
• A decrypted or plain HTTP request: y approves that request. If the agent's client already gave up (hold time passed, E_PENDING), y creates a single-use authorisation for the identical request, valid 10 minutes.
• Durable openings are policy rules, which you write and confirm in the console's :review.

Requests are approved one at a time. Requests of identical fingerprint (container, method, URL, media type, every end-to-end header, normalised body) share one screen and one decision; a request to the same URL with another body is a separate screen.

Quick start with lea

lea runs the gate in its proxy container when LEA_LOCKHTTP=1. The contract between the two (files, mounts, uids, network rules) is in docs/lea.md.

# 1. Install the binary (see Install), then separate the console from lea's account
sudo lockhttp install --client "$USER" --gate-uid 10003            # Docker rootful
sudo lockhttp install --client "$USER" --gate-uid 10003 --rootless # rootless Podman
sudo passwd lockhttp

# 2. Log in as "lockhttp" in its own session (switch user), then:
lockhttp init --trusted "<LEA_EGRESS_ALLOW>"  # the policy; lea's allowlist as trusted reads
lockhttp console                               # keep it open: it asks you

# 3. Back in your session: start lea with LockHTTP on
export LEA_LOCKHTTP=1
lockhttp doctor                                # as lockhttp: setup, policy, CA

--gate-uid is the gate's uid inside the proxy container. The console authenticates the gate by the uid the host kernel reports, so under rootless Podman --rootless maps it through /etc/subuid.

Quick start standalone (one host)

Without lea, the gate runs on the host, as another account than the console's (it refuses to run as root). Every connection is attributed to the container local.

# Once
sudo lockhttp install --client "$USER"
sudo passwd lockhttp

# As "lockhttp", in its own login session
lockhttp init
lockhttp console

# As you
lockhttp gate --listen 127.0.0.1:3130 --audit-dir ~/.local/state/lockhttp-gate
HTTPS_PROXY=http://127.0.0.1:3130 HTTP_PROXY=http://127.0.0.1:3130 your-agent

In this setup the proxy variables are the only thing that sends the agent through the gate: an agent that ignores them goes straight out. Standalone mode is useful to try the policy and the console; it is a boundary only if the agent's sole route to the network is the gate.

Install

V=v0.1.0
curl -fsSLO "https://raw.githubusercontent.com/DavidGodefroid/lockhttp/$V/scripts/install.sh"
less install.sh
LOCKHTTP_VERSION=$V sh install.sh

scripts/install.sh downloads the release archive for Linux or macOS (amd64, arm64), verifies the keyless cosign signature of checksums.txt against this repository's release workflow, checks the archive, and places lockhttp in /usr/local/bin (LOCKHTTP_INSTALL_DIR to change it). It refuses to install without cosign unless LOCKHTTP_SKIP_COSIGN=1.

Then, once per host:

Build from source: CGO_ENABLED=0 go build ./cmd/lockhttp (Go 1.26 or later).

Every command and flag: docs/usage.md.

Configuration

The policy lives in the console account's ~/.config/lockhttp/config.toml, one table per profile. The console reads it, reloads it when it changes, and holds every change that loosens it until you confirm it with :review. Unknown keys and keys that look like secrets are refused.

[profiles.default]
mode          = "enforce"   # enforce | shadow
heuristics    = "shadow"    # off | shadow | enforce
buffer_limit  = "10MiB"     # largest body held for a human
hold          = "60s"       # how long a request waits for the human (max 5m)
connect_grant = "10m"       # how long an approved CONNECT opens its host
trusted = ["go.dev", "pkg.go.dev", "github.com", "api.github.com"]
splice  = []                # never decrypted (certificate pinning)
deny    = []                # always refused

Hosts are names: example.com, or *.example.com for its subdomains (not example.com itself). IP literals are refused. The full reference, with the evaluation order and what counts as a loosening, is in docs/policy.md.

Policy examples

[profiles.default]
trusted = ["docs.rs", "*.readthedocs.io"]       # free reads of docs
splice  = ["pinned.example.com"]                # a client that pins its certificate
deny    = ["pastebin.com"]

# A container-scoped rule that auto mode may answer
[[profiles.default.rules]]
id        = "npm-audit"
container = "lea-ab12cd34ef"
host      = "registry.npmjs.org"
methods   = ["POST"]
path      = "/-/npm/v1/security/advisories/bulk"
verdict   = "auto"
max_body  = "256KiB"
expires   = "2026-12-31"

# Every write under an API path asks (NeverAuto), even on a trusted host
[[profiles.default.rules]]
id      = "issues-write"
host    = "api.github.com"
methods = ["POST", "PATCH"]
path    = "/repos/acme/shop/issues*"
verdict = "ask"

# Refuse a host for every container
[[profiles.default.rules]]
id      = "no-gists"
host    = "gist.github.com"
verdict = "deny"

# An internal host on a private address: free reads on 8443
[[profiles.default.internal_hosts]]
host  = "git.corp.example"
ports = [8443]
read  = true

To try a policy before enforcing it, set mode = "shadow": what would ask or be denied passes and is audited with "decision": "shadow-ask" or "shadow-deny". The floor and secret matches stay enforced.

What the agent sees

A refusal is a 403 Forbidden with a plain-text body that says why and what to ask of the human, and two headers: X-LockHTTP-Code and X-LockHTTP-Request (the id to find in the console and the audit). For a CONNECT it is the CONNECT's own response, which clients show as a proxy error. A forwarded response carries X-LockHTTP-Request too (decrypted or plain HTTP); a target the gate cannot reach is a 502.

E_HOST_UNKNOWN, E_CLAUDE_API_PARAM, E_EXFIL_SUSPECT, E_METHOD and E_PINNED are registered codes too; in v0.1.0 a refused ASK reaches the agent as E_DENIED, E_TIMEOUT, E_PENDING or E_NO_CONSOLE, and E_PINNED appears in the gate's audit only (a client that rejects the gate's certificate closes the connection before any response).

Claude API allowlist

The four hosts Claude Code reaches (api.anthropic.com, claude.ai, console.anthropic.com, statsig.anthropic.com) are free at the domain. Any other host under anthropic.com, claude.ai or claude.com asks (NeverAuto), unless a rule says otherwise.

Once TLS is decrypted, the Claude API is a generic relay and is checked per request:

Duplicate keys, and keys that differ from mcp_servers, tools or container only by case, make the body ambiguous: it asks.

Security model

The gate is the enforcement point on the network path; the console is the only place a human decision is made. In short:

• The console is on the host, in a separate account. lockhttp console runs as lockhttp, in its own login session; lockkit refuses a console in the agent's account or in a container. Its socket is reachable only by the lockhttp-clients group and the uids in allowed_uids (the gate's), checked with the kernel's peer credentials, and it is bind-mounted in the proxy container only, never in an agent's.
• NeverAuto by default. Every approval screen is NeverAuto unless the request matched an active rule with verdict = "auto". Such a rule names a container or none, never an agent, and is refused on messaging hosts, registry publishing, git-receive-pack, a write to any path of a git forge, spliced hosts, every-host rules and production profiles. At run time uploads, messaging, publishing, git pushes, WebSockets, CONNECTs, red screens and heuristic hits stay NeverAuto; secrets are denied. The console re-checks the gate's claim against its own approved policy (rule id, active, auto, host, method, path, container, max_body) before auto mode may answer.
• A decision is shared only by identical requests. Same container, method, URL, significant headers and normalised body; anything else is its own screen.
• Fail closed. No console: every ASK is refused at once (E_NO_CONSOLE), while FREE goes on with the last policy the console served. Unknown source, unreadable source map: refused. An unreadable credentials file: every Claude credential is denied. A policy whose fingerprint does not match: the previous one is kept.
• The gate never reads a policy. It uses what the console serves, and checks it against the console's fingerprint.
• The signer holds the CA key. The gate asks lockhttp signer for a 24-hour leaf per host, over a Unix socket restricted to allowed uids; it never sees the CA key.
• The AI tightens, the human loosens. Any change that widens what passes without a human (a trusted host, a free or auto rule, shadow mode, a longer grant, a removed deny...) waits for your :review.
• Traced. The gate's JSONL audit and the console's audit carry request_id, container, agent, attribution, via, never a body, a query string or a header value.

Threats, parades and residual risks: docs/security-model.md.

Limits

• Without decryption, a CONNECT opens reads AND writes. A trusted host is free at the domain, and an approved CONNECT opens its host for connect_grant; the gate does not see what goes through. Rules with methods or path cannot apply at the domain. The Claude API allowlist needs decryption too. lockhttp doctor warns when no CA is given.
• HTTP/1.1 only to clients when decrypting. The gate offers ALPN http/1.1; it does not speak HTTP/2 to clients, and refuses Upgrade: h2c.
• A WebSocket session is one approval. The upgrade request is decided; the frames that follow are not.
• Heuristics run in shadow by default. The exfiltration score is logged, not enforced, until you set heuristics = "enforce".
• One human per installation, one approval at a time. The console is serial; the gate queues its asks.
• The agent name is declarative. The container is read from the network the connection arrived on; the agent name comes from Proxy-Authorization and is for the audit only. Agents of one container share a uid, so rules scope to containers, never to agents.
• Standalone mode is not a boundary unless the agent's only route out is the gate.
• No MCP server in v0.1.0: agents meet LockHTTP as a proxy, and its 403 pages tell them what to ask of the human.

The Lock family

LockHTTP is one of a family of human-gated tools for AI agents, built on the same console, separation and approval model:

Website: lockhttp.com.

Documentation

Licence

Apache License 2.0. See LICENSE and NOTICE.