🛬 Airlock — a deterministic egress gate for locked-down LLM agents

Give an LLM agent internet access without letting it roam or exfiltrate.

The usual options are bad: either you prompt the model "please don't leak data / only search Google" (unenforceable — one clever prompt and it's gone), or you hand it a raw browser tool (it can navigate anywhere and POST anything out). Airlock is the third option:

The agent can reason and ask Airlock to look something up — but the guarantees live in deterministic code the model cannot override. The LLM literally cannot widen the aperture.

Airlock is a small MCP server that enforces:

And it's self-healing: it drives a real, logged-in Chrome over CDP (survives the bot-walls headless scrapers hit), relaunches that Chrome if it dies, runs stateless (a restart never strands the client), and ships with a launchd plist for crash/reboot resilience.

The threat model it actually addresses

An autonomous agent with internet access is an exfiltration risk: prompt-injected content, a confused plan, or a jailbreak can turn "research this" into "POST our secrets to attacker.com." Airlock makes that structurally impossible for the agent — the only thing that ever leaves is a query string to one pre-approved domain, and the only thing that comes back is read-only result text. The locked-down agent holds no credentials and has no other network path.

  locked-down LLM agent ──(asks)──► Airlock (deterministic MCP) ──► ONE allowed domain
        ▲                                  │
        └────────── raw results ◄──────────┘   (one-way; status-only audit)

Related MCP server: MCP Internet Server

Quickstart

pip install -r requirements.txt
playwright install chromium    # or use your system Chrome (default)

# 1. Launch the dedicated, logged-in Chrome ONCE (sign in to whatever you need, then leave it):
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 --user-data-dir="$HOME/airlock-chrome-profile"

# 2. Run Airlock
python airlock.py

Register it with your MCP client (e.g. an OpenClaw/Claude agent) as a streamable-http server at http://host.docker.internal:9100/mcp/ (or localhost if not containerized), and scope it to the one agent allowed to do research. Tools: gate_status, search, fetch_page.

Configuration (env)

See .env.example. Always-on via launchd: com.airlock.gate.plist.

Hard-won lessons baked in

• Stateless MCP is mandatory. Streamable-HTTP MCP ties sessions to the process; restart the gate and the client dies with Session not found (-32600). Fix: mcp.run(..., stateless_http=True) — and pass it to run(), not the FastMCP(...) constructor (constructor kwargs are deprecated and crash older versions — a nasty silent footgun).

• Self-heal your dependency. A gate whose browser quit is just "down." Airlock relaunches its own Chrome (subprocess.Popen(start_new_session=True)) so a closed window recovers with no human.

• Drive a real logged-in browser, not headless. Real profile over CDP sails past the bot-walls that block headless scrapers — and keeps you logged in to whatever you need.

• Put guarantees in code, not prompts. "Don't exfiltrate" in a system prompt is a suggestion. A single hard-coded egress domain + fail-closed checks is a guarantee.

Built by

Built by KodeKing · author Fazal Shah. We build local, private, multi-agent AI systems for teams who can't send their data to the cloud. Issues and PRs welcome.

License

MIT — see LICENSE.

Author and engineering notes

Published by Fazal Shah. Explore my local AI experiments, Mac hardware test notes, agent engineering articles, and public tools on my personal website.

All public repositories · YouTube builds and walkthroughs