Repository navigation
Releases
v0.5.0
Account profiles: one login volume per account, tied to a project
A personal Claude account and a company one no longer have to meet in a sandbox.
New
[credentials] profile = "work"names a login volume (airlock-profile-work) that every project naming it shares. The provider logins, Pi's settings and installed packages, and the saved conversations of one profile are invisible to the others. A profile wins overcredentials.scope; without one nothing changes.- Tie a profile to projects in a settings file for them (
airlock config edit --project, or a file in~/.config/airlock/projects/with amatchlist), then runairlock loginonce in a project of each profile.AIRLOCK_CREDENTIALS_PROFILEsets it for one run.airlock doctorshows which volume a project mounts. - Only your user config and those settings files may set a profile. The
.airlock.tomlof a repository is ignored, with a warning, so a repository cannot choose which account its own code runs with. airlock rm --purgeandairlock gcleave profile volumes alone, because several projects share one.airlock login --resetwipes it and says whom that affects.- What a profile does not separate: the tools volume, tokens you pass from the host (
[env],git.token_env) and the network. One sandbox has one profile; two accounts inside the same sandbox are not supported.
Changed
airlock initno longer has a special case for one PHP application (a printed settings file, two database drivers and a note). Acomposer.jsonstill proposes PHP from apt. The documentation examples are generic.- The git history was rewritten to remove names that do not belong in a general tool. Tags and commit hashes of earlier releases changed; the code of each release did not, apart from those names. If you cloned or forked the repository before, clone it again.
Upgrading: the image is the same as in 0.4.0. A sandbox is recreated only when you set a profile for its project (the login volume changes); you log in again once per profile. Not tried yet: a real login on two profiles with two accounts.
Install or upgrade: curl -fsSL https://raw.githubusercontent.com/alexghirelli/airlock/main/install.sh | sh (checksums in SHA256SUMS). After upgrading, run airlock rm and then airlock in a project if the notes say the image or the sandbox settings changed: the new sandbox is created from the new image, and your logins and installed tools are kept.
Full changelog: v0.4.0...v0.5.0
v0.4.0
Inbox, summary, init, remote and handoff, per-project settings and wt run, and security fixes
Eight additions and a round of security fixes from an adversarial review. Please upgrade: several of the fixes apply to every earlier release.
Security
- An agent could write into the project's
.git(or a worktree's.gitfile) so that git, run by airlock on your computer, ran a program of the agent's own: onairlock wt ls,summary,review,remote pushand more. All host-side git now goes through one helper that fixes the repository, ignores the checkout's own configuration and never looks into submodules. - The session wrapper and the container entrypoint (root, with
NET_ADMIN, before the firewall is up) looked programs up in the agent'sPATH. Both use root-owned paths now. - The task files of a worktree (focus, review, handoff briefing) lived in
.git, where the sandbox could aim them at files on your computer. They moved to a folder the host owns, mounted read-only into the sandbox. airlock initon a repository you just cloned no longer reads special files, writes through symlinks, or lets the repository send escape sequences to your terminal.- A limit that stays, now documented: with
sudothe agent is root inside its container, and a restart of that container re-runs whatever it left in its file system. Remove a sandbox you suspect (airlock rm) instead of restarting it.
New
airlock inbox [--watch]: the agents of every running sandbox and what they wait for;--watchnotifies you (notify-send,osascript, or your own command in[notify]).airlock summary [worktree]: commits, files, uncommitted work and audit result of a worktree before you merge it (--json).airlock init: writes a starter.airlock.tomlfrom what the project uses (it also suggests what belongs in your own config).airlock remote push|pull|open <host>: keep a project on a server with git, so an agent keeps working while your laptop sleeps. Nothing merges by itself.airlock wt handoff <name>: give a worktree to a new agent (--agent pi|claude) with a briefing of what was done.[[runner]]andairlock wt run <runner> <worktree> -- cmd: run a command in a container you already have (a compose service, say), in the path of that worktree. You run it, not the sandboxed agent.- Settings files for one project, in
~/.config/airlock/projects/*.tomlwith amatchlist (airlock config edit --project): they cannot live in the repository, which the sandbox can write. sandbox.worktree_linkandairlock wt link: linkvendor,local.php,extensions/*and the like from the main checkout into each worktree.
Upgrading: sandboxes are recreated (image scripts and the container settings changed). A focus set with an earlier version must be set again with airlock wt focus <name> "...". Mounting your airlock config folder, or running a project that contains it, is now refused. The image is published to GHCR for this release, so the first run downloads it. Not tried yet: remote against a real server, wt run against your own container on macOS, and inbox --watch with live agents.
v0.3.0
Agents continue their conversation, airlock gc, and sandboxes that stop when idle
Three things that make a sandbox you leave running (or close) less of a chore.
- A workspace you reopen continues its 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 whose Herdr workspace was closed, a sandbox that was stopped or recreated), the agent starts with--continueand picks up the last conversation of that folder; a folder without one starts fresh. A worktree has its own conversation, and a team always starts fresh.--freshstarts a new conversation for one run andagent.resume = falseturns the continuing off. airlock gclists what deleted projects and old releases left behind: sandboxes whose project folder is gone, the own credentials volume of such a project, andairlock:images of older releases that no sandbox uses.airlock gc --forceremoves them. Shared logins, the tools volume, your project files and anything still in use are never collected. A per-project credentials volume is labelled with its project from this release on; volumes made earlier are left alone (airlock rm --purgeremoves them).airlock wt prunedoes the same for worktrees whose folder you deleted by hand; their branches stay.sandbox.idle_stop = "2h"(at least 5m, empty = never, the default) stops a sandbox that has no terminal attached and no agent working for that long.airlockstarts it again and the agents continue their conversations. Anything else running in it, a dev server for one, stops too. A project's.airlock.tomlcannot set it.
Upgrading: sandboxes are recreated (image scripts changed). The image is published to GHCR for this release, so the first run downloads it.
Install or upgrade: curl -fsSL https://raw.githubusercontent.com/alexghirelli/airlock/main/install.sh | sh (checksums in SHA256SUMS). After upgrading, run airlock rm and then airlock in a project if the notes say the image or the sandbox settings changed: the new sandbox is created from the new image, and your logins and installed tools are kept.
Full changelog: v0.2.1...v0.3.0
v0.2.1
A cleaner first run, airlock rm --purge, and a demo GIF in the README
Small fixes on top of v0.2.0.
- Herdr no longer greets every new sandbox with a welcome box and an integrations page: airlock installs the integrations it needs itself and writes
onboarding = falseto Herdr's config when there is none (an existing config is left alone). airlock rm --purgealso deletes the sandbox's own credentials volume whencredentials.scope = "per-project", whichairlock rmkept and left behind for good. The shared volume is never touched;airlock login --resetempties it. The login commands now name the right volume for a worktree too.- The README has a demo GIF: a prompt-injected agent finds no host secrets, no LAN, no way to remove the firewall and read-only git hooks, then a pull request is reviewed in a second Herdr workspace.
scripts/demo.shandassets/demo.taperender it with VHS.
Upgrading: sandboxes are recreated (an image script changed). The image is published to GHCR for this release, so the first run downloads it.
Install or upgrade: curl -fsSL https://raw.githubusercontent.com/alexghirelli/airlock/main/install.sh | sh (checksums in SHA256SUMS). After upgrading, run airlock build, then airlock start --recreate if the notes say the image or the sandbox settings changed.
Full changelog: v0.2.0...v0.2.1
v0.2.0
Choose your agent, and a first run that downloads instead of building
The agent is now a setting: Pi (the default) or Claude Code, at the version you want. The base image is published to GHCR, so the first run downloads it instead of building it.
[agent] kind = "pi" | "claude",version = "pinned" | "latest" | "2.1.322"andargschoose the agent.airlock --agent claudedoes it for one run, andairlock review 123 --agent claudefor one worktree, so a Pi and a Claude Code workspace can sit side by side in the same Herdr.- Nothing but Pi is in the image. Claude Code is installed by Anthropic's own installer, and other Pi versions from npm, into the tools volume the first time they are used (one folder per version, shared by projects). Claude Code gets the sandbox instructions, the MCP servers, the task of the worktree and
args; skills,pi.default_model, packages and--teamstay Pi-only. Inside the sandbox the project is trusted for Claude Code and its first-run screens are skipped. - The first
airlockdownloads the base image (about 300 MB, amd64 and arm64) from GHCR instead of building it (about two minutes). It builds locally when the download fails, for development builds, or withAIRLOCK_BUILD_LOCAL=1;extras.aptis added as a small layer on top. - The README says plainly what a container does not stop (data leaving over the internet, the shared kernel), and macOS with Docker Desktop is marked as in daily use.
scripts/demo.shandassets/demo.taperender the demo GIF with VHS.- Tested on Linux, against local servers and registries; not yet with a real Claude Code login, on live GitHub, GitLab or Bitbucket, or the image workflow itself.
Upgrading: sandboxes are recreated (the image scripts and the sandbox settings changed). The first run downloads the new image; if it is not published yet airlock builds it locally. A sandbox that used Claude Code through extras.claude_code or a Pi package installs it again into the tools volume on its first start.
Install or upgrade: curl -fsSL https://raw.githubusercontent.com/alexghirelli/airlock/main/install.sh | sh (checksums in SHA256SUMS). After upgrading, run airlock build, then airlock start --recreate if the notes say the image or the sandbox settings changed.
Full changelog: v0.1.9...v0.2.0
v0.1.9
Review pull and merge requests, and a fix for reviews started together
airlock reviewnow takes GitHub pull requests, GitLab merge requests and Bitbucket Server pull requests as well as Gerrit changes: give it the URL, or a number (321,12345/3), orpr:321,mr:45,bb:7,gerrit:12345when a number exists as more than one kind. It uses the ref the server publishes for each (refs/pull/N/head,refs/merge-requests/N/head,refs/pull-requests/N/from), so it needs no API and no token beyond what git already uses for the remote. Gitea and Forgejo work like GitHub. A URL picks the remote that points at that repository, so a pull request againstupstreamworks from a fork;git.review_remotepins the remote. Bitbucket Cloud does not publish pull requests as git refs: airlock says so instead of failing.- Each kind gets its own local branch and worktree (
review/12345,review/pr-321,review/mr-45,review/bb-7), moved to the new head when you run it again, without losing uncommitted changes or local commits. A pull or merge request can have several commits and its target branch only exists on the forge, so the agent's task gives a likely base and tells it to check. - Fixed: two reviews started at the same time (two terminals) could end up on the same commit, with the task describing the other change. Each review now fetches into its own ref, and creating or removing worktrees takes a lock. If you reviewed two changes together with v0.1.8, run
airlock reviewagain: a branch with no commits or changes of yours moves to the right commit by itself, and one with yours is left alone with thegit rebase --ontoto run. - The review task now names the commit by hash and tells the agent to check that
HEADmatches, and carries airlock's warning when the branch could not be moved to the new version. airlock wt addandairlock reviewstay quiet when a Herdr is already open in another terminal on the same sandbox: the new workspace appears there without taking its focus, and nothing attaches.--attachattaches anyway.- Reviews of pull and merge requests have been tried against a local server with the same ref layout as GitHub, GitLab and Bitbucket Server, not yet against the services themselves.
Upgrading: nothing to rebuild. The image and the sandbox settings did not change, so running sandboxes keep working and no --recreate is needed.
Install or upgrade: curl -fsSL https://raw.githubusercontent.com/alexghirelli/airlock/main/install.sh | sh (checksums in SHA256SUMS). After upgrading, run airlock build, then airlock start --recreate if the notes say the image or the sandbox settings changed.
Full changelog: v0.1.8...v0.1.9
v0.1.8
Git worktrees as Herdr workspaces, and Gerrit reviews
airlock wt add <name> ["what to focus on"]makes a git worktree on a new or existing branch. By default every worktree shares the project's sandbox and shows up as a workspace in the same Herdr session.wt open,wt ls,wt focusandwt rmcomplete it;wt rmcloses the workspace and keeps the branch.airlock review <change>(a number,12345/3, or the Gerrit change URL) fetches the patchset on your computer, where your Gerrit credentials are, and checks it out on a local branchreview/<change>, so a review can include changes of your own. Run it again and the branch moves to the newest patchset, unless that would lose uncommitted changes or local commits: it then says so and prints the rebase to run. The remote isgerritif the repository has one, otherwiseorigin;git.gerrit_remotechanges it.- Every worktree can have a task for its agent. Text after the name or change is its focus; a review also gets one written from the commit (change, patchset, subject, author, and the rules of a review: no push, no edits unless asked, findings by file). Pi reads them each time it starts in the worktree, and they stay out of
git status. sandbox.worktree_isolation(none,reviewsorall), and--shared/--isolatedfor one worktree, give a worktree a sandbox of its own. An isolated worktree mounts only itself and the repository's.git: the main checkout, its untracked files and the other worktrees are not visible. The default isnone, because reviewing a patch in the project's sandbox lets the agent read your other worktrees; setreviewsif you review patches from people you do not know.- Reviews have been tried against a local server with Gerrit's
refs/changeslayout, not yet against a live Gerrit.
Upgrading: the Herdr and Pi scripts in the image changed and sandboxes now record their tmpfs mounts, so the first airlock after upgrading builds a new image (a few minutes) and the sandbox has to be recreated: run airlock --recreate. Your project files, logins and installed tools are kept.
Install or upgrade: curl -fsSL https://raw.githubusercontent.com/alexghirelli/airlock/main/install.sh | sh (checksums in SHA256SUMS). After upgrading, run airlock build, then airlock start --recreate if the notes say the image or the sandbox settings changed.
Full changelog: v0.1.7...v0.1.8
v0.1.7
Know when the config changed, and import MCP servers
- airlock now tells you when the configuration changed after the sandbox started, instead of silently reusing the old one.
airlock restartstops and starts the sandbox to apply the change (sessions in it end). [[setup]]steps takewatch = ["/path"]: the step runs again when files under those paths change (size or modification time;.git,__pycache__,node_modulesand*.logare ignored). Handy for a copy of a tool taken from a mount.airlock mcp import file.jsonturns anmcpServersJSON file (the format of Claude Code and others) into[[mcp]]entries. Values that look like secrets are never copied: they become references to host environment variables. It warns about paths on your computer, virtualenvs and runtimes the sandbox does not have yet.- Releases now carry release notes written for users, taken from the tag message.
Upgrading: the start-up script inside the image changed, so the first airlock after upgrading builds a new image (a few minutes) and the sandbox has to be recreated: run airlock start --recreate. Your project files and logins are kept.
Install or upgrade: curl -fsSL https://raw.githubusercontent.com/alexghirelli/airlock/main/install.sh | sh (checksums in SHA256SUMS).
Full changelog: v0.1.6...v0.1.7
v0.1.6
Literal values in [env], and a built-in concise skill
[env]entries accept a literal value,NAME = { value = "/mnt/vault" }, besidesfrom_host_env. Names starting withAIRLOCK_are rejected, because they carry the firewall and ownership settings. Literal values are not secrets.- Every sandbox ships a short built-in
conciseskill (lead with the answer, no preamble or recap, numbered steps, one tangent at a time). Pi loads it, and the same rules are written into the generated/AGENTS.md. Switch it off with[agents] concise = false.
Upgrading: run airlock build, then airlock start --recreate.
Install or upgrade: curl -fsSL https://raw.githubusercontent.com/alexghirelli/airlock/main/install.sh | sh (checksums in SHA256SUMS).
Full changelog: v0.1.5...v0.1.6
v0.1.5
Setup steps, and a safer upgrade on macOS
- New
[[setup]]steps: a shell command run inside the sandbox at start, before the agent, for anything airlock knows nothing about (a virtualenv,npm ci, a copy of a tool from a mount). A step is skipped while its command is unchanged and itscreatespath exists; a failing step is reported and retried at the next start without stopping the sandbox. Only your user config can define steps. - Warnings from the sandbox's start-up are now shown by
airlockinstead of staying in the container log. install.shreplaces the binary by renaming a new file over the old one. Overwriting it in place made macOS kill the next launch (zsh: killed) after an upgrade.
Upgrading: run airlock build, then airlock start --recreate.
Install or upgrade: curl -fsSL https://raw.githubusercontent.com/alexghirelli/airlock/main/install.sh | sh (checksums in SHA256SUMS).
Full changelog: v0.1.4...v0.1.5