Module container 

Container management for container-type agent panes (Phase 1).

Manages persistent Docker containers — one per container agent. Each container runs the configured image (e.g. ghcr.io/agentmuxai/agent-claude) with tini as PID 1 and is kept alive between turns. Individual turns are executed via docker exec -i (no -t — avoids CR/LF corruption of NDJSON).

Platform support (cross-platform, matches SPEC_CONTAINER_PANE_SUPPORT_2026_06_11.md):

• Windows: named pipe //./pipe/docker_engine
• macOS: socket resolved via docker context inspect (Docker Desktop or Rancher)
• Linux: /var/run/docker.sock or rootless path in XDG_RUNTIME_DIR

Independence boundary: this module has no dependency on a5af/claw. Docker best practices here were researched independently.

Structs

ContainerManager

Shared container manager. Clone-on-Arc; cheap to pass around.

ContainerManagerInner 🔒

ContainerMountSpec

Host directories a container agent needs mounted to be able to work.

ContainerRuntimeHandle

Self-healing holder for the container runtime connection.

ExecOutcome 🔒

What a collected exec produced.

ExecSession

Exec session handle for a single turn.

Enums

CliProvision

Whether provision_cli found the CLI in place or had to install it.

ContainerError

Errors from container operations.

RuntimeSlot 🔒

State of the container-runtime slot held by ContainerRuntimeHandle.

Constants

AGENTMUX_DOCKER_NETWORK

Shared user-defined Docker bridge network every agent container is attached to, ADDITIVE to whatever network_mode/extra_hosts already set up (container→host reachability, unaffected — see the doc comment on network_mode below). Unlike the default bridge network, a user-defined one gives per-container DNS resolution and lets the native dev-proxy (backend::dev_proxy) route to a container by its internal IP. See docs/specs/SPEC_NATIVE_CONTAINER_DEV_PROXY_2026_09_19.md §3.1.

CLAUDE_CREDENTIALS_FILE

The credentials file inside the account’s config dir, and inside the image.

CONTAINER_CLAUDE_DIR

Where the agent CLI’s config dir lives inside the image (CLAUDE_CONFIG_DIR).

CONTAINER_ENV_DENYLIST

Env var names that reference host-filesystem paths and must NOT be forwarded into a container via docker exec -e. The container image supplies its own values for these (e.g. CLAUDE_CONFIG_DIR=/home/agent/.claude baked in).

CONTAINER_WORKSPACE_DIR

Where the agent’s working directory is bind-mounted inside the image.

Functions

agent_home_mounts 🔒

The mounts that make up the agent’s home dir inside the container.

agent_id_from_container_name 🔒

Reverses container_name_for_slug — "agentmux-foo" → Some("foo"). Used by cleanup_dev_proxy_routes to key off the container name alone (stop/remove only get a container_name, not the agent’s own id).

cli_dir_mount 🔒

The per-agent volume the provider CLI is installed into.

container_name_for_slug

Derive the stable container name for an agent from its slug. Format: agentmux-<slug>. Deterministic so restarts reuse the same container.

credentials_dir_if_file_backed

The account config dir to hand to ContainerMountSpec::claude_config_host_dir, or None when this account has no file-backed credential to mount.

fold_mount_source 🔒

Canonical form of a mount source for comparison.

normalize_host_path 🔒

Normalize a host path for Docker’s mount API: backslashes are not accepted in a bind source, so C:\Users\x has to travel as C:/Users/x.

parse_id_output 🔒

Parse id -u; id -g output into (uid, gid).

parse_volume_spec 🔒

Parse a Docker volume spec into (source, target, read_only).

pull_error 🔒

Map a bollard pull error to ContainerError::ImagePull.

rewrite_local_url_for_container

Rewrite a host-loopback AGENTMUX_LOCAL_URL (e.g. http://127.0.0.1:PORT) into something a container’s network namespace can actually reach.