corral is a disposable rootless-Podman environment for four AI coding
agents: codex, claude, opencode, and agy. The four binaries live only
in the image. All tool state lives in one named Podman volume --
nothing appears as dotfiles in your host home. Every invocation is an
ephemeral run --rm container. The rootfs is read-only, all
capabilities are dropped, no-new-privileges is set, processes are
limited, and userns keep-id ensures files the agents write into your
project are owned by you on the host, not a subordinate UID.
Setup
----
$ sudo pacman -S podman podman-compose gnupg
$ git clone https://github.com/librefos/corral.git
$ cd corral
$ chmod +x harness
$ ./harness build
Daily use
----
From any project directory:
$ /path/to/corral/harness claude
$ /path/to/corral/harness codex
$ /path/to/corral/harness opencode
$ /path/to/corral/harness agy
$ /path/to/corral/harness # shell, all four on PATH
To make it global, symlink it into a directory on your PATH. The
script resolves the link back to this checkout, so compose.yaml is
still found, and unlike an alias the command also works from scripts,
tmux send-keys, and non-interactive shells:
$ ln -s /path/to/corral/harness ~/.local/bin/harness
Only your current directory is mounted (at /workspace). The container
is deleted the instant the command exits. Tokens land in the
corral-home volume and survive run --rm.
Division of labor
----
Files are shared across the container boundary; processes are not. The
bind mount means your host editor and the containerized agents see the
same bytes live. Anything whose job is touching files belongs on the
host. Anything whose job is executing the project must exist inside the
image, because that is where agent-spawned processes run.
host image volume
---- ----- ------
editor, tmux, IDE the four agents auth tokens
your own git usage project runtimes agent config, logs
the project files git, rg, fd, jq gitconfig, bashrc
Host tmux is where persistence lives: each pane can run its own harness
invocation, every one an isolated container sharing the same volume and
workspace.
What is inside the container
----
The four agent CLIs, each a single native binary on PATH:
claude Claude Code
codex Codex CLI
opencode OpenCode
agy Antigravity CLI
Supporting tools installed via apt:
- the GNU basics from the Debian slim base.
- less, file, procps (ps, top, free).
- tar, gzip, unzip, xz-utils: archive handling.
- openssh-client: enables git-over-ssh IF you provision a key inside
the volume; your host ~/.ssh is deliberately never mounted.
- curl: HTTP client.
- git: version control; the agents lean on it constantly.
- rg (ripgrep) and fd: fast search; some agents invoke these.
- jq: JSON processing.
- bubblewrap: the sandbox backend codex prefers on PATH.
Deliberately not included:
- Language toolchains and compilers.
- Editors. Host editors work on the shared files.
- Anything host-identifying: no SSH keys, cloud credentials, agent
sockets, or host dotfiles.
Adding tools
----
Installs fail inside a normal harness shell on purpose: you are not
root, the rootfs is read-only, and the container is ephemeral. Three
sanctioned routes instead, in order of preference:
1. Permanent: set EXTRA_PACKAGES (the ARG in the Containerfile, or build
args in compose) and rebuild. The layer sits after the
CLI downloads, so changing it rebuilds in seconds -- the four agent
binaries stay cached.
2. Experiment first: the hardening lives in compose, not the image, so a
throwaway writable root shell is one command away:
$ podman run -it --rm --user root localhost/corral:latest bash
apt-get works in there; everything vanishes on exit. Use it to
figure out what you need, then codify it in EXTRA_PACKAGES.
3. Per-user, no rebuild: anything installed under $HOME lands in the
persistent volume and survives across sessions. Your ~/.bashrc lives
there too, so add PATH="$HOME/.local/bin:$PATH" to it once.
Per-project images
----
If you hop between stacks, keep the base image generic and derive one
image per stack, so a Rust project's agent container never carries node
and vice versa. The path goes from a throwaway experiment to a
committed file, in three steps.
1. Explore first, simple mode: a writable root shell on the base image
with one direct podman command:
$ podman run -it --rm --user root localhost/corral:latest bash
apt-get works in there and everything vanishes on exit. Use it to
pin down the exact package list your stack needs.
2. Codify it in a Containerfile.<stack> next to the base one. A derived
Containerfile is three meaningful lines plus the root/agent user
switch:
FROM localhost/corral:latest
USER root
RUN apt-get update \
&& apt-get install -y --no-install-recommends nodejs npm \
&& rm -rf /var/lib/apt/lists/* \
&& node --version
USER agent
The USER switch matters: the base image ends as the unprivileged
agent user, so apt needs root and the result must drop back.
Ending the RUN with a --version check keeps the base image's
fail-loudly-at-build convention.
3. Build it once under the localhost/corral-* naming convention (plain
podman build; harness build always targets the base), then select it
per invocation:
$ podman build -t localhost/corral-node -f Containerfile.node .
$ HARNESS_IMAGE=localhost/corral-node harness claude
To make it stick per project, see "Selecting the image per project"
below.
Notes that follow from the design:
- The corral-home volume is shared by every image: logins, gitconfig,
and bashrc carry over with no re-auth.
- harness build and update always target the base image. A base
rebuild leaves derived images on the old layers; rebuild each
Containerfile.<stack> afterward.
- destroy, purge, and status act on whatever HARNESS_IMAGE selects.
destroy retires one derived image and keeps logins; purge also
deletes the shared volume -- the logins for ALL images.
- The localhost/corral-* name is what lets nuke find and remove
derived images; stray tags outside the convention survive it.
Selecting the image per project
----
Each client repository names its image in a direnv .envrc, loaded by
hand rather than by a shell hook:
$ sudo pacman -S direnv # no hook line in ~/.bashrc needed
Once per repository, write the .envrc and ignore it. harness envrc
does both for any number of projects, and wildcards work quoted or not:
$ harness envrc astro ~/clients/*
ok ~/clients/acme: created .envrc, added /.envrc to .gitignore
ok ~/clients/globex: .envrc already set, .gitignore already ignores .envrc
error ~/clients/notes.txt: not a directory
error ~/clients/old-site: not a git repository
2 succeeded, 2 failed
The image is a full name or a short one: astro means
localhost/corral-astro, and it must already exist. For each project it:
- creates .envrc, replaces an existing HARNESS_IMAGE line, or appends
the line to a .envrc you already had;
- adds /.envrc to .gitignore unless a rule for it is already there;
- refuses directories that are not git repositories, and any project
that commits its own .envrc -- that file belongs to the client, so
it prints the line to add by hand instead.
It is safe to rerun, and exits non-zero if any project failed. It
requires direnv, since the files do nothing without it.
Then approve each new or changed file -- and again after every edit:
$ direnv allow ~/clients/acme
Every time:
$ direnv exec . harness
$ direnv exec . harness claude
$ direnv exec . harness npm test
direnv exec loads .envrc for that one command only, so nothing lingers
in your shell: a terminal that just worked on one client cannot carry
its image into another client's directory.
Forgetting direnv exec is caught: plain harness in a project whose
.envrc sets HARNESS_IMAGE stops with the command to use, or with the
install hint when direnv is missing, instead of quietly starting the
base image. An explicit HARNESS_IMAGE=... harness still runs.
direnv allow is an approval of the file's current contents, not part of
the command. Never chain it in front of every run: direnv refusing an
edited .envrc is the cue to read the change before allowing it again.
A shorter name, in ~/.bashrc:
hx() { direnv exec . harness "$@"; }
Without direnv, source .envrc works too, but the variable then stays set
in that shell until unset HARNESS_IMAGE, and nothing asks for approval.
Parallel instances
----
Run as many harness containers at once as you like -- a test suite for
one client in one terminal, development on another client's site in
the next. Each invocation is its own container, named after the image,
the project directory, and the harness PID:
$ cd ~/clients/acme && HARNESS_IMAGE=localhost/corral-astro harness npm test
harness: corral-astro-acme-4242
harness: http://127.0.0.1:4321 -> container port 4321
harness: http://127.0.0.1:8000 -> container port 8000
harness: http://127.0.0.1:8080 -> container port 8080
$ cd ~/clients/globex && HARNESS_IMAGE=localhost/corral-astro harness
harness: corral-astro-globex-4310
harness: http://127.0.0.1:4322 -> container port 4321
harness: http://127.0.0.1:8001 -> container port 8000
harness: http://127.0.0.1:8081 -> container port 8080
Ports come from the image's EXPOSE list and are published on host
localhost only. Each one keeps its own number when free and otherwise
takes the next free one, so the first container gets the familiar
ports and later ones are offset. Inside every container the servers
still listen on the original ports; only the host side moves. The
base image exposes nothing, so plain harness runs publish nothing.
- HARNESS_PORTS="3000 5173" publishes that list instead of EXPOSE;
HARNESS_PORTS= (empty) publishes nothing.
- harness status, or podman ps, lists the running containers and
their port mappings.
- Starting several at the same moment is safe: each harness reserves
its host ports (in $XDG_RUNTIME_DIR/corral-ports-<uid>) for as long
as it runs, since the container itself binds them only seconds
later. The reservation ends when that harness exits.
- A derived image's run label (podman container runlabel) binds fixed
host ports, so it stays one container at a time. Use harness when
you want several.
All instances share the corral-home volume, so logins and agent config
are the same in each. Processes are not shared: each container runs
its own gpg-agent, with its sockets in the container's /run, so a key
unlocked in one container stays locked in the others and pinentry
always prompts in the container that asked. Unlock once per
container, e.g. gpg -o /dev/null -s /dev/null.
First login
----
No browser exists in the container; all four tools print a URL to open
in your host browser instead.
- claude: prints a login URL; or export ANTHROPIC_API_KEY.
- codex: choose Sign in with Device Code, same Sign in with ChatGPT,
same plan-included usage, only the handshake differs. Personal
accounts may first need device code login enabled in ChatGPT
security settings. Credentials are stored file-based in the volume,
since there is no keyring.
- opencode: run opencode auth login, follow the URL.
- agy: prints an authorization URL plus a one-time code.
Git identity: the host ~/.gitconfig is deliberately not mounted, so the
first commit from inside fails with "Please tell me who you are".
One-time fix, inside harness shell:
$ git config --global user.name "Your Name"
$ git config --global user.email "your@email.com"
It lands in the volume and sticks. Using a distinct address here makes
agent-authored commits distinguishable from your own.
Lifecycle
----
$ ./harness update # rebuild without cache -> latest CLIs
$ ./harness backup # export logins/state, gpg-encrypted
$ ./harness restore corral-home-YYYYMMDD.tar.gpg
$ ./harness destroy # remove image + containers, KEEP logins
$ ./harness purge # remove absolutely everything
$ ./harness nuke # purge + base image + derived images +
# dangling layers (full uninstall)
$ ./harness status # what exists right now
backup defaults to gpg symmetric mode (it prompts for a passphrase). If
you already have a GPG keypair, encrypt to it instead -- no passphrase
to remember, decryption goes through your normal key and agent:
$ AI_GPG_RECIPIENT=you@example.com ./harness backup
destroy then build later means fresh binaries, same logins, zero
re-auth.
nuke is the full uninstall short of removing podman itself: on top of
purge it deletes every localhost/corral* image, the upstream base image
the build pulled, and dangling layers left by interrupted builds. It
asks for confirmation unless given -y, deliberately never runs prune -a
(unrelated images on the machine survive), and never deletes backup
files -- it lists any it finds instead. Afterward only podman itself
and your /etc/subuid entries remain; remove those with pacman and by
editing /etc/subuid and /etc/subgid if podman is no longer wanted at
all.
Backups contain live OAuth credentials -- treat them like passwords.
Never commit them or drop them unencrypted into a sync folder.
Logging in fresh per machine is safer than sharing a backup across
machines.
Multi-machine
----
On each machine: install podman and podman-compose, clone this
repository, and run ./harness build.
For byte-identical images everywhere, either pin versions (CODEX_VERSION
build arg; CLAUDE_CHANNEL; the installers otherwise fetch latest) or
build once and push the tagged image to a private registry.
First-build verification
----
Two seeded settings are best-effort and worth a one-time check:
1. ~/.codex/config.toml sets cli_auth_credentials_store = "file". If a
future codex release complains about the key, delete the file --
codex falls back to file storage when no keyring exists.
2. AGY_CLI_DISABLE_AUTO_UPDATE may be a no-op depending on the agy
version. Harmless either way: the rootfs is read-only and the binary
root-owned, so self-update physically cannot succeed.
Two build details, for when an install step breaks:
- The opencode installer nowadays ignores OPENCODE_INSTALL_DIR and
hard-codes $HOME/.opencode/bin, so the Containerfile lets it install
into the throwaway build HOME and copies the binary to
/usr/local/bin itself -- the same pattern claude and agy already
used. Installers fetch "latest"; if one changes its interface
again, expect the same class of failure and the same class of fix.
- Every CLI step ends with a --version self-check, so a broken
download or unrunnable binary fails the build loudly at its own step
instead of surfacing at first use.
Smoke test after building:
$ ./harness codex --version
$ ./harness claude --version
$ ./harness opencode --version
$ ./harness agy --version
Then, inside a harness shell started from a project directory:
$ touch testfile && ls -l testfile
That should show the file owned by your user on the host. If it shows a
UID like 100999, your podman-compose is too old to pass userns_mode
through -- update it, or add --userns=keep-id to the run via
podman_args.
Security boundary
----
This isolates your host filesystem and keeps the host clean. It does
not make the agents safe in an absolute sense:
- They can read and write everything in the mounted project.
- They can read the credentials in the volume.
- They have network access, so anything they can read, they can in
principle transmit.
- Containers share the host kernel; this is not a VM boundary.
Never mount ~/.ssh, cloud credential dirs, SSH_AUTH_SOCK, or the Podman
socket into it. Never add privileged: true to make a tool's nested
sandbox work -- the container is the sandbox layer here. Keep each
CLI's approval prompts on. For repos you do not trust at all, use a VM
instead.
License
----
Copyright (C) 2026 Thiago C. Silva <librefos@newliber.com>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.