One hardened container per project for AI coding agents, with parallel git worktrees
and patch reviews from Gerrit, GitHub, GitLab or Bitbucket. Nothing on your machine
but Docker. Run airlock in a project folder and it starts (or resumes) a dedicated
container for that project and attaches you to it, with Pi and
Herdr ready to work.
Agents work freely inside the box. By default they cannot reach your home directory, your local network, your git credentials or the Docker socket. They can reach the internet, so anything they can read in the project they could also send out: airlock limits the damage to what you put in the box, it does not make a compromised agent harmless (see Security model).
Status: early. The core is implemented, covered by automated tests (below) and used daily on Linux and macOS (Docker Desktop). Some features from the design are not built yet; see What is not there yet.
You need Docker (Engine, Docker Desktop, OrbStack or Colima) running.
Linux and macOS, one line (checks the download against the release checksums):
curl -fsSL https://raw.githubusercontent.com/alexghirelli/airlock/main/install.sh | shIt installs airlock into ~/.local/bin (set AIRLOCK_INSTALL_DIR to change that,
AIRLOCK_VERSION=v0.1.0 to pin a release) and tells you if that folder is not in
your PATH. To read the script before running it, open
install.sh first.
Manually: download the archive for your system from the
Releases page, check it with
sha256sum -c --ignore-missing SHA256SUMS, and put airlock somewhere in your PATH.
On Windows, use the .zip, preferably from inside WSL2 (see
airlock doctor for the trade-offs).
With Go: go install github.com/alexghirelli/airlock/cmd/airlock@latest.
From source: go build -o airlock ./cmd/airlock in a clone of the repository.
The first airlock in any project downloads the base image (about 300 MB, a few
seconds to a minute; it is published to GHCR for every release, for amd64 and
arm64) and every later project reuses it. The image has Pi, Herdr and mise and
nothing proprietary: other agents are installed on your machine, by their own
installers, the first time you use them (see Agents).
If the download fails, or for a development build,
airlock builds the image locally instead (about two minutes, 1.3 GB). Set
AIRLOCK_BUILD_LOCAL=1 to always build locally, and airlock build to do it now.
cd ~/projects/my-app
airlock # first run builds the imageInside, Herdr opens with Pi running in the project's workspace. Close the terminal
at any time: the sandbox and its agents keep running, and airlock reattaches.
New to airlock? airlock init in the project folder reads what the project uses and
writes a starter .airlock.toml (see Starting a project).
airlock [path] start or resume the sandbox for a project and attach
airlock shell [path] open a shell in it
airlock exec [path] -- cmd run a command in it
airlock stop|rm [path] stop it (tools stay) / delete it (--purge: and its own logins)
airlock wt add|open|focus|handoff|rm | airlock review <change> worktrees and Gerrit reviews
airlock summary [worktree] what a worktree changed, before you trust or merge it (--json)
airlock ls list sandboxes
airlock inbox [--watch] the agents that need you, across sandboxes (--watch: notify)
airlock gc [--force] list (--force: remove) what deleted projects and old releases left behind
airlock login log in to the providers named in your config
airlock audit [path] report changes to files that run on your computer
airlock doctor check the runtime, the firewall and the setup
airlock build | update build the image / rebuild it from scratch
airlock init [path] write this project's .airlock.toml from what it uses
airlock config init|show|path|edit your user config (init is per project, config init is yours)
airlock remote push|pull|open <host> [path] move the project to a server with git (see below)
airlock --remote <ssh-host> <command> run a command on a server over ssh
- One container per project (
airlock-<name>-<hash>), persistent by default. - The project is mounted at the same absolute path as on the host, so git worktrees (which store absolute paths) work from both sides. Files you and the agent create are owned by you.
- Git worktrees share the project's sandbox, each as a Herdr workspace, or get a sandbox of their own (see Worktrees).
- Network
open-no-lan(default): the internet works; your computer, your LAN, link-local/metadata addresses and other sandboxes are blocked by a firewall that the agent cannot change (see Security model). sudoworks inside, so agents canapt installand usemisefor Node/Python/Go/Ruby. Installed tools persist untilairlock rm.- Pi and Claude Code logins and settings live in a Docker volume, shared by all projects
(
credentials.scope = "shared"), per project, or per account profile.airlock rmkeeps the volume, so a recreated sandbox stays logged in;airlock rm --purgedeletes a per-project one.
Work on several branches at once, one git worktree each, and review Gerrit patches next to your own feature. By default every worktree shows up as a Herdr workspace in the same session, so you switch between them without opening terminals.
airlock wt add rate-limit "rate limiting of the API, only src/api/"
airlock review 12345 # a Gerrit change, a GitHub pull request or a GitLab merge request
airlock review https://github.com/acme/widgets/pull/321 # also GitLab merge requests and Bitbucket pull requests
airlock review https://gerrit.example.org/r/c/core/+/12345/3 "check the SQL"
airlock wt # worktrees, branches, changes, sandboxes, focus
airlock wt open rate-limit # come back to one
airlock wt focus rate-limit "now: the tests" # change what its agent concentrates on
airlock wt handoff rate-limit "start at the retry path" # a new agent takes over, with a briefing
airlock wt rm review-12345 # remove the worktree, keep the branch
airlock wt prune # list worktrees whose folder you deleted by hand (--force forgets them)
airlock wt link # link the paths of sandbox.worktree_link into worktrees (see Settings for one project)addcreates the worktree under.worktrees/(git-excluded) on a new branch fromHEAD(-bto name it or use an existing or remote branch,--fromto start elsewhere).reviewtakes a Gerrit change, a GitHub pull request or a GitLab merge request. It fetches the ref the server publishes for it (refs/changes/NN/N/P,refs/pull/N/head,refs/merge-requests/N/head,refs/pull-requests/N/from) on the host, where your git credentials are: it needs no API and no token, only a remote that git can already reach. It checks the result out on a local branch (review/12345,review/pr-321,review/mr-45,review/bb-7), so a review can include changes of your own. Run it again and the branch moves to the newest patchset or head, unless that would lose uncommitted changes or local commits: then it says so and prints thegit rebase --ontoto run.- What you can give it: the URL of the change (it picks the remote that points at that
repository, so a pull request against
upstreamworks from a fork); a number (12345, or12345/3for a Gerrit patchset), which airlock looks up ongerrit,originandupstreamin turn, asking each which kind of change that number is; orpr:12,mr:12,bb:7,gerrit:12345when a number exists as more than one kind. Gitea and Forgejo pull requests work like GitHub's. Bitbucket means Server / Data Center; Bitbucket Cloud does not publish pull requests as git refs, so airlock says so and points towt add -b <branch>.git.review_remotepins the remote (git.gerrit_remotedoes the same for Gerrit only). - Both start the sandbox and attach. If another terminal already has Herdr open on
that sandbox, they stay quiet instead: the new workspace appears there, without taking
its focus, and nothing attaches (
airlock wt open <name>brings you to it).--attachattaches anyway,--no-attachnever does. airlock knows because theairlockprocess holding that terminal leaves a small file in its cache folder, which dies with the terminal; a Herdr left behind inside the sandbox by a closed window does not count. - A task per worktree. Text after the name or change is the worktree's focus.
A review also gets a task of its own, written from the fetched commit: what is under
review, the commit (by hash, so it holds even if the branch could not be moved), the
subject and the author, with the rules of a review (no push or merge, no edits unless asked,
findings by file) and a pointer to the forge's tools for the description and comments.
A pull or merge request can hold several commits and its target branch only exists on the
forge: the task gives a likely base (the merge-base with the remote's default branch) and
tells the agent to check it.
The agent reads both every time it starts in the worktree, so every new session there has
its scope, and
wt focusapplies to the next one. They are files of the host, in a folder of airlock's state (<cache>/airlock/tasks/<project>/<worktree>/), mounted read-only into the sandbox at/run/airlock/tasks/<worktree>/: they never show ingit status, and the agent cannot change them.wt rmdeletes the folder;wt prune(for a worktree deleted by hand) leaves it behind in the state folder. Task files from before this version, in the worktree's git directory, are not read: runairlock wt focus <name> "..."again to set the focus.
When an agent is stuck, has run out of context, or another model would do better, hand
the worktree over. The new agent (the same kind, or --agent claude / --agent pi)
starts fresh with a briefing instead of from nothing:
airlock wt handoff rate-limit "the retry path still fails: start there"
airlock wt handoff rate-limit --agent claude
airlock wt handoff rate-limit --reset # delete the briefing, do nothing else- It refuses while the previous agent is still working, and when the sandbox's agent list
cannot be read (
--forceoverrides both). The previous agent is the one Herdr lists in the worktree's folder; none there is fine. - The briefing is
handoff.mdin the worktree's task folder, next to the focus and the review (see above), so it never shows ingit status. It opens with airlock's instruction to check the state with git before changing anything, then your note, the transcript path of the previous conversation (inside the sandbox, read if its reasoning is needed), and whatairlock summarysays the worktree changed. Everything from the worktree is marked as data, not instructions. - The worktree's Herdr workspace is closed, the previous agent is confirmed gone, then the
briefing is written and a new agent starts in the worktree with
--fresh. The agent gets the briefing in its system prompt. An agent that is resumed later with--continuegets it too: the briefing is appended on every start, like the focus, until it is reset or replaced. A conversation continued later reads the same briefing again. - The briefing stays until the next handoff overwrites it,
airlock wt handoff <name> --resetdeletes it, or the worktree is removed. Until then every agent started in the worktree gets it, so run--resetwhen the handoff is over. - It needs the Herdr UI (
sandbox.ui = "herdr"). - Only one agent runs in a folder: while the new agent is in the worktree,
airlock wt opengoes to it, whatever its kind.--agentapplies to this handoff only. Once that agent is closed,wt openstarts the configured kind again, unless you pass--agentagain. - With
--agenta different kind than the configured one, airlock may print "the configuration changed since ... runairlock restart" when it brings the sandbox up. For the agent kind alone that is harmless: do not restart the sandbox for it. - Not tried end to end: there was no Docker to run the sandbox and Herdr in, so the listing
of agents, the closing and the fresh start in a real workspace have not run. The briefing,
the choice of previous agent, the refusal, the check after the close, the file handling, the wrappers and the one-agent-per-folder rule of
airlock-herdr-up(against a stub Herdr) are tested.
airlock summary rate-limit # commits past the base, files, uncommitted and untracked, focus
airlock summary # the same for the worktree or project you are in
airlock summary --json # the same data for scripts- The base is the branch's upstream if it has one, else the remote's default branch
(
origin/HEAD), else the first oforigin/main,origin/master,main,masterthat exists. A review branch has no upstream, so it uses the default branch. A pushed feature branch whose upstream is its own copy on the remote (git push -u origin feature) is not used as the base: the default branch is.git push -u origin feature:other-nameis not detected, so its base is that branch's own tip and only the uncommitted changes show. - Files are what
git diffshows against the merge-base: committed and uncommitted changes to tracked files, with added and deleted lines. Binary files are marked, not counted. Untracked files are listed (the first 50), not read. - It does not show the content of the changes (
git diff <base>does), whether the tests pass, or what the agent said. The audit line is project-wide, not about one worktree; it is read without recording a baseline, soairlock audit --acceptis still what acknowledges changes. - Everything it prints from the worktree (focus, commit subjects, names) is escaped, so an escape sequence or a bidi character in them does not reach your terminal.
A sandbox is the boundary, not a folder: agents in the same sandbox can read and write
each other's worktrees, and the project's untracked files (a config/local.php with
database credentials, say). That is fine for your own branches; it is a risk for a
patch from someone else, because instructions hidden in it may steer the agent that
reads it. So a worktree can have a sandbox of its own:
[sandbox]
worktree_isolation = "none" # none (default) | reviews | all| Value | wt add |
review |
|---|---|---|
none |
project sandbox, Herdr workspace | project sandbox, Herdr workspace |
reviews |
project sandbox | own sandbox |
all |
own sandbox | own sandbox |
--shared and --isolated override the setting for one worktree. An isolated worktree
lives in .worktrees/.isolated/, mounts only itself, the repository's .git
(hooks, config and its own config.worktree read-only) and its own task folder (read-only), and has its own terminal and
Herdr: the main checkout, its untracked files and every other worktree are not visible,
and a port used there does not clash with yours. The project's sandbox sees
.worktrees/.isolated/ as an empty read-only folder.
airlockrun inside a worktree resolves to the sandbox it belongs to; that meansairlock stop|rmin a shared worktree acts on the project's sandbox.- A worktree builds the main repository's configuration and project image, never its own: a patch under review cannot change how its own sandbox is built.
- Worktrees made by
airlock wtare locked, so agit worktree prunerun where they look missing (the project's sandbox does not see isolated ones) cannot forget them. - Agents can make worktrees under
.worktrees/themselves; they land in the project's sandbox. Isolated ones are made withairlock wton the host.
What worktrees still share is the git directory: objects, branches and tags. An agent in an isolated worktree can rewrite refs of other branches. It cannot read or change their files. See Security model.
Some projects are tested in a container you already run: a DDEV web container, a plain
container, or a docker compose service. A [[runner]] in your user config names one, and
airlock wt run runs a command in it, against a worktree. An example, with a
running container (recommended):
[[runner]]
name = "web"
container = "myapp-web-1" # docker ps lists it
mount = "/var/www/html" # where the project root is mounted in that container
# user = "501:20" # optional, passed as --userThe compose form works too: compose = "~/Sites/myapp/docker-compose.yml" (or a list
of files, each passed as its own -f, in order) with service = "web" instead of
container. With an explicit -f, docker compose does not load docker-compose.override.yml
by itself: list it. Only docker compose v2 is supported.
airlock wt run web rate-limit -- composer test -- tests/Unit/Foo
airlock wt run web . -- composer test # the main checkoutairlock maps the worktree to its place under the mount (here
/var/www/html/.worktrees/rate-limit) and runs the command there with docker. The
command goes as separate arguments after the container or service name, never through a
shell; the exit code is the command's. --print shows the docker command instead,
shell-quoted for pasting, and runs nothing. A project's .airlock.toml cannot define a
runner, and a worktree is only one that airlock made: a link or a folder without a .git
file in .worktrees/ is refused.
Some things to know when you use it:
- Ctrl-C reaches the container's command only when there is a terminal. Without one,
docker execdoes not forward it, and the process keeps running; airlock stops docker, which does not stop that process. - git inside the container does not work in a worktree, unless the host path of the
project equals
mount: the worktree's.gitfile holds the host's absolute path. Run git on the host. - The compose form is less safe. A compose file inside the project can be written by the
agent, and so can the
.envnext to it, which changes the compose project name:execthen reaches another project's container. airlock warns when a compose file is inside the project, and it still runs. Prefercontainer.
This runs on your computer, outside the sandbox, and the agent cannot start it: it has no
Docker socket. The worktree's code runs in that container, with the project's main checkout
mounted there read-write, so what the agent wrote can change every file of the project. Its
output is the container's and reaches your terminal unfiltered, escape sequences included,
so code in the worktree can print anything: write to your clipboard, change the window
title. Look at what the agent changed first (airlock summary <worktree>, airlock audit).
To let the agent run the tests itself, inside the sandbox, install what they need there
(extras.mise, extras.apt): it then runs them with its own changes, under the sandbox.
With several worktrees running agents at once, an agent that stopped on a question
waits until you look. airlock inbox lists the agents of every running sandbox, with
their worktree and status, blocked ones first:
PROJECT WORKTREE AGENT KIND STATUS
app review-pr-7 pi-review-pr-7 pi blocked
app - pi pi idle
airlock inbox --watch polls every 5 seconds and prints each status change with its time.
It notifies you when an agent is blocked or finishes (goes from working to done or idle).
An agent that is already blocked when the watch starts, or that appears blocked, is notified
too. The agents that need you in one poll make one notification: "pi-review-7 needs you",
or "3 agents need you". Ctrl-C stops it. A notification always rings the terminal bell;
it also shows a desktop notification (notify-send on Linux, osascript on macOS). To send
it somewhere else, set your own command in the user config. airlock appends the title and
the message to its arguments, with no shell in between:
[notify]
command = ["sh", "-c", "curl -s -d \"$2\" ntfy.sh/my-topic", "notify"] # ntfy.sh, to your phoneOnly your own configuration can set [notify] (your user config, or a settings file for
one project): a project's .airlock.toml cannot, because the command runs on your computer. With airlock --remote host inbox --watch the watch and its
notifications run on the remote machine, so they reach that machine's desktop or ntfy topic.
Each sandbox is asked with herdr agent list, as the session user, under timeout so a
hung Herdr is killed. A sandbox without a Herdr server simply has no agents. A sandbox that
times out, answers with something that is not an agent list, or sends more than 1 MiB is
reported on stderr in one-shot mode (airlock: warning: <sandbox> did not answer), and in
watch mode its agents are kept from the last poll. A sandbox is taken into account for at
most 50 agents.
Everything an agent reports (its name, directory, status) comes from inside the sandbox.
airlock removes control characters, terminal escape sequences and Unicode format
characters from it, and caps its length, before it reaches your terminal or a
notification. That keeps the text from moving the cursor, rewriting the screen or hiding
other text. It does not make the text trustworthy: a name can still say anything. For
notify-send, &, < and > are escaped, because many notification daemons render markup.
Other notifiers receive the text as it is, with the characters above removed.
--json prints the same rows as an array. The parsing, classification, sorting, change
detection and sanitizing are unit tested, and the query path is tested with a fake backend.
Not tested end to end: the desktop notifications on macOS and notify-send, and the watch
against a real Herdr with agents changing state.
Known limitation: on Windows the project's path is a host path, and the worktree column
does not map it to the sandbox path, so worktrees show as -.
airlock --remote <host> <command> runs airlock on a server over ssh, and Herdr
keeps the agents alive there. airlock remote moves the project itself, with git:
airlock remote push <host> [path] send the committed branch to the server
airlock remote open <host> [path] start or attach the sandbox there
airlock remote pull <host> [path] fetch the server's branches, for review
- push needs a branch and a clean tree: commit or stash first, because only
commits travel.
-b <branch>pushes another local branch (names starting with-or+are refused).--forcedoes not mean a git force push: it allows the push with uncommitted changes on this machine, which stay here. Pushing never rewrites history on the server; a server branch with commits you lack makes git refuse, and you pull first. It checks thatairlockis installed on the server (curl -fsSL https://raw.githubusercontent.com/alexghirelli/airlock/main/install.sh | shinstalls it there), refuses a server checkout with uncommitted changes, createsairlock-remote/<project>in the server's home directory, adds a git remoteairlock-<host>-<project>to your repository, and switches the server's checkout to the pushed branch. If that last switch fails, the branch is pushed but the server stays on its old branch: fix it and rerun. - open is
airlock --remote <host> airlock-remote/<project>. The path is relative to the server's home directory, where ssh starts a command, so it is the folder push wrote to. The sandbox runs with the server's configuration: your local mounts, environment variables and MCP servers do not exist there. - pull fetches into
airlock-<host>-<project>/*(pruning branches the server deleted) and prints the branches that moved, with the commands to look at them (git log --oneline <branch>..<remote>/<branch>) and to merge them (git merge <remote>/<branch>). It never merges. Files the agent changed on the server but did not commit do not travel: commit them inside the sandbox there (airlock --remote <host> shell airlock-remote/<project>), then pull again. Untracked files do not travel either. - Each project has its own folder and remote, so a worktree and its project are separate on the server. Moving or renaming the project folder changes its name, and the next push creates a new copy on the server; the old copy stays until you delete it there.
- Every ssh call opens a connection. For speed, an ssh
ControlMastersetting in~/.ssh/configfor the host keeps one connection open for them all.
Security notes:
pushsends the committed history of the branch to the server, and the server keeps it. Secrets from your environment and mounts are not copied, but a secret committed to the repository is.- The server never needs access to your computer: the traffic is ssh and git.
- What the agent wrote on the server is untrusted until you have reviewed it. Review
a pulled branch before you merge it, and run
airlock auditafter merging, before you run the code on your computer.
Tests use a fake ssh and git between two local folders (AIRLOCK_SSH names the ssh
client, a hook for tests and unusual setups). This has not been run against a real
server.
airlock config init writes a fully commented template to
$XDG_CONFIG_HOME/airlock/config.toml (%APPDATA%\airlock\config.toml on
Windows). Precedence: defaults < user config < settings for one project (below)
< <project>/.airlock.toml < CLI flags < AIRLOCK_* environment variables.
The project file comes with the repository, so it is untrusted. It may only
set the UI, the default model, whether the team is on, extra apt/mise
packages, a project Dockerfile, resource limits (lower only) and a stricter
network mode. Mounts, environment variables, credentials, capabilities and
anything that loosens the network are ignored, and the ignored keys are reported.
Useful pieces:
[pi]
packages = ["npm:pi-claude-bridge@0.11.0"] # needs Claude Code, which airlock then installs too
default_model = "claude-bridge/claude-opus-5-5"
[env] # passed from your environment
OPENCODE_API_KEY = { from_host_env = "OPENCODE_API_KEY" }
VAULT_DIR = { value = "/mnt/vault" } # a literal value, not a secret
[[mount]] # shared folders, at /mnt/<name>
name = "notes"
host = "~/notes"
mode = "rw"
description = "My knowledge base. Read its README first."
[[mount]]
name = "skills"
host = "~/agent-skills"
mode = "ro"
skills = "." # load Pi skills from here
[[mcp]] # remote MCP server
name = "docs"
url = "https://example.com/mcp"
headers = { Authorization = "DOCS_MCP_AUTH" } # host env var holding the value
[[mcp]] # local (stdio) MCP server
name = "tracker"
command = "node"
args = ["/mnt/tools/mcp-tracker/src/index.js"] # code comes in through a mount
env = { TRACKER_USER = "alice" }
env_from_host = { TRACKER_TOKEN = "TRACKER_TOKEN" } # secrets stay out of the file
[[setup]] # preparation run inside the sandbox
name = "gerrit-venv"
run = """
python -m venv ~/.local/share/mise/venvs/gerrit &&
~/.local/share/mise/venvs/gerrit/bin/pip install -r /mnt/tools/gerrit/requirements.txt
"""
creates = "~/.local/share/mise/venvs/gerrit/bin/python"
watch = ["/mnt/tools/gerrit"] # rerun when files there change[[setup]] runs a shell command at start, before the agent, for anything airlock
knows nothing about (a virtualenv, npm ci, a copy into a writable folder). A step
is skipped while its command is unchanged and the creates path exists; a failing
step is reported by airlock and retried at the next start, without stopping the
sandbox. Only your own configuration may define steps (your user config, or a settings file
for one project): a project's .airlock.toml cannot.
Put what they build under ~/.local/share/mise to keep it across recreations.
With watch, a step also reruns when the files under those paths change (size or
modification time; .git, __pycache__, node_modules and *.log are ignored),
so a copy of a tool from a mount stays current.
Some settings belong to one project, not to all of them: the local settings file a
web app needs, a vendor folder, a mount that only one codebase uses. They cannot go in
the project's .airlock.toml, for the reason below. They go in a settings file for the
project, kept in your configuration folder, next to your user config:
$XDG_CONFIG_HOME/airlock/projects/*.toml (%APPDATA%\airlock\projects\ on Windows).
The layers, lowest to highest: built-in defaults, your user config, the matching settings
files, the project's .airlock.toml, CLI flags, AIRLOCK_* variables. airlock config show
lists on stderr the layers that applied, and airlock doctor lists the settings files.
A settings file has the user config's keys and one more, match, which names the project
folders it applies to:
# ~/.config/airlock/projects/myapp.toml
match = ["~/Sites/myapp", "~/work/*"] # required: the project roots (see below)
[sandbox]
worktree_link = ["config/local.php", "vendor", "plugins/*", ".env"]
[[mount]] # any key of the user config works here
name = "notes"
host = "~/notes"
mode = "ro"matchis a string or a list of strings (an element that is not a string is an error naming the file).~is your home folder.*,?and[...]match within one folder name, so~/work/*is the projects directly in~/work, not deeper;**means the same as*. A project is matched by its root, the main checkout: a worktree of it gets the same settings. The path is compared with the real path on disk (symlinks resolved), so write the real path when your folder sits behind a link.- A wildcard applies to every project that lands there.
match = ["~/*"]gives the file's mounts, environment, setup steps and notify command to every project under your home folder, including one you cloned a minute ago without reading it. Keep wildcards narrow. - Several files. All the files that match apply, in file-name order, and a later one wins.
The merge is the user config's: a scalar set in a file replaces the earlier value, a list
(
worktree_link,[[mount]],[[mcp]],[[setup]]) replaces the earlier list rather than adding to it, and[env]merges key by key. - Files that cannot be checked stop airlock. A file is read only up to 256 KiB. When a
file does not parse, or has an unknown key or a bad value, airlock reads its
matchalone: if that is missing, unreadable or names this project, airlock stops and names the file, because the file may apply here. If itsmatchis readable and names other projects, the file is skipped with a warning. An unreadable file, one over the size cap, and a symlink that is refused or does not resolve stop airlock the same way: theirmatchcannot be read. A file that parses and matches no project is ignored. - Symlinks. A symlink is followed only to a regular file you own, and only when that file is outside the project. Ownership is a sanity check, not the protection: the protection is the location. A symlink that points into the project stops airlock, since the project's own files are not a place for trusted settings.
- Where it is. The folder is
<dir of the user config>/projects, when the config file is calledconfig.toml(so--configandAIRLOCK_CONFIGmove it with the file). Any other name has no folder unless you setAIRLOCK_PROJECTS_DIRto one, which also works withconfig.toml.airlock config path --projectprints the file for the project around the current directory.airlock config init --projectwrites a commented skeleton (mode 0600), andairlock config edit --projectcreates it if it is missing and opens it in$VISUALor$EDITOR, asconfig editdoes. The name is<folder>.toml; when that name already belongs to another project,<folder>-<hash>.toml. A folder name with*,?,[or a backslash is escaped inmatch(on Windows, which has no such escape, it is refused). - The configuration folder is off limits to the sandbox. Airlock refuses a mount of the
configuration folder, of the folder of the config file in use, of the projects folder, of a
folder that holds any of them (
~/.configholds~/.config/airlock, for instance), and of a file inside them. It refuses to start a sandbox whose project folder holds or lies inside them. Paths are resolved through symlinks first, and compared case-insensitively on macOS and Windows.
Why not in the repository. The project's .airlock.toml is in the repository, and the
agent in the sandbox can write it. So airlock reads only a few harmless keys from it (see
Configuration). A settings file is different: you own it, and airlock
never mounts the configuration folders into a sandbox (see the last bullet above), so the
sandbox cannot write it. That is why it may set what .airlock.toml may not, such as mounts,
environment variables, setup steps and worktree_link. The trust is yours, though.
A settings file you did not write is as much a configuration you accepted as your user config
would be, so read one before you copy it.
A worktree shares the repository, not the folder's untracked files: a config/local.php, a
vendor folder, a .env. worktree_link lists paths of the project root (relative, /
separated, patterns allowed) that each new worktree should get. When airlock wt add, a new
airlock review or airlock wt link [name] runs, airlock creates for every matching path a
relative symlink in the worktree that points at the main checkout's entry, such as
.worktrees/feat/vendor -> ../../vendor. airlock wt link with no name does all the
worktrees, and running it again creates nothing new.
- It never replaces anything, and never removes anything. A path that already exists in the worktree is left alone, and so is a path that git tracks, in the project or in the worktree's branch.
- It skips, with a line each, what it cannot link safely: a pattern that matches nothing, a match that is a link out of the project or a dangling link, and the whole of an isolated worktree (its sandbox does not mount the main checkout, so the links would dangle). The count line says how many paths git tracks, were already linked, or are already in the worktree as something else; those are not listed one by one.
- A folder of the new link that is missing is made inside the worktree. A folder that is a link is not followed, and the link is skipped. The worktree folder is written by the agent, so the links are made through a directory handle that cannot leave the worktree, and airlock stops if the folder it opened is not the one it looked at.
- Patterns may not be absolute, contain
.., name.git,.worktrees, or the first folder ofsandbox.worktrees_dir(checked against the same configuration), or be empty. Such a pattern is a configuration error. The folder is never linked at link time either. - The links are untracked, so they show in
git status. Agit add -Ain the worktree would stage them, so exclude them (in.git/info/exclude, shared by the worktrees) if they get in your way.
For a PHP app with a local config file and plugins, in ~/.config/airlock/projects/myapp.toml:
match = ["~/Sites/myapp"]
[sandbox]
worktree_link = ["config/local.php", "vendor", "plugins/*", ".env"]Tracked plugins are skipped, so only the ones you have locally are linked.
worktree_link in a project's .airlock.toml is ignored, and airlock says so.
airlock init looks at the project root and writes .airlock.toml with the packages
the project needs (extras.mise, extras.apt), each with a comment saying which file
it came from. Toolchains that a version file already pins (.nvmrc, .python-version,
.tool-versions, mise.toml and the like) are left alone. It detects Node, Go, Python,
Ruby, Rust and PHP (PHP comes from apt: mise would compile it for minutes). It writes at
the repository root, also when you run it inside a worktree. It refuses to overwrite an
existing file, and never writes through a symlink, even with --force; --json only
prints the result. The project is untrusted, so what init prints is cleaned of control
characters, escape sequences and bidi overrides, and a secret-looking file whose name
holds a line break or such a character is counted, not listed.
Services are matched by name: an image whose last path segment contains mariadb,
mysql, postgres, postgis, redis, valkey, memcached, mongo, elasticsearch,
opensearch or rabbitmq is listed (so bitnami/postgresql counts, and so can an
exporter with such a name).
It does not write your user config. It prints what belongs there instead: MCP config
files to pass to airlock mcp import, compose services that run a database (airlock has
no service containers yet), and secret-looking files to add to .airlockignore.
airlock config init is the other command: it writes your user config.
The published image is only the base. What you add never changes it, and is kept on your machine, in the cheapest place that fits:
| You add | Where it lives | Cost |
|---|---|---|
extras.mise, [[setup]], Pi packages, logins |
Docker volumes, filled when the sandbox starts | nothing to rebuild |
extras.apt |
a layer built on top of the downloaded image | seconds, rebuilt when the list changes |
| an agent other than Pi, or another Pi version | the tools volume, installed on first use (see Agents) | seconds to a minute, once per version |
[image] dockerfile, project extras.apt |
a per-project image built on top of the base | seconds, rebuilt when the files change |
A new airlock release publishes a new image; the first run after upgrading
downloads it, and layers you had added are rebuilt on top. The old image is removed
once nothing uses it. airlock update rebuilds from scratch locally instead of
downloading.
The configuration is read when the sandbox starts. If you change it while a sandbox
is running, airlock says so; airlock restart stops and starts it again to apply
the change (sessions inside it end).
Already have mcpServers JSON from another tool? airlock mcp import file.json
prints the matching [[mcp]] entries. It never copies values that look like secrets
(it points to host variables instead) and warns about paths on your computer,
virtualenvs and runtimes the sandbox does not have yet.
A local MCP server runs inside the Linux sandbox, so its code must be mounted
and its runtime must exist there: add extras.mise = ["node@22", "python@3.12"]
as needed. A virtualenv or compiled node_modules built on macOS will not run
in Linux; create them from inside the sandbox instead.
Every agent also gets a built-in concise skill (image/skills/concise/SKILL.md):
lead with the answer, no preamble or recap, numbered steps, one tangent at a time.
Its rules are written into the generated /AGENTS.md and Pi loads the skill too.
Turn it off with [agents] concise = false. It was inspired by
i-have-adhd (MIT), but is its own, shorter text.
Agents are told about the sandbox, the network policy, git rules and every mount
through a generated /AGENTS.md. Verify model ids with pi --list-models inside
the sandbox rather than assuming them.
.airlockignore (gitignore syntax, in the project root) hides files from the
sandbox: matching files appear empty and read-only. Files created later are not
hidden until the sandbox is recreated.
airlock gc lists what is left behind, and airlock gc --force removes it:
- sandboxes whose project folder no longer exists (a deleted project or worktree);
- the credentials volume of such a project (
credentials.scope = "per-project"; volumes made before this version are not labelled and are never touched, remove those withairlock rm --purgein their project); airlock:images of older releases that no sandbox uses.
The shared logins, the tools volume, your project files and anything that is still
in use are never collected. Without --force it only lists. airlock wt prune
does the same for worktrees whose folder you deleted by hand (their branches stay).
To stop sandboxes nobody uses, set idle_stop in your user config:
[sandbox]
idle_stop = "2h" # at least 5m; empty = never (the default)A sandbox stops after that long with no terminal attached and no agent working.
airlock starts it again, and the agents continue their conversations (see
Agents). Anything else running in it stops too,
a dev server for one. The setting applies the next time the sandbox starts
(airlock restart).
A personal Claude account and a company one must not meet. Give each its own login volume
with a profile, and tie the profile to the projects that use it, in a settings file for
those projects (airlock config edit --project, or a file in ~/.config/airlock/projects/):
# ~/.config/airlock/projects/work.toml
match = ["~/Work/*"]
[credentials]
profile = "work"Projects that match get the volume airlock-profile-work; the others keep the shared one (or
a profile of their own). Run airlock login once in a work project to log in to the company
account there, and once in a personal one to log in to the other. What a profile separates:
the provider logins, Pi's settings and installed packages, and the saved conversations. All the
worktrees of a repository use the profile of the repository.
- A profile wins over
credentials.scope.AIRLOCK_CREDENTIALS_PROFILEsets it for one run. - A profile is a name (lowercase letters, digits,
-,_). Only your user config and the settings files inprojects/may set it: the.airlock.tomlof a repository is ignored (with a warning), so a repository cannot pick which account its own code runs with. - Several projects share the volume of their profile, so
airlock rm --purgeandairlock gcleave it alone;airlock login --resetin one of those projects wipes it for all of them.airlock doctorshows which volume a project mounts. - What it does not separate: the tools volume, the tokens you pass from the host (
[env],git.token_env) and the network. Set those per project as before. - One sandbox has one profile. Two accounts inside the same sandbox are not supported, because every agent there could read both logins.
- Changing the profile of an existing project recreates its sandbox (the volume changes).
- Anthropic API key:
default_model = "anthropic/<id>", runairlock login. - Claude subscription:
packages = ["npm:pi-claude-bridge@0.11.0"],default_model = "claude-bridge/<id>", runairlock login(it runsclaude auth login; the bridge uses Claude Code's login, not Pi's). - API key from the environment: add it under
[env]and export it on the host.
Pi is the default and comes in the image. The agent is a setting, so you can run another one, at the version you want:
[agent]
kind = "claude" # pi (default) | claude
version = "pinned" # pinned (tested with this airlock) | latest | "2.1.322"
args = ["--dangerously-skip-permissions"] # extra arguments; the sandbox is the boundaryairlock --agent claude does the same for one run, and airlock review 123 --agent claude for one worktree, so a Pi session and a Claude Code one can work side by
side in the same Herdr. The first use installs the agent into the tools volume, a
folder per version, so projects share the download and can use different versions;
Claude Code comes from Anthropic's own installer and Pi from npm. Nothing is baked
into the image, which also keeps it free of anything that cannot be redistributed.
Then run airlock login once.
Closing a workspace does not lose the conversation. Pi and Claude Code keep their
sessions in the credentials volume, one per folder. When a workspace is opened again
(airlock wt open, a worktree that had been closed, a sandbox that was stopped or
recreated), the agent starts with --continue and picks up the last conversation of
that folder; a folder without one starts fresh. --fresh starts a new conversation
for one run (airlock wt open rate-limit --fresh) and agent.resume = false turns
the continuing off. A worktree has its own conversation, separate from the project's
and from every other worktree's, and a team (--team) always starts fresh.
What airlock does for you depends on the agent:
| Pi | Claude Code | |
|---|---|---|
| Runs in a sandbox with the firewall, worktrees and Herdr workspaces | yes | yes |
| Sandbox instructions (where you are, mounts, MCP servers) | yes | yes, added to its system prompt |
MCP servers from [[mcp]] |
yes | yes |
Task of a worktree (airlock review, wt focus) |
yes | yes |
Skills from mounts, the concise skill, pi.default_model, packages |
yes | no, these are Pi's |
--team |
yes | no |
Inside the sandbox airlock marks the project as trusted for Claude Code (the project
is the reason the sandbox exists) and skips its first-run screens. Other agents are
not wired up yet; a kind is a small adapter, and adding one is a good first
contribution.
What it protects against: an agent that is prompt-injected, buggy or overeager trying to (a) read or change host files outside the project, (b) reach your host or LAN (router, NAS, Docker socket, cloud metadata), (c) leave code that later runs on your computer, or (d) get at your credentials.
How:
- Non-root user,
--cap-drop ALLplus a small set, never privileged, no host network/PID/IPC, no Docker socket, only the project and declared mounts. - The egress firewall is installed by the entrypoint from settings fixed at
container creation.
docker execgives processes the container's capabilities, not the entrypoint's, so every session airlock starts goes through a wrapper that removesNET_ADMIN/NET_RAWfrom the bounding set:sudo iptables -Ffails. (This is tested; it was a real flaw in the first design.) .git/hooksand.git/configare mounted read-only, which blocks the usual ways to plant code that git later runs on the host.- The task files of a worktree (focus, review, handoff briefing) are host files: they live in airlock's state folder, which the sandbox never sees. They are mounted read-only: an isolated worktree's sandbox sees only its own folder, and the project's sandbox sees the folders of the worktrees that share it (as it sees the worktrees themselves). The agent cannot change what the host reads (a link or a FIFO in the worktree's git directory is ignored, and the reads are capped at 64 KiB), nor what the next agent is told at its start. An agent can still influence what it later reads from the project and from commit messages, since the briefings call them data, not instructions: that boundary is advisory, not enforced.
- No git credentials in the box by default.
git.mode = "push"injects one token from a host variable, offered only to the configured hosts.~/.sshis never mounted. airlock auditreports changes to hooks,.envrc,.vscode/, build and CI files,package.json/composer.jsonscripts and new executables. It reports; it does not revert. The baseline moves only when you runairlock audit --accept.
The host runs git too, on the repository the agent writes to. airlock summary,
wt, remote and review run git on your checkout and its worktrees, and git
on its own finds a repository from the folder it runs in and reads its config,
attributes and hooks from wherever it lands. A .git the agent rewrote could
therefore make your git run its commands. internal/hostgit is the only host
path to git: it pins the git directory, the common directory and the working tree
to paths derived from your checkout, refuses a commondir file or a .git that
is not a directory, and never follows the .git file of a worktree in a worktrees folder. It also turns off
what would run code (fsmonitor, hooks, ssh, filters, textconv, external diffs) on
every call, and it runs on a snapshot of HEAD and the index when
extensions.worktreeConfig is set, because the config.worktree of the main
checkout is not protected. The main checkout's .git is a mount point in its
sandbox, so the agent cannot rename it and put its own in place. What is left: the
trust a worktree gets comes from its folder (.worktrees or .isolated), so run
airlock from the project root, and a sandbox.worktrees_dir other than those
names is not recognised as a worktrees folder. Your own global git configuration
and environment are trusted; the system git configuration is not read by these
calls.
What it does not protect against:
- Data leaving over the internet. The default network mode lets the agent reach
the internet, so a prompt-injected agent can send out anything it can read: your
source, the environment variables you pass in, the tokens you mount. The firewall
blocks your computer and LAN, not the outside. Keep secrets out of the project
(
.airlockignorehides files from the box;airlock doctorwarns about visible secret-looking ones) and out of the variables you pass. A domain allowlist is not built yet. - A container shares the host kernel. The agent is root inside the box (it has
sudo, so it can install packages), and a kernel exploit could escape from there. Docker Sandboxes and similar tools use a microVM for this; airlock has a gVisor option (runsc, not yet part of the test suite) and a microVM backend is only an idea so far. - A restart of the container re-runs code the agent can change. The agent has
sudo, so it is root inside the container (withoutNET_ADMIN), and the container's file system is writable. It can replace the entrypoint or the programs it uses (id,iptables…), and the next start of the container (airlock stop,sandbox.idle_stop, a Docker restart) runs them as root withNET_ADMIN, before the firewall is back. The firewall cannot be changed in a running container, but a sandbox that was compromised and then restarted should not be trusted: remove it withairlock rminstead of restarting it. Withoutsudothe agent cannot do this: the entrypoint no longer looks anything up in folders the agent can write. - Anything you hand over: a read-write mount can be modified, a mounted
~/.awsis readable, apushtoken can push, environment variables are visible to every process in the box (and indocker inspect). - Worktrees in the same sandbox are not kept apart. By default they all share the
project's sandbox, so an agent reviewing a patch can read and change your other
worktrees and the project's untracked files. Set
sandbox.worktree_isolationto give reviews (or every worktree) a sandbox of their own. - Worktrees share one git directory, isolated or not. An agent in one can create, move or delete branches and tags that the others (and you) see, and add objects to the shared store. Review what a sandbox committed before you push it.
- With
credentials.scope = "shared", any sandbox on the machine can read the provider logins.per-projectisolates them, and acredentials.profileisolates them from every project that does not use the same profile.airlock login --resetwipes them. - The toolchain volume is shared between projects.
- The firewall allows DNS to the resolvers Docker forwards to (needed for name resolution), so DNS can carry data out.
- Rootless Docker/Podman: file ownership of the project may not map to your user
(
doctorsays so).
| Not implemented | Notes |
|---|---|
network.mode = "allowlist" |
Fails with a clear message. Needs a filtering proxy. |
--team |
The Herdr bootstrap and team scripts are written, but not verified end to end. Treat as experimental. |
microvm / vm backends |
Rejected by the CLI. gvisor starts the container with runsc but has not been run through the test suite. |
airlock login |
Runs Pi's and Claude Code's own login flows; checked up to the credential prompt only (no real login was made). --reset is untested. |
credentials.profile |
The volume name, the config rules and the plan are unit tested; two real logins on two profiles were not made. |
[[mcp]] |
Written into Pi's MCP config (remote and stdio servers); the entry and the mounted command are tested, but not a full session against a real MCP server. |
airlock remote |
Tested with a fake ssh and two local folders; never run against a real server. The server-side scripts run under sh -c, so the login shell can be anything that runs sh and airlock. |
| Windows | The release archive compiles for it, but airlock has not been run there (WSL2 is the way to go, see airlock doctor). |
go test ./... # unit tests, a few seconds
go test -tags integration -timeout 15m ./tests/... # needs Docker and internet
AIRLOCK_IT_SLOW=1 go test -tags integration -run Packages ./tests/... # the slow, network-heavy testThe integration tests build the image once (about three minutes the first time) and
then take about a minute. They cover: isolation (with a positive control, so a
missing firewall would be noticed), capability dropping, ownership, protected git
files, worktrees (one sandbox each, none seeing another), untrusted project config, same-name projects, mounts,
persistence, Herdr attach/detach/reattach through a real pseudo-terminal,
.airlockignore, audit, git modes and doctor, and Claude Code and other Pi
versions as the agent. The test that installs Pi packages together with Claude
Code is opt-in (AIRLOCK_IT_SLOW=1).
CI runs only the fast checks on every push (formatting, vet, unit tests,
cross-compilation). The integration tests run weekly, and on demand from the
Actions tab (the integration workflow).
The tests set AIRLOCK_PRUNE_IMAGES=0 so the several image variants they build
survive each other. Normally airlock removes superseded airlock:* tags after a
build; the image is about 1.3 GB.
Releases come from annotated tags, and the tag message is the release text:
git tag -a v0.2.0 -F notes.md # a summary line, then what changed, for users
git push origin v0.2.0The release workflow refuses lightweight tags and messages without a summary
line and at least one line of detail. The release is named after the version only
(v0.2.0); the tag message is its text. It builds the archives, publishes them with
SHA256SUMS, and appends the install line and a link to the full changelog.
Apache License 2.0. See LICENSE and NOTICE.
The image downloads Pi (MIT), Herdr (Apache-2.0) and mise at build time; each keeps its own licence and terms. Claude Code is proprietary and is not in the image: when you choose it, Anthropic's installer fetches it onto your machine, under Anthropic's terms.
