Skip to content
librefosPublic

About

Disposable rootless Podman sandbox for AI coding agents

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

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/>.

About

Disposable rootless Podman sandbox for AI coding agents

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Used by

Contributors

Languages