Skip to content
DavidGodefroidPublic

About

Harness security for AI agents, for outbound HTTP(S): a Lock of the Lock Family. An egress gate with approvals in lox run and proxy-side credential injection.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

lockhttp: your agent browses. You hold the key.

CI Latest release License: Apache 2.0 Go version

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.

An agent (here Claude Code, in a lea container) fetches a page of pkg.go.dev, a trusted host: the lockhttp gate lets the GET through at once. It then POSTs a build report to hooks.example.net, an unknown host: the gate holds the request, and a question shows in lox run, in your own terminal. You press d to read the whole masked screen (the author's email shows as j***(23)), then n to deny; the agent gets a 403 E_DENIED, denied on the hub, and the gate's audit records both decisions.

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.

Why lockhttp

  • 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 NeverAuto ticket on lockhub, answered by a human in lox 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.

Install

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/lea

lockhttp 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 | sh

LEA_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.

Quick start

  1. In lea's projects directory, add the lock. lox add lockhttp asks only for its name, writes the policy and starts the console:

    cd ~/projects
    lox add lockhttp
  2. In a terminal of its own, outside lea and any agent, keep lox run open. Every held request shows up there:

    lox run
  3. Turn lockhttp on in lea's configuration, then restart lea. LEA_LOCKHTTP=1 lea is 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 doctor reports the gate's state.

  4. 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.

Highlights

👤 Never answered automatically
Every held request is a NeverAuto ticket: a human answers it. Only a free rule you confirmed lets a request pass unasked.

🔑 Credentials injected
A policy inject entry has the gate add an Authorization header from its own secrets file, on a decrypted request or plain HTTP to an internal host. The agent never holds the token.

🔁 LLM APIs checked as a relay
With TLS decryption, the Claude API's mcp_servers, code execution container, server tools other than web_search, and Files API wait for a human; plain messages, OAuth and body-less reads pass.

🧱 Fail closed
No console, or a policy that does not decode: asks are refused at once. Unknown source, an error while deciding: deny.

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).

How it works

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
  1. The agent's HTTP client sends every request to the gate. In lea the agent's container has no other route out.
  2. The gate decides each request with the policy the console serves it. It never reads a policy file.
  3. 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.
  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.

The full diagram, verdicts, refusal codes, the Claude API checks and the limits: docs/how-it-works.md.

Safety model

  • 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 :review in 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/messages body's mcp_servers). The console approves no request: it audits policy reviews.
  • Known limits. Without decryption a CONNECT opens reads and writes, and whoever can run docker can reach the console's container.

Every rule: docs/safety.md. Threat model: docs/security-model.md.

Documentation

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/.

The Lock Family

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 · Security · License

  • 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's docs-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.

About

Harness security for AI agents, for outbound HTTP(S): a Lock of the Lock Family. An egress gate with approvals in lox run and proxy-side credential injection.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages