This page covers the launcher, raw docker run and podman run commands, health checks, sudo, file ownership and upgrades.
- The launcher
- Development server ports
- Without the launcher
- Container health
- sudo
- File ownership
- Other options
- Upgrading
bin/agentainer wraps the run and exec commands below. It uses Podman when it finds it, otherwise Docker, and prints each command before it runs it.
| Command | What it does |
|---|---|
agentainer up [--name N] [--sudo] [--image I] [--publish MAPPING ...] [--] [DIR] |
Starts a detached container. DIR defaults to the current directory and becomes /workspace. |
agentainer attach [N] |
Runs tmux new-session -A -s main in the container |
agentainer shell [N] |
Opens a bash login shell |
agentainer start [N] |
Starts a stopped container, for example after the host or the Podman machine restarts |
agentainer update [N] |
Pulls the image the container was created from and recreates the container with the same options (upgrading) |
agentainer down [N] |
Removes a container carrying the Agentainer label. It refuses unrelated containers. The home volume stays. |
agentainer status |
Lists agentainer containers |
agentainer doctor [N] [--json] |
Runs offline diagnostics in the running container, without a TTY; see diagnostic checks and exit codes. |
N defaults to agentainer. These variables override the launcher's defaults:
| Variable | Default |
|---|---|
AGENTAINER_IMAGE |
ghcr.io/chadmayfield/agentainer:latest |
AGENTAINER_ENV_FILE |
~/.config/agentainer/env |
AGENTAINER_HOME_VOLUME |
agentainer-home |
AGENTAINER_RUNTIME |
podman if installed, else docker |
For a host directory instead of the default named home volume, set AGENTAINER_HOME_VOLUME to an existing directory such as "$HOME/.config/agentainer/home". Both mount at /home/agent. Customizing Agentainer covers setup, your own dotfiles and separate test homes.
Home sources containing /, or exactly . or .., are host paths. Other values are named volumes. Use ./myhome for a relative directory rather than myhome. The launcher warns if a mount exposes the host home, a parent of it, or the host root. Choose a project directory to limit access.
Limits:
- DIR must not contain
:, because-vsplits its value at:. Rename the directory to remove:. - Container names also serve as hostnames. They must be at most 64 ASCII characters and start with a letter or digit (launcher, hostname limit).
updatepulls from a registry, so it cannot update a container that runs an image you built locally (localhost/...). Useagentainer downandagentainer up --image ...for those.
up passes your shell's locale and time zone into the new container with -e:
LANGandLC_ALL.- The locale categories glibc defines:
LC_CTYPE,LC_NUMERIC,LC_TIME,LC_COLLATE,LC_MONETARY,LC_MESSAGES,LC_PAPER,LC_NAME,LC_ADDRESS,LC_TELEPHONE,LC_MEASUREMENTandLC_IDENTIFICATION. OtherLC_names, such as iTerm2'sLC_TERMINAL, stay on the host. TZ. WhenTZis unset, the launcher reads the zone name from the/etc/localtimelink, the part afterzoneinfo/. On macOS that link is/var/db/timezone/zoneinfo/America/Denver, for example.
The launcher skips a value it cannot use:
- A locale must be
C.UTF-8,C.utf8, orlanguage_TERRITORY.UTF-8(or.utf8) with an optional@modifier, such asen_US.UTF-8orsr_RS.UTF-8@latin. Other codesets, and macOS's bareLC_CTYPE=UTF-8, are skipped, because tmux needs a UTF-8 locale. TZmust be a zone name such asAmerica/DenverorUTC. A value that starts with:names a file and is skipped.
Variables your env file sets win. Both runtimes let -e override --env-file (docker/cli opts/parse.go, Podman environment precedence), so the launcher reads the variable names in the env file and does not pass those variables. It reads names only and never prints the file's values.
up records what it passed in the io.github.chadmayfield.agentainer.locale label. update passes those recorded values again and does not read your current shell, so an update from cron or SSH changes nothing. A container created before the label existed gets no locale or time zone from update. A value passed from your shell changes only when you run agentainer down and then agentainer up; the home volume stays. A LANG or TZ set in the env file is read again on every update, so editing it there takes effect on update.
Repeat --publish or -p before DIR to publish development servers to the host:
bin/agentainer up --publish 3000:3000 --publish 8080:8000 "$HOME/code"This maps host ports 3000 and 8080 to container ports 3000 and 8000. Open http://127.0.0.1:8080 on the host for a server on container port 8000. The server must listen on the container's network interface, for example 0.0.0.0, not only on its own loopback address (Docker publishing, Podman publishing).
Each mapping is [IPv4:]HOST_PORT:CONTAINER_PORT[/tcp|udp]:
| Form | Example | Result |
|---|---|---|
| No address | --publish 3000:3000 |
Binds 127.0.0.1 on the host, TCP |
| UDP | --publish 5353:5353/udp |
UDP instead of TCP |
| Explicit address | --publish 0.0.0.0:3000:3000 |
Binds all host IPv4 interfaces |
| Joined forms | --publish=3000:3000, -p3000:3000 |
Accepted |
| IPv6, port ranges, automatic host ports | Not supported; use a direct runtime command |
The optional extras Kandev and OpenChamber are web apps that need a published port:
# Kandev
bin/agentainer up --publish 38429:38429 "$HOME/code"
kandev --port 38429 --headless # inside the container
# OpenChamber
bin/agentainer up --publish 3000:3000 "$HOME/code"
openchamber --lan --port 3000 --ui-password '<password>' # inside the containerKandev's local mode is not an authenticated multi-user boundary, and OpenChamber needs --ui-password to protect browser access, so keep the default 127.0.0.1 host binding (Kandev, OpenChamber).
Ports must be 1 through 65535. For a remote engine, the bind address belongs to the engine host. With a local VM, reachability also depends on the runtime's port forwarding.
The launcher validates mappings before it creates a container and before it pulls an update. With no --publish option, it publishes no ports. update keeps the recorded mappings. Containers created by older launchers without a ports label publish no ports. To change the mappings, recreate the container with new up options; the home stays.
Use a published version tag. The registry has no latest manifest until a stable release publishes it (release policy).
docker run -d --name agentainer --hostname agentainer \
--security-opt no-new-privileges=true \
--sysctl "net.ipv4.ping_group_range=1000 1000" \
-v agentainer-home:/home/agent \
-v "$HOME/code:/workspace" -w /workspace \
--env-file "$HOME/.config/agentainer/env" \
ghcr.io/chadmayfield/agentainer:0.1.0-dev.20261024.1
docker exec -it agentainer tmux new-session -A -s mainWith Podman, use the same commands and add --userns=keep-id:uid=1000,gid=1000. It maps your host user to the container user, so files in /workspace stay yours (man podman-run).
- The container runs
sleep infinityundertinias PID 1. Sessions areexeccalls into tmux, so agents keep running when a terminal or SSH connection drops. - The whole home directory
/home/agentis one volume. Logins, settings andAGENTS.mdlive there and survive a new container. Containers that use the same volume share logins, and two containers running the same agent write the same files. - The
ping_group_rangesysctl letspingwork without theNET_RAWcapability. It names only GID 1000: with Podman's keep-id the GID map is not contiguous, and a wider range breaks.
The image runs agentainer-healthcheck through the Dockerfile HEALTHCHECK instruction:
| Setting | Value |
|---|---|
| Interval | 30 seconds |
| Timeout | 5 seconds |
| Start period | 180 seconds |
Retries before unhealthy |
3 |
The probe checks the entrypoint's completion marker, read, write and search access to the home directory, and that the active tools symlink points to a readable, searchable directory. Startup clears the marker, including after a restart. The probe reads no agent settings or credentials, runs no agents, changes no home files and makes no network requests. It does not check free disk space or whether each tool works. agentainer doctor checks configuration syntax and that tools start; neither checks free space, so use df -h for that.
Inspect the status and recent probe results from the host:
podman inspect --format '{{json .State.Health}}' agentainer
docker inspect --format '{{json .State.Health}}' agentainerHealth status reports readiness. It does not restart the container. Kubernetes ignores image health checks; configure pod probes separately (Kubernetes probes).
Podman inherits an image health check only from a Docker-format manifest (Podman source). scripts/build.sh builds Docker format with both engines. Release images are OCI manifests with SBOM and provenance attestations, so a raw podman run of a release image needs the probe passed explicitly:
--health-cmd=/usr/local/bin/agentainer-healthcheck --health-interval=30s \
--health-timeout=5s --health-start-period=180s --health-retries=3The launcher does not add these options (Podman options). Older images without the probe need an image update and a new container. Troubleshooting covers Podman-specific health states.
The image has passwordless sudo, and --security-opt no-new-privileges=true turns it off (Docker reference). agentainer up --sudo leaves that option out.
With sudo on, an agent can change anything in the container, including the agent binaries and the settings that stop them from updating themselves. Packages installed with sudo apt install are gone when the container is recreated. Under rootful Docker, container root is UID 0 on the host, limited by the container's namespaces.
- Rootless Podman with keep-id: files in
/workspacebelong to your host user. - Rootful Docker on Linux: files written to
/workspacebelong to UID 1000 on the host. If your UID is different, use Podman or rootless Docker, or build an image with your UID and GID.
scripts/build.sh uses Podman unless RUNTIME says otherwise. On a Docker host:
RUNTIME=docker sh scripts/build.sh --uid "$(id -u)" --gid "$(id -g)"With a GID other than 1000, also set --sysctl "net.ipv4.ping_group_range=<gid> <gid>" in your run command, or ping fails. The launcher always passes 1000 1000.
sh tests/host/test-build-uid.sh builds an image with --uid 1001 --gid 20 and checks the agent user. When the build fails, it prints the last 80 lines of the build output.
-
SSH agent on a Linux host: add
-v "$SSH_AUTH_SOCK:/run/ssh-agent.sock" -e SSH_AUTH_SOCK=/run/ssh-agent.sock. A forwarded agent lets container processes request signatures with its loaded keys, so use a dedicated agent holding only the keys this session needs (credential exposure).ssh-agentrefuses a client whose UID differs from its own unless the client is root (uid mismatchin ssh-agent.c), so the container user needs the UID of the user who started the agent:- Rootless Podman with keep-id, as the launcher runs it, maps your host UID to the container user (podman-run). Not verified with an SSH agent.
- Rootful Docker runs the container user as UID 1000. If your UID is different, build your own image as described in File ownership.
Verified in CI with rootful Docker on Linux only, in a narrow check: CI makes the socket's directory readable, then runs
ssh-add -las the entrypoint with--user "$(id -u):$(id -g)", so the normal entrypoint does not run. Not verified: macOS, where the socket path depends on the runtime. For git, the default isGH_TOKEN(logins). -
SELinux hosts may need
:zon volume mounts. Not verified.
bin/agentainer updateupdate pulls the image the container was created from and recreates the container; the home volume stays. Without the launcher, pull first: a plain run does not pull a newer image for a tag that is already on your machine. For Kubernetes, see docs/kubernetes.md.
How update works:
uprecords DIR, image, sudo setting, home volume, published ports, the env file's absolute path and the locale and time zone it passed as container labels.updatereads them back.updatechanges nothing when the pull fails, when DIR or the env file no longer exists, or when the container has no option labels.- After the pull,
updaterenames the old container tocx-agentainer-backup-Nand stops it. It removes the backup only after the new container starts. If creation or startup fails, it restores the old container in its previous running or stopped state. Changes the new container made to the home or workspace are not rolled back. - Startup may take up to 180 seconds. The new container counts as started when the entrypoint's completion marker exists; for an older image without the marker, when its tools link exists. If the launcher is killed before it can restore a failed update, inspect
cx-agentainer-backup-Nbefore you retry.updaterefuses to overwrite an existing backup. - A successful
updateleaves the new container running, even when the old one was stopped. AGENTAINER_DRY_RUN=1prints the commands that change state instead of running them.updateanddownstill run read-onlyinspectcalls to read the recorded options.
On the first start of the new image, the entrypoint adds files that are missing from your home volume. It does not replace your files with the image's copies, with these exceptions. Each exception changes only the part the entrypoint manages:
| File | What changes | When |
|---|---|---|
~/.agentainer/AGENTS.md |
Replaced with the new default | You never edited it and the image's version allows it; AGENTS.md lists the conditions |
| Agent MCP configs | Servers that agentainer-mcp sync added |
~/.agentainer/mcp.json changed, or you run agentainer-mcp sync (MCP servers) |
~/.gitconfig |
The GitHub credential helper, from gh auth setup-git |
GH_TOKEN or GITHUB_TOKEN is set and this container's gh is not already the helper (GitHub and Git) |
~/.gitconfig |
user.name or user.email |
GIT_AUTHOR_NAME or GIT_AUTHOR_EMAIL is set and the file has no value for it |
~/.config/opencode/service.json |
Created by opencode service set disabled true |
The file does not exist yet |
Everything else:
- Logins, agent settings and history stay.
- New defaults in the image's seed files do not reach an existing home. Compare yours with the image's copies in
/etc/agentainer/home/, for example.claude/settings.jsonand.codex/config.toml. - With
AGENTAINER_TOOLS=persist, tools you installed stay onPATHafter the image's own tools (tools that agents install). - MCP servers sync again only when
~/.agentainer/mcp.jsonchanges. Runagentainer-mcp syncto sync after an upgrade. - Anything installed with
sudo apt installis gone, as after every new container.