airlock

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.

!CI !License !Platform !MCP

!Airlock demo

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.

<!-- Static fallback if the GIF doesn't render: -->

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_counter for collision-free unique numbers, set_note_if for compare-and-swap. Read-modify-write is race-free, not best-effort.
• announce presence — register_agent heartbeats; when an agent dies, its locks release and its waiters wake immediately.
• signal events — generation-counted signal_event / wait_for_event for 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

| Tool | Args | Returns | |------|------|---------| | lock_resource | name, agent_id, ttl_seconds?=900, wait_seconds?=0 (cap 50), wake_token? | {locked:true, lock_token, expires_in_seconds} — or, if contended, {locked:false, held_by, expires_in_seconds} plus {wake_token, queue_position, retry_with} when you were queued | | unlock_resource | name, lock_token (preferred) or agent_id | {released: bool} | | renew_lock | name, lock_token (preferred) or agent_id, ttl_seconds?=900 | {renewed:true, expires_in_seconds} or {renewed:false, error} | | list_locks | — | [{name, agent_id, expires_in_seconds}] | | lock_resources | names:[string], agent_id, ttl_seconds?=900 | all-or-nothing: {locked:true, tokens:{name:token}} or {locked:false, held_by} |

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

| Tool | Args | Returns | |------|------|---------| | set_note | key, value, author?, ttl_seconds? | {saved:true} | | get_note | key | {key, value, author?, expires_in_seconds?} or {found:false} | | list_notes | — | [{key, value, author?, expires_in_seconds?}] | | delete_note (v2) | key | {deleted: bool} | | set_note_if (v2) | key, expected_value, new_value, author?, ttl_seconds? | {swapped: bool} (true only if the stored value equaled expected_value; an absent/expired note counts as "") | | increment_counter (v2) | name, by?=1 | {value} (post-increment; collision-free under concurrency) |

Presence

| Tool | Args | Returns | |------|------|---------| | register_agent (v2) | agent_id, ttl_seconds?=60 | {registered:true, expires_in_seconds} — re-call to stay alive; when it lapses the agent's locks auto-release | | unregister_agent (v2) | agent_id | {unregistered:true} — also releases held locks | | list_agents (v2) | — | [{agent_id, expires_in_seconds}] |

Events

| Tool | Args | Returns | |------|------|---------| | signal_event (v2) | name | {generation} (the new, bumped generation; wakes all waiters) | | wait_for_event (v2) | name, last_seen_generation?=0, wait_seconds?=25 (cap 50) | {generation, fired} — blocks until the generation advances past last_seen_generation, or the window expires (fired:false) | | clear_event (v2) | name | {cleared:true} |

Events are generation-counted, not latched: pass back the generation you last saw and a signal that fired between calls is never missed.

Tasks

| Tool | Args | Returns | |------|------|---------| | push_task (v2) | queue, payload, author?, priority?=0 | {id} (higher priority / older claimed first) | | claim_next_task (v2) | queue, agent_id, lease_seconds?=120 | {claimed:true, id, payload, lease_token} or {claimed:false} | | complete_task (v2) | id, lease_token | {completed: bool} | | fail_task (v2) | id, lease_token, requeue?=true | {failed: bool} (requeue=true returns it to pending; false gives up) | | list_tasks (v2) | queue | [{id, queue, payload, priority, state, author?, lease_agent?, lease_expires_in_seconds?}] |

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 makes increment_counter and set_note_if correct for free.
• Blocking waits. A parked waiter is a goroutine on a per-resource in-memory FIFO channel with a context deadline — 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_token gate unlock/renew and complete/fail. agent_id is provenance, not authorization.
• Security. Loopback-only bind, Host-header allowlist, reject any Origin header (DNS-rebinding defense), require application/json on POST — plus a 0600 bearer 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.