Airlock
Run five agents on one repo without them stomping on each other.
Named resource locks, atomic shared state, presence, events, and a task queue for AI agents — exposed over a local HTTP MCP server that's always running, so any session, terminal, or CI job can coordinate with any other. Cross-platform Go daemon, SQLite-backed, with real blocking waits — no more poll loops.
Two agents reach for the same npm-install lock — one wins, the other blocks on a server-side wait and acquires the instant the first releases.
Agent A Agent B
────── ──────
lock_resource("npm-install") lock_resource("npm-install", wait_seconds=50)
→ { locked: true, lock_token } (parked — the daemon holds the connection open)
npm install ...
unlock_resource(lock_token)
→ { locked: true, lock_token } ← wakes instantly
npm install ...
The problem
Open two Claude Code sessions on the same repo — one adding auth, one adding notifications. Both reach for npm install at the same time. Both pick 003_ as the next migration filename. Neither knows the other exists.
There's no shared state. No handoff. No way for one agent to know what another is doing. Coordination lives in fragile prompt instructions ("please wait until migrations finish") that nothing enforces.
How it works
Airlock is a single Go daemon that runs as a background service — always on, surviving IDE and terminal restarts. It listens on 127.0.0.1:27183 and speaks MCP over HTTP. Any agent that has it configured can:
- acquire locks — and block on a contended one (
wait_seconds, up to 50s), so the daemon parks the caller and wakes it the instant the lock frees. No agent-authored retry loops. - share atomic state —
increment_counterfor collision-free unique numbers,set_note_iffor compare-and-swap. Read-modify-write is race-free, not best-effort. - announce presence —
register_agentheartbeats; when an agent dies, its locks release and its waiters wake immediately. - signal events — generation-counted
signal_event/wait_for_eventfor handoffs without polling. - queue work — a small task queue with presence-bound leases that auto-requeue on crash.
State lives in SQLite (WAL mode) at ~/.airlock/state.db — transactional, crash-safe, with concurrent readers and a single writer. The store is pure-Go (modernc.org/sqlite, no cgo), which is what makes the Linux build a trivial cross-compile. One binary, no language runtime, no external database.
Install
(a) go install
go install github.com/adamorad/airlock/v2@latest # builds the `airlock` binary
airlock install-service # launchd (macOS) / systemd user unit (Linux)
(b) Homebrew
brew install adamorad/tap/airlock
airlock install-service
(c) Build from source
git clone https://github.com/adamorad/airlock.git
cd airlock
go build -o airlock .
sudo install airlock /usr/local/bin/airlock # or anywhere on your PATH
airlock install-service
install-service registers an always-on background service (and unloads the old v1 LaunchAgent if present, so the v2 daemon takes port 27183 cleanly).
Verify
airlock status
# Airlock — 127.0.0.1:27183
#
# LOCKS (0)
# (none)
# ...
Configure your agent
Claude Code — one command:
claude mcp add --transport http airlock http://localhost:27183
Cursor / Windsurf / any MCP client — add this to your MCP config:
{
"mcpServers": {
"airlock": {
"type": "http",
"url": "http://127.0.0.1:27183"
}
}
}
On Linux (and any multi-user host) a bearer token is required — loopback is shared across all users there, so it isn't an authorization boundary on its own. The daemon writes a 0600 token to ~/.airlock/token on first run; send it as an Authorization: Bearer <token> header:
{
"mcpServers": {
"airlock": {
"type": "http",
"url": "http://127.0.0.1:27183",
"headers": { "Authorization": "Bearer <paste contents of ~/.airlock/token>" }
}
}
}
On macOS the daemon is loopback-only by default and the token is optional. AIRLOCK_TOKEN overrides the file on any OS.
Tools
Airlock exposes 22 tools over MCP. Every tool result is a JSON object (the list_* tools return a JSON array). TTLs are in ttl_seconds; ttl_minutes is accepted as a deprecated alias.
Locks
wait_seconds is the coordination-by-default knob: pass it (up to 50) and lock_resource blocks server-side until the lock frees, instead of returning locked:false immediately. The cap stays under Claude Code's 60s default per-tool-call timeout. The returned lock_token is a capability — unlock_resource/renew_lock require it (the agent_id path is kept for v1 compatibility). lock_resources acquires in a documented lock-ordering (lexicographic by name) so two callers can't deadlock.
Notes & State
Presence
Events
Events are generation-counted, not latched: pass back the generation you last saw and a signal that fired between calls is never missed.
Tasks
A claim is a lease: if the claimant doesn't complete_task/fail_task within lease_seconds, the task auto-requeues for another consumer — no work is lost to a crashed worker. The lease_token from claim_next_task is the capability complete_task/fail_task require.
Naming conventions
Use consistent names so agents understand each other:
- Files:
file:/abs/path/to/package.json - Processes:
npm-install,db-migrations,tests:unit - Agent identity:
agent:claude-session-abc
Recipes
(a) Serialize edits to one file with a blocking lock
Two subagents both need to edit package.json. They serialize on a single lock — the second one blocks (no retry loop) and wakes the instant the first releases.
# Subagent A — block up to 50s to acquire, edit, release.
A=$(curl -s -X POST localhost:27183 -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"lock_resource","arguments":{"name":"file:/repo/package.json","agent_id":"sub-A","wait_seconds":50}}}' \
| jq -r '.result.content[0].text | fromjson | .lock_token')
# ...edit the file...
curl -s -X POST localhost:27183 -H 'Content-Type: application/json' \
-d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"unlock_resource\",\"arguments\":{\"name\":\"file:/repo/package.json\",\"lock_token\":\"$A\"}}}" \
| jq -c '.result.content[0].text | fromjson' # → {"released":true}
# Subagent B — the same call with wait_seconds=50 parks until A releases, then
# returns {locked:true, lock_token} the moment the lock frees. No polling.
(b) Unique migration filenames — race-free
The classic v1 hazard: two agents get_note the counter at the same instant, both read 003, both write 004. In v2 there is no read-modify-write to lose — increment_counter is atomic, so 100 concurrent callers get 100 distinct numbers.
curl -s -X POST localhost:27183 -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"increment_counter","arguments":{"name":"migration-seq"}}}' \
| jq -c '.result.content[0].text | fromjson' # → {"value":4}
# Use the returned value: create 0004_*.sql. The next caller gets 5, never a collision.
(c) Producer/consumer handoff via the task queue
A planner agent pushes work; one or more worker agents claim it. A lease means a crashed worker's task auto-requeues instead of vanishing.
# Producer — enqueue a unit of work.
curl -s -X POST localhost:27183 -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"push_task","arguments":{"queue":"build","payload":"compile module X","author":"planner"}}}' \
| jq -c '.result.content[0].text | fromjson' # → {"id":1}
# Consumer — claim the next task, do the work, complete it with the lease token.
CLAIM=$(curl -s -X POST localhost:27183 -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"claim_next_task","arguments":{"queue":"build","agent_id":"worker-1"}}}' \
| jq -c '.result.content[0].text | fromjson') # → {"claimed":true,"id":1,"payload":"compile module X","lease_token":"..."}
ID=$(echo "$CLAIM" | jq -r .id); TOK=$(echo "$CLAIM" | jq -r .lease_token)
# ...do the work...
curl -s -X POST localhost:27183 -H 'Content-Type: application/json' \
-d "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"complete_task\",\"arguments\":{\"id\":$ID,\"lease_token\":\"$TOK\"}}}" \
| jq -c '.result.content[0].text | fromjson' # → {"completed":true}
airlock status
One-shot snapshot of everything the daemon is coordinating — locks (and who holds them), present agents, notes, counters, events, and tasks. Runs against ~/.airlock/state.db, so it works even from a different shell. airlock watch reprints it live once a second.
Airlock — 127.0.0.1:27183
LOCKS (2)
NAME HELD BY EXPIRES IN
file:/repo/package.json sub-A 4m30s
npm-install session-A 12m
AGENTS (2)
AGENT EXPIRES IN
session-A 48s
worker-1 59s
NOTES (1)
KEY VALUE AUTHOR EXPIRES IN
deploy-status building planner —
COUNTERS (1)
NAME VALUE
migration-seq 4
EVENTS (1)
NAME GENERATION
migrations-done 2
TASKS (1)
ID QUEUE STATE PAYLOAD LEASE AGENT
2 build claimed compile module Y worker-1
Architecture
A single Go daemon, one process, on 127.0.0.1:27183.
- Store. SQLite in WAL mode at
~/.airlock/state.db— pure-Go (modernc.org/sqlite, no cgo), transactional, crash-safe. A single dedicated write connection serializes writes; readers use the WAL's concurrent path. SQLite's single-writer model is what makesincrement_counterandset_note_ifcorrect for free. - Blocking waits. A parked waiter is a goroutine on a per-resource in-memory FIFO channel with a
contextdeadline — outside any SQLite transaction, so a blocking daemon never melts the database under contention. A background reaper sweeps expired lock TTLs and presence leases and wakes the FIFO head, so waiters behind a dead holder don't eat their full wait window. - Capability tokens.
lock_token/lease_tokengateunlock/renewandcomplete/fail.agent_idis provenance, not authorization. - Security. Loopback-only bind,
Host-header allowlist, reject anyOriginheader (DNS-rebinding defense), requireapplication/jsonon POST — plus a0600bearer token at~/.airlock/token, required on Linux/multi-user hosts. See SECURITY.md. - Port 27183. PortPeek owns
27182(the digits of e); Airlock takes the next port so the two daemons coexist.
v1 (Swift, macOS-only) is archived at legacy/swift/ and tagged v1.1.0. The full v1 wire contract still works unchanged on v2 — same port, same JSON.
Roadmap / v2 status
v2.0.0 ships the core — locks with blocking waits, atomic state, presence, and events — plus the task queue, all in Go and cross-platform (macOS + Linux). The design spec and rationale, including how Airlock sits against adjacent tools, live in docs/ROADMAP-v2.md. If the roadmap is wrong for your workflow, open an issue — there's a pinned "tear this apart" thread for exactly that.
Uninstall
airlock uninstall-service # remove the launchd / systemd service
brew uninstall airlock # if installed via the tap: brew uninstall adamorad/tap/airlock
rm -rf ~/.airlock # optional: drop the state db + token
FAQ
Why port 27183? PortPeek already uses 27182 (the first digits of e, Euler's number). Airlock takes the next port, 27183, so the two daemons coexist on one machine without colliding.
What's the security model? Airlock binds loopback only, validates the Host header, rejects any Origin header, and requires application/json on POST. On Linux/multi-user hosts a 0600 bearer token at ~/.airlock/token is required (loopback is shared across users there); on macOS it's optional. Capability tokens (lock_token / lease_token) mean a buggy or prompt-injected agent can't drop or steal another agent's lock just by guessing its agent_id. The deliberate, documented limit: any process running as the same local user can call the API — Airlock coordinates cooperating agents, it doesn't sandbox them. Note/task content is untrusted cross-agent input; consuming agents must treat it as data, never instructions. Full threat model: SECURITY.md.
How does it relate to PortPeek? PortPeek solves port conflicts for AI agents (who's bound to which port). Airlock solves the broader coordination problem (who's doing which task). Same lineage, adjacent ports (27182 / 27183), designed to run side by side.
Contributing
Issues and PRs welcome — see CONTRIBUTING.md.
Licensed under the MIT License.
Built by Adam Morad.