
ilo
Teach Claude to manage reproducible build environments with the ilo CLI.
- GitHub stars
- 21
Install
/plugin install ilo@metioRun it inside Claude Code after adding the marketplace with /plugin marketplace add metio/ilo.
Contents
Discovered from sourceSkills 1
Using ilo
ilo manages reproducible build environments by wrapping a container runtime
(Podman, nerdctl, Docker, or Apple's container). Instead of installing a
project's toolchain on the host, you run commands inside a container built
from the project's image or Containerfile. The container is persistent and
reused across runs, the project directory is mounted read-write, and with the
default rootless Podman runtime files written inside the container stay owned by
you on the host.
The core idea for an agent: don't run build/test commands on the host — run
them through ilo so the right toolchain is present and the build is
reproducible.
--help is the source of truth
This skill ships separately from the ilo binary, so the installed version may be
newer or older than what is described here. Treat the installed binary as
authoritative: run ilo --help and ilo <subcommand> --help to confirm the
available subcommands, flags, and defaults before relying on anything below. The
patterns in this skill describe the stable command surface; if a flag named here
is rejected, check --help rather than assuming the command is wrong.
When this applies
Treat ilo as the way to run tooling when any of these are true:
ilois onPATH, AND- the project has one of:
.ilo.rc,.ilo/ilo.rc, anILO_RCenv var,dev/argument files (plain-text files of ilo args), aContainerfile/Dockerfile, adevcontainer.json(.devcontainer/devcontainer.jsonor.devcontainer.json), adevfile.yaml, or a compose file; OR - a command you need to run requires a toolchain that is not installed on the host.
If the host already has the toolchain and the project shows no sign of ilo, prefer running commands directly.
Setting up a project
When a project could use ilo but isn't wired up yet, offer to set it up — show
what you'll add and ask first, don't do it silently. Before creating an rc file,
check the repo's CLAUDE.md / docs: some repos deliberately forbid an auto-loaded
rc file and use explicit @dev/... argument files instead.
Respect that.
1. Offer a Containerfile
If no image already carries the project's toolchain, offer to create a
Containerfile tailored to it. Detect the stack from its build files (pom.xml,
package.json, go.mod, Cargo.toml, …), start from an official base image for
that toolchain, and add only what the build actually needs. Put it at
dev/Containerfile and build from it with --containerfile.
Show the file and get sign-off before writing it.
2. Detect the runtime and its mode
How files written in the container end up owned on the host depends on which runtime ilo uses and whether it runs rootless or rootful — so determine this before writing the rc file, and use it both to construct the rc and to interpret the ownership check in step 4.
- Which runtime ilo will use: it honors
--runtime/$ILO_SHELL_RUNTIME, else auto-selects the first installed of podman → nerdctl → docker → container. Check what's onPATH(command -v podman nerdctl docker). - Which mode:
- Podman / nerdctl:
podman info --format '{{.Host.Security.Rootless}}'(true= rootless). - Docker:
docker info --format '{{.SecurityOptions}}'— containsrootlesswhen in rootless mode; Docker Desktop maps ownership like rootless via its VM.
- Podman / nerdctl:
ilo's --update-remote-user-uid
is on by default and does the right thing per runtime — keep it on. The
behavior to expect:
| Runtime / mode | Root image | Non-root image (most current images) |
|---|---|---|
| rootless Podman / nerdctl | owned by you — nothing to do | --userns=keep-id maps the user to you (auto; name it with --remote-user if not detected) |
| rootless Docker / Docker Desktop | owned by you | owned by you |
| rootful Docker | runs as your host UID, so /root/... paths may be unwritable — redirect caches to a mounted path | a derived image remaps the user to you |
The cache-redirect pattern (step 3) is doubly useful: it also sidesteps the
rootful-Docker case where a root image can't write /root.
3. Create an .ilo.rc to simplify invocation
An rc file removes the shell <options> <image> boilerplate so every call becomes
just ilo <command>. Create .ilo.rc in the project root with the shell
subcommand, the image (or --containerfile + an image name to build), any cache
mounts, and any ownership flag step 2 calls for — one argument per line:
shell
--containerfile dev/Containerfile
--volume ${XDG_CACHE_HOME:-$HOME/.cache}/maven:/cache:z
--env MAVEN_ARGS=-Dmaven.repo.local=/cache
dev/my-project:latest
The cache mount above points Maven's local repository at /cache (a host
directory) so dependencies survive between runs — see
references/commands.md for the equivalent for Gradle,
Cargo, Go, npm, and others. Redirecting the tool's cache to a fixed path you mount
is more robust than mounting onto the image's default location, which varies by
image (and is often unwritable, since most current images run as a non-root user).
Add --remote-user <name> (or --runtime <name>) here only if step 2 / step 4
shows you need it — ilo's defaults usually suffice.
With that in place, ilo prepends those args automatically, so the trailing command runs inside the container:
ilo mvn verify # runs `mvn verify` in the container
ilo go test ./...
ilo bash -c 'cd web && npm ci && npm run build' # complex / multi-step cases
ilo bash -c '...' is the go-to for anything with pipes, &&, cd, or quoting;
it needs bash in the image — use sh -c '...' for minimal images.
An .ilo.rc is host-specific (local cache paths, host-dependent ownership
settings), so it must not be shared. After writing it, if the project is a git
repository and the file isn't already ignored, add it to .gitignore
automatically:
# only if inside a work tree and not already ignored
git rev-parse --is-inside-work-tree >/dev/null 2>&1 \
&& ! git check-ignore -q .ilo.rc \
&& printf '\n# ilo per-developer config (host-specific)\n.ilo.rc\n.ilo/\n' >> .gitignore
If there is no git repository, skip this step — do not create one.
Two things to know about rc files: ilo loads .ilo.rc on every invocation in
that directory and expands its values with your host shell, so it asks you to trust
the file the first time. In a non-interactive session an untrusted file is
silently skipped — so right after creating one, the next automated ilo <command>
may run without the image/options and fail confusingly. Have the user run ilo
once interactively to trust it, or fall back to an explicit @dev/run argument file
(which needs no trust prompt).
4. Verify read/write and file ownership
Before generating any build artifacts, confirm that files written inside the
container land on the host owned by you, not by root (or a phantom sub-UID).
Run the check through the rc file you just created, so it exercises the real
runtime, image, and flags:
ilo bash -c 'echo ok > .ilo-write-test'
ls -l .ilo-write-test # must be owned by your host user, not root
rm .ilo-write-test
If it comes back owned by root/another UID or won't delete without sudo, stop
and apply the remedy for your runtime and mode from step 2 — typically
--remote-user <name> on rootless Podman/nerdctl, or switching to rootless Docker
(or redirecting the tool's cache to a mounted path) on rootful Docker — then add
that flag to .ilo.rc and re-check. Full details:
https://ilo.projects.metio.wtf/usage/file-ownership/.
Alternative: a committed devcontainer.json
When the environment should be shared with the team and committed — and usable
by editors that read devcontainers, not just ilo —
describe it in a devcontainer.json and point the rc file at ilo devcontainer
instead of ilo shell. Split by what is portable:
-
devcontainer.jsonis committed, so it must contain no host paths or other host-specific settings. Put the portable configuration here — ilo readsimage/build.dockerfile,containerEnv(cache-redirect vars such asCARGO_HOME=/cacheare portable),remoteUser(the ownership fix for root images — portable, use it instead of--remote-user),remoteEnv,forwardPorts,workspaceFolder, and the lifecycle commands (postCreateCommand, …). Persist caches with a named volume, which has no host path, survives recreation, and side-steps host file ownership entirely:{ "image": "docker.io/library/rust:latest", "containerEnv": { "CARGO_HOME": "/cache" }, "mounts": ["source=myproject-cache,target=/cache,type=volume"] }Do not put a host bind-mount (
source=/home/...) here — it would break for everyone else. Use a named volume, or keep host-path caches in theilo shellsetup. -
.ilo.rcstays host-specific and git-ignored (step 3), but now just selects the devcontainer workflow plus any host-only toggle (e.g. a forced--shell-runtime):devcontainer
Then ilo opens the shared environment, applying the file's lifecycle. Two
differences from the ilo shell setup:
ilo devcontaineralways opens an interactive shell and does not accept a trailing command — positional arguments aredevcontainer.jsonlocations, so theilo mvn verify/ilo bash -c '...'shortcut does not apply. For non-interactive one-offs (CI, automation), keep anilo shellrc; drive automated setup throughpostCreateCommandinstead.- ilo searches
.devcontainer/devcontainer.jsonthen.devcontainer.json.
Alternative: a committed devfile.yaml
For teams standardizing on devfiles (odo, Eclipse Che), point
the rc file at ilo devfile. ilo opens the first component that declares an image
(or a local Dockerfile), mapping its image, container env (cache-redirect vars are
portable), and mountSources / sourceMapping (the project mount):
schemaVersion: 2.2.0
metadata:
name: my-project
components:
- name: dev
container:
image: docker.io/library/rust:latest
mountSources: true
sourceMapping: /workspace
env:
- name: CARGO_HOME
value: /cache
# .ilo.rc (host-specific, git-ignored)
devfile
Like ilo devcontainer, this is interactive-only (positional arguments are
devfile.yaml locations, not a command). ilo maps only the component's image, env,
and project mount — it does not bind extra volumes from the devfile, so a cache
redirected via env lives in the reused container (and is cleared by --fresh),
with no named-volume option here. Pick a component with --component <name>; ilo
searches devfile.yaml then .devfile.yaml.
When the project needs companion services: ilo compose
ilo's core job is a complete local dev environment — so when building or testing needs
more than a toolchain (a database, a message broker, a cache server, …), describe the
whole stack in a compose file and switch the setup to ilo compose. It opens a shell
in one service (dev by default) with the others running alongside, which is the right
choice whenever a project can't be built or tested in isolation:
# docker-compose.yml (committed; relative paths + named volumes keep it portable)
services:
db:
image: docker.io/library/postgres:latest
environment:
POSTGRES_PASSWORD: dev
dev:
image: docker.io/library/maven:latest
working_dir: /workspace
volumes:
- .:/workspace # project directory (relative path — portable)
- cache:/cache # named volume for the dependency cache
environment:
MAVEN_ARGS: -Dmaven.repo.local=/cache
depends_on:
- db # the database comes up with the dev shell
volumes:
cache:
# .ilo.rc (host-specific, git-ignored)
compose
Then ilo opens the dev shell with db running (reachable from dev at the
hostname db). Run a one-off non-interactively with
ilo compose --no-interactive dev mvn verify, force a rebuild with --build, or
attach to another service with ilo compose db. The service is the first positional
(default dev); to keep the ilo <command> shortcut, put compose and dev on
separate lines in .ilo.rc so ilo mvn verify runs in the dev service. As with
devcontainer.json, keep host paths out of the committed compose file — use relative
mounts and named volumes, or compose's ${VAR} interpolation for anything truly
host-specific. ilo compose needs a compose runtime (Docker Compose, podman-compose,
or nerdctl) on PATH.
How to run commands
Pick the first pattern that fits. Always run non-interactively for automation — never open a bare interactive shell you can't exit.
1. Use the project's argument files (preferred). ilo argument files are
plain-text files of ilo args, invoked with an @ prefix. Projects commonly keep
them under dev/. They usually already set --no-interactive and the command to
run:
ilo @dev/build # e.g. runs `mvn verify` in the project's container
ilo @dev/test
List candidates first (e.g. ls dev/) and read one to see what it does before
running it.
2. Project has an rc file — run an ad-hoc command. When .ilo.rc or
.ilo/ilo.rc exists, ilo auto-loads it (it supplies shell, the options, and
the image), so trailing arguments become the command run inside the container:
ilo go build ./...
ilo go test ./...
3. No rc/arg file — run a one-off explicitly. Name the subcommand, the
image, and the command, and pass --no-interactive:
ilo shell --no-interactive docker.io/library/maven:latest mvn -q verify
ilo shell --no-interactive --volume ${XDG_CACHE_HOME:-$HOME/.cache}/maven:/cache:z --env MAVEN_ARGS=-Dmaven.repo.local=/cache docker.io/library/maven:latest mvn -q verify
Subcommands
ilo shell— single container from an image orContainerfile. The workhorse.ilo compose— environment backed by a compose file (use when the build needs companion services like a database). Defaults to thedevservice.ilo devcontainer— reads adevcontainer.jsonand injects its lifecycle.ilo devfile— reads adevfile.yamland injects its lifecycle.
All four take the same shell-style options below and run a command the same way
(ilo compose --no-interactive dev mvn verify).
Common, stable flags
These are the flags you reach for most; they are part of the stable surface. For
the complete, version-accurate list and defaults, use ilo <subcommand> --help.
--no-interactive— run one command and exit (do this for automation).--containerfile/--dockerfile <file>— build the image from a file first.--volume host:container:z— mount a host directory (e.g. a dependency cache) into the container. Pair it with the tool's own cache-dir env var (seereferences/commands.md) so downloads survive between runs.--env KEY=value— set an environment variable.--remote-user <name>— run as (and align to your host user) the named container user. Use it when an image runs asrootbut writes files you need to own on the host: running as the image's non-root user (e.g.--remote-user gradle) keeps caches and outputs owned by you instead of an unmanageable sub-UID.--publish host:container— expose a port.--pull— re-pull the image (and recreate the container) before running.--fresh— discard the reused container and recreate from scratch.--remove-image— remove the container and its image on exit (clean slate).--runtime podman|docker|nerdctl|container— force a runtime; otherwise ilo auto-selects podman → nerdctl → docker → container.--no-rc— run without loading any rc files (goes before the subcommand:ilo --no-rc shell ...).
Run ilo <subcommand> --help for the full list, or read references/commands.md
for a fuller cheatsheet.
Recurring env vars and flags belong in .ilo.rc
--env KEY=value sets an environment variable inside the container. When a build
needs the same variable on every run, set it once in .ilo.rc instead of
prefixing each command with it. For example, rather than repeating
ilo bash -c 'GOSUMDB=off go test ./...'
add the variable to .ilo.rc once and let every command inherit it:
shell
--containerfile dev/Containerfile
--volume ${XDG_CACHE_HOME:-$HOME/.cache}/go:/cache:z
--env GOMODCACHE=/cache/mod
--env GOCACHE=/cache/build
--env GOSUMDB=off
dev/my-project:latest
ilo go test ./... # GOSUMDB=off and the cache mounts applied automatically
The same holds for any flag that belongs on every run (--volume, --publish,
--remote-user, …): put it in .ilo.rc rather than retyping it.
But edit .ilo.rc deliberately — each change costs an approval. Editing the
file re-triggers ilo's trust prompt: the next interactive run requires you to
re-approve the rc file before it is loaded (and a non-interactive run silently
skips an untrusted file — see Notes & cautions below). So only add an env var or
flag you are confident you will need for all containers and runs in this
project, and when several are needed, add them in a single edit rather than one at
a time — fewer edits mean fewer manual approvals.
Notes & cautions
- rc files run host shell expansion.
.ilo.rc/.ilo/ilo.rcare discovered automatically and their values are expanded by your host shell, so loading one can run arbitrary commands. The first time ilo sees an untrusted rc file it prompts to trust it; in a non-interactive session an untrusted file is not loaded. If a command silently runs without the expected environment, an untrusted rc file may have been skipped — run it interactively once to trust it, or use an explicit@dev/...argument file instead. - Don't add an rc file to a repo that forbids it. Some repos (ilo's own, for
example) explicitly tell you not to add
.ilo.rc/.ilo/ilo.rcbecause ilo auto-loads them on every invocation. Use explicit@dev/...argument files there. Check the repo'sCLAUDE.md/ docs before creating an rc file. - Always use long-form image references — include the registry everywhere you
name an image (
ilocommands,.ilo.rc/ argument files,ContainerfileFROMlines, compose files):docker.io/library/golang:latest, notgolang:latest;ghcr.io/.../mcr.microsoft.com/...keep their host. Short names rely on registry-search resolution that differs by runtime and can fail or pull the wrong image under Podman/Fedora; the long form works identically everywhere. - First run is slow (pull/build); later runs reuse the container and are fast.
- Apple
containerruntime is macOS-only and single-terminal; it needscontainer system startonce per boot.
For full docs see https://ilo.projects.metio.wtf/.
Sponsors
Details
- Marketplace
- metio/ilo
- Category
- Community
- License
- 0BSD
- Keywords
- ilo, containers, reproducible-builds, build-environments