agent-containers 0.1.0.dev0__py3-none-any.whl

agent_containers/__init__.py

@@ -0,0 +1 @@
+"""Deterministic onboarding and maintenance for hardened agent containers."""

agent_containers/__main__.py

@@ -0,0 +1,6 @@
+"""Support python -m agent_containers."""
+
+from agent_containers.cli import app
+
+if __name__ == "__main__":
+    app()

agent_containers/_assets/agent-images/adal/Dockerfile

@@ -0,0 +1,103 @@
+FROM python:3.14-slim-trixie AS base
+
+ARG TARGETARCH
+
+# Shared Node.js, containment, gateway-client, and cloudflared baseline for
+# the first-party Python-and-Node workload images.
+COPY --from=shared install-workload-base.sh /usr/local/lib/agent/install-workload-base.sh
+RUN TARGETARCH="$TARGETARCH" bash /usr/local/lib/agent/install-workload-base.sh
+
+COPY --from=shared install-additional-packages.sh /usr/local/lib/agent/install-additional-packages.sh
+COPY packages-apt.txt /tmp/packages-apt.txt
+RUN bash -c '. /usr/local/lib/agent/install-additional-packages.sh \
+        && install_apt_packages /tmp/packages-apt.txt' \
+    && rm -f /tmp/packages-apt.txt
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
+
+# packages-uv.txt — general Python libraries (not CLI tools; see
+# tools-uv.txt below), installed via `uv pip install --system` into this
+# system Python. Runs as root, before the adal user exists, since it writes
+# into the image's system site-packages rather than $HOME.
+COPY packages-uv.txt /tmp/packages-uv.txt
+RUN bash -c '. /usr/local/lib/agent/install-additional-packages.sh \
+        && install_uv_packages /tmp/packages-uv.txt' \
+    && rm -f /tmp/packages-uv.txt
+
+# The official npm fallback ships the platform-specific AdaL runtime as an
+# optional dependency. Pin it so rebuilding does not silently change the CLI.
+RUN npm install -g @sylphai/adal-cli@1.7.1
+
+# The adal account is created here, at a fixed placeholder UID/GID
+# (1000:1000), purely so the root-only installers below (npm, uv tool) have
+# a real non-root account to run as. `final` remaps this account to the
+# operator's actual host UID/GID instead of recreating it, so a rebuild for
+# a different host user reuses everything installed below unchanged rather
+# than reinstalling it over the network.
+RUN groupadd -g 1000 adal \
+    && useradd -m -u 1000 -g 1000 -s /bin/bash adal \
+    && mkdir -p /home/adal/.adal /workspace \
+    && chown -R adal:adal /home/adal /workspace
+
+ENV HOME=/home/adal
+ENV npm_config_prefix=/home/adal/.npm-global
+ENV PATH="/home/adal/.local/bin:/home/adal/.npm-global/bin:${PATH}"
+
+# $HOME (uv's default cache location) and /workspace are deliberately
+# separate mounts in this containment model, so uv's hardlink/reflink
+# optimisation can never apply between them — declare the copy fallback
+# explicit rather than have uv warn about it on every install.
+ENV UV_LINK_MODE=copy
+
+COPY packages-npm.txt /tmp/packages-npm.txt
+COPY tools-uv.txt /tmp/tools-uv.txt
+RUN gosu adal bash -c '. /usr/local/lib/agent/install-additional-packages.sh \
+        && install_npm_packages /tmp/packages-npm.txt \
+        && install_uv_tools /tmp/tools-uv.txt' \
+    && rm -f /tmp/packages-npm.txt /tmp/tools-uv.txt
+
+# Everything above this line is UID/GID-independent and layer-cacheable
+# across hosts: the adal account exists at the fixed placeholder UID/GID
+# only so the installers above have a non-root account to run as. From here
+# down, `final` remaps that account to the operator's actual host UID/GID
+# with --build-arg UID=$(id -u) --build-arg GID=$(id -g) — the base stage
+# above is reused unchanged from cache, and nothing installed above is
+# reinstalled, rather than rebuilding per host user.
+FROM base AS final
+ARG UID=1000
+ARG GID=1000
+
+# Only remap when the caller supplied a different UID/GID than the fixed
+# placeholder baked into `base` above — usermod/groupmod plus a chown -R
+# walk over already-installed content is far cheaper than rerunning the
+# npm/uv-tool installs above, but it's skippable entirely for the common
+# case where the caller never overrides UID/GID. Deliberately no -o:
+# without it, usermod/groupmod refuse to reuse an ID already assigned to
+# another account, so a caller can never remap adal onto UID/GID 0 (root)
+# or collide it with another in-image identity — the build fails instead of
+# silently succeeding.
+RUN if [ "$UID" != "1000" ] || [ "$GID" != "1000" ]; then \
+        groupmod -g "$GID" adal \
+        && usermod -u "$UID" -g "$GID" adal \
+        && chown -R "$UID":"$GID" /home/adal /workspace; \
+    fi
+
+COPY --from=shared egress-allowlist.sh /usr/local/lib/agent/egress-allowlist.sh
+COPY --from=shared workload-entrypoint.sh /usr/local/lib/agent/workload-entrypoint.sh
+RUN chmod +x /usr/local/lib/agent/workload-entrypoint.sh
+
+# Strip setuid/setgid bits from the base image and every package installed
+# above — required infra (install-workload-base.sh), packages-apt.txt,
+# packages-npm.txt, packages-uv.txt, and tools-uv.txt — run last so nothing
+# installed by any of those is missed. NoNewPrivs=1 (set by every documented
+# run invocation) already makes these bits inert on execve, but that's an
+# argument for stripping them, not against: if any single control ever
+# regresses, a setuid-root `mount` becomes a live escalation primitive. None
+# of these binaries are needed at runtime, so none should ship
+# exploitable-shaped.
+RUN find / -xdev -perm /6000 -type f -exec chmod a-s {} + || true
+
+WORKDIR /workspace
+
+ENTRYPOINT ["/usr/local/lib/agent/workload-entrypoint.sh", "adal", "adal"]
+CMD ["adal"]

agent_containers/_assets/agent-images/adal/examples/egress-allowlist.txt

@@ -0,0 +1,10 @@
+# Hosts/IPs the container is allowed to reach outbound, one per line.
+# Blank lines and lines starting with '#' are ignored. Mount this file at
+# /etc/agent/egress-allowlist.txt; it takes precedence over
+# $AGENT_ALLOWED_EGRESS. If neither is set, outbound traffic is denied.
+#
+# AdaL's browser-based sign-in starts at this documented service host. Add
+# only the further hosts required by the features you intentionally enable:
+# direct BYOAK providers, an MCP server, a plugin marketplace, a source host,
+# or a local-model endpoint. Do not use this file to grant broad egress.
+adal.sylph.ai

agent_containers/_assets/agent-images/adal/packages-apt.txt

@@ -0,0 +1,13 @@
+# Optional apt packages installed at build time, one per line.
+# Blank lines and lines starting with '#' are ignored.
+gh
+jq
+ripgrep
+fd-find
+tree
+unzip
+less
+file
+lsof
+yq
+miller

agent_containers/_assets/agent-images/adal/packages-npm.txt

@@ -0,0 +1,2 @@
+# Optional global npm packages installed at build time, one per line.
+# Blank lines and lines starting with '#' are ignored.

agent_containers/_assets/agent-images/adal/packages-uv.txt

@@ -0,0 +1,6 @@
+# Optional Python libraries installed into the system Python at build time
+# via `uv pip install --system`, one per line. Blank lines and lines
+# starting with '#' are ignored. Unlike tools-uv.txt, these land in the one
+# shared system Python rather than an isolated venv, so they're importable
+# by whatever runs inside the image — a CLI-only package with no importable
+# module of its own belongs in tools-uv.txt instead.

agent_containers/_assets/agent-images/adal/tools-uv.txt

@@ -0,0 +1,4 @@
+# Optional Python CLI tools installed at build time via `uv tool install`,
+# each into its own isolated venv, one per line. Blank lines and lines
+# starting with '#' are ignored. A plain importable library (no
+# console-script entry point of its own) belongs in packages-uv.txt instead.

agent_containers/_assets/agent-images/agent-gateway/Dockerfile

@@ -0,0 +1,50 @@
+FROM debian:trixie-slim
+
+ARG TARGETARCH
+
+RUN apt-get update \
+    && apt-get upgrade -y \
+    && apt-get install -y --no-install-recommends \
+        ca-certificates \
+        iptables \
+        ipset \
+        dnsmasq \
+        dnsutils \
+        openssh-server \
+        python3 \
+        curl \
+    && curl -fsSL "https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-${TARGETARCH}" \
+         -o /usr/local/bin/cloudflared \
+    && chmod +x /usr/local/bin/cloudflared \
+    && rm -f /etc/ssh/ssh_host_* \
+    && rm -rf /var/lib/apt/lists/*
+# python3 isn't used by anything in this image — it's what sshuttle execs
+# remotely over the SSH session from the claude-code side. The entrypoint
+# copies the mounted public key to a root-owned runtime path under /run, so
+# it works with a read-only root filesystem without CAP_CHOWN. cloudflared
+# is always installed but only ever invoked (see entrypoint.sh) when
+# CLOUDFLARE_TUNNEL_TOKEN is set — the direct-TCP path (Task 4) needs no
+# Cloudflare account and stays completely unaffected by its presence.
+# TARGETARCH is supplied automatically by Buildx and matches cloudflared's
+# own release-asset naming (amd64/arm64/386/...).
+
+RUN useradd -m -s /bin/bash -d /home/tunnel tunnel \
+    && passwd -l tunnel
+
+COPY --from=shared egress-allowlist.sh /usr/local/lib/agent/egress-allowlist.sh
+COPY sshd_config.agent-gateway /etc/ssh/sshd_config.d/agent-gateway.conf
+COPY entrypoint.sh /usr/local/bin/entrypoint.sh
+RUN chmod +x /usr/local/bin/entrypoint.sh
+
+# Strip setuid/setgid bits from the base image and packages above (mount,
+# umount, passwd, chfn, gpasswd, newgrp, ...) — none of them are this image's
+# own privilege mechanism. sshd runs as real root throughout (not via a
+# setuid binary) and dnsmasq drops root->its own user via the CAP_SETUID/
+# CAP_SETGID this container is granted directly, not through any setuid-bit
+# binary, so both keep working unaffected. The build's own `passwd -l
+# tunnel` step above already ran as root before this point, so it isn't
+# affected either.
+RUN find / -xdev -perm /6000 -type f -exec chmod a-s {} + || true
+
+EXPOSE 2222
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

agent_containers/_assets/agent-images/agent-gateway/entrypoint.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+set -euo pipefail
+
+AUTHORIZED_KEYS_DIR=/run/agent-gateway
+mkdir -p "$AUTHORIZED_KEYS_DIR"
+chmod 755 "$AUTHORIZED_KEYS_DIR"
+# This is a public key, so root ownership and mode 0644 are safe. Keeping it
+# under /run makes the authorization state ephemeral while preserving a
+# read-only image root filesystem.
+install -m 644 /etc/agent/gateway-key.pub "$AUTHORIZED_KEYS_DIR/authorized_keys"
+
+HOST_KEY_DIR=/etc/ssh/keys
+mkdir -p "$HOST_KEY_DIR"
+if [ ! -f "$HOST_KEY_DIR/ssh_host_ed25519_key" ]; then
+    echo "[entrypoint] Generating gateway SSH host key ..." >&2
+    ssh-keygen -q -t ed25519 -f "$HOST_KEY_DIR/ssh_host_ed25519_key" -N ""
+fi
+
+source /usr/local/lib/agent/egress-allowlist.sh
+configure_egress_allowlist
+
+if [ -n "${CLOUDFLARE_TUNNEL_TOKEN:-}" ]; then
+    echo "[entrypoint] Starting cloudflared tunnel (no inbound port needed)." >&2
+    cloudflared tunnel run --token "$CLOUDFLARE_TUNNEL_TOKEN" &
+fi
+
+mkdir -p /run/sshd
+exec /usr/sbin/sshd -D -e

agent_containers/_assets/agent-images/agent-gateway/sshd_config.agent-gateway

@@ -0,0 +1,11 @@
+Port 2222
+HostKey /etc/ssh/keys/ssh_host_ed25519_key
+PermitRootLogin no
+PasswordAuthentication no
+KbdInteractiveAuthentication no
+AllowUsers tunnel
+AuthorizedKeysFile /run/agent-gateway/authorized_keys
+AllowTcpForwarding yes
+X11Forwarding no
+AllowAgentForwarding no
+PrintMotd no

agent_containers/_assets/agent-images/aider/Dockerfile

@@ -0,0 +1,114 @@
+FROM python:3.12-slim-trixie AS base
+
+ARG TARGETARCH
+
+# Reuse the hardened workload baseline: egress enforcement, gateway-client
+# support, and the non-root handoff. Node.js and uv remain available for
+# project tooling and optional user-selected packages.
+COPY --from=shared install-workload-base.sh /usr/local/lib/agent/install-workload-base.sh
+RUN TARGETARCH="$TARGETARCH" bash /usr/local/lib/agent/install-workload-base.sh
+
+COPY --from=shared install-additional-packages.sh /usr/local/lib/agent/install-additional-packages.sh
+COPY packages-apt.txt /tmp/packages-apt.txt
+RUN bash -c '. /usr/local/lib/agent/install-additional-packages.sh \
+        && install_apt_packages /tmp/packages-apt.txt' \
+    && rm -f /tmp/packages-apt.txt
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
+
+# packages-uv.txt — general Python libraries (not CLI tools; see
+# tools-uv.txt below), installed via `uv pip install --system` into this
+# system Python. Runs as root, before the aider user exists, since it
+# writes into the image's system site-packages rather than $HOME.
+COPY packages-uv.txt /tmp/packages-uv.txt
+RUN bash -c '. /usr/local/lib/agent/install-additional-packages.sh \
+        && install_uv_packages /tmp/packages-uv.txt' \
+    && rm -f /tmp/packages-uv.txt
+
+# Aider 0.86.2 supports Python 3.10-3.12. Pin the CLI so a rebuild does not
+# silently change the agent or its LLM-provider dependency graph. The default
+# package deliberately excludes browser/Playwright extras: installing browser
+# binaries at runtime is incompatible with the read-only-rootfs profile.
+RUN python -m pip install --no-cache-dir 'aider-chat==0.86.2'
+
+# The aider account is created here, at a fixed placeholder UID/GID
+# (1000:1000), purely so the root-only installers below (npm, uv tool) have
+# a real non-root account to run as. `final` remaps this account to the
+# operator's actual host UID/GID instead of recreating it, so a rebuild for
+# a different host user reuses everything installed below unchanged rather
+# than reinstalling it over the network.
+RUN groupadd -g 1000 aider \
+    && useradd -m -u 1000 -g 1000 -s /bin/bash aider \
+    && mkdir -p /workspace \
+    && chown -R aider:aider /home/aider /workspace
+
+ENV HOME=/home/aider
+ENV npm_config_prefix=/home/aider/.npm-global
+ENV PATH="/home/aider/.local/bin:/home/aider/.npm-global/bin:${PATH}"
+
+# $HOME (uv's default cache location) and /workspace are deliberately
+# separate mounts in this containment model, so uv's hardlink/reflink
+# optimisation can never apply between them — declare the copy fallback
+# explicit rather than have uv warn about it on every install.
+ENV UV_LINK_MODE=copy
+
+# Aider would otherwise check for updates at startup and may offer to install
+# Playwright dynamically. Both expand egress/write requirements without being
+# necessary for the core terminal workflow. Analytics is disabled explicitly,
+# rather than relying on Aider's prompt-driven opt-in behavior.
+ENV AIDER_CHECK_UPDATE=false
+ENV AIDER_ANALYTICS=false
+ENV AIDER_DISABLE_PLAYWRIGHT=true
+
+COPY packages-npm.txt /tmp/packages-npm.txt
+COPY tools-uv.txt /tmp/tools-uv.txt
+RUN gosu aider bash -c '. /usr/local/lib/agent/install-additional-packages.sh \
+        && install_npm_packages /tmp/packages-npm.txt \
+        && install_uv_tools /tmp/tools-uv.txt' \
+    && rm -f /tmp/packages-npm.txt /tmp/tools-uv.txt
+
+# Everything above this line is UID/GID-independent and layer-cacheable
+# across hosts: the aider account exists at the fixed placeholder UID/GID
+# only so the installers above have a non-root account to run as. From here
+# down, `final` remaps that account to the operator's actual host UID/GID
+# with --build-arg UID=$(id -u) --build-arg GID=$(id -g) — the base stage
+# above is reused unchanged from cache, and nothing installed above is
+# reinstalled, rather than rebuilding per host user.
+FROM base AS final
+ARG UID=1000
+ARG GID=1000
+
+# Only remap when the caller supplied a different UID/GID than the fixed
+# placeholder baked into `base` above — usermod/groupmod plus a chown -R
+# walk over already-installed content is far cheaper than rerunning the
+# npm/uv-tool installs above, but it's skippable entirely for the common
+# case where the caller never overrides UID/GID. Deliberately no -o:
+# without it, usermod/groupmod refuse to reuse an ID already assigned to
+# another account, so a caller can never remap aider onto UID/GID 0 (root)
+# or collide it with another in-image identity — the build fails instead of
+# silently succeeding.
+RUN if [ "$UID" != "1000" ] || [ "$GID" != "1000" ]; then \
+        groupmod -g "$GID" aider \
+        && usermod -u "$UID" -g "$GID" aider \
+        && chown -R "$UID":"$GID" /home/aider /workspace; \
+    fi
+
+COPY --from=shared egress-allowlist.sh /usr/local/lib/agent/egress-allowlist.sh
+COPY --from=shared workload-entrypoint.sh /usr/local/lib/agent/workload-entrypoint.sh
+RUN chmod +x /usr/local/lib/agent/workload-entrypoint.sh
+
+# Strip setuid/setgid bits from the base image and every package installed
+# above — required infra (install-workload-base.sh), packages-apt.txt,
+# packages-npm.txt, packages-uv.txt, and tools-uv.txt — run last so nothing
+# installed by any of those is missed. NoNewPrivs=1 (set by every documented
+# run invocation) already makes these bits inert on execve, but that's an
+# argument for stripping them, not against: if any single control ever
+# regresses, a setuid-root `mount` becomes a live escalation primitive. None
+# of these binaries are needed at runtime, so none should ship
+# exploitable-shaped.
+RUN find / -xdev -perm /6000 -type f -exec chmod a-s {} + || true
+
+WORKDIR /workspace
+
+ENTRYPOINT ["/usr/local/lib/agent/workload-entrypoint.sh", "aider", "aider"]
+CMD ["aider"]

agent_containers/_assets/agent-images/aider/examples/egress-allowlist.txt

@@ -0,0 +1,16 @@
+# Hosts/IPs the container is allowed to reach outbound, one per line.
+# Blank lines and lines starting with '#' are ignored.
+#
+# Accepted forms of each entry:
+#   example.com              Hostname (resolved via dnsmasq, both A/AAAA)
+#   203.0.113.10             IPv4 address or CIDR (e.g. 203.0.113.0/24)
+#   2001:db8::1              IPv6 address or CIDR
+#
+# Mount this file to /etc/agent/egress-allowlist.txt in the container.
+# A file mount here takes precedence over $AGENT_ALLOWED_EGRESS.
+# If neither is set, all outbound traffic is denied by default.
+#
+# This is only an example. Retain just the API provider(s) you selected and
+# add a source-control, package-registry, or MCP host only when you need it.
+api.anthropic.com
+api.openai.com

agent_containers/_assets/agent-images/aider/packages-apt.txt

@@ -0,0 +1,16 @@
+# Default/optional apt packages installed at build time, one per line.
+# Blank lines and lines starting with '#' are ignored. Edit freely and
+# rebuild the image — this is separate from the Dockerfile's own
+# required-infra apt list (git, iptables, gosu, etc.), which this file
+# cannot remove packages from.
+gh
+jq
+ripgrep
+fd-find
+tree
+unzip
+less
+file
+lsof
+yq
+miller

agent_containers/_assets/agent-images/aider/packages-npm.txt

@@ -0,0 +1,7 @@
+# Optional global npm packages installed at build time (via `npm install -g`),
+# one per line. Blank lines and lines starting with '#' are ignored. Empty by
+# default — there's no "everyone wants this" global npm CLI the way there is
+# for apt utilities.
+#
+# Example:
+# @some-scope/some-cli

agent_containers/_assets/agent-images/aider/packages-uv.txt

@@ -0,0 +1,9 @@
+# Optional Python libraries installed into the system Python at build time
+# (via `uv pip install --system`), one per line. Blank lines and lines
+# starting with '#' are ignored. Empty by default. Unlike tools-uv.txt, these
+# land in the one shared system Python rather than an isolated venv, so
+# they're importable by whatever runs inside the image — a CLI-only package
+# with no importable module of its own belongs in tools-uv.txt instead.
+#
+# Example:
+# langfuse

agent_containers/_assets/agent-images/aider/tools-uv.txt

@@ -0,0 +1,9 @@
+# Optional Python CLI tools installed at build time (via `uv tool install`),
+# one per line, each into its own isolated venv. Blank lines and lines
+# starting with '#' are ignored. Empty by default — there's no "everyone
+# wants this" uv-installed CLI the way there is for apt utilities. A plain
+# importable library (no console-script entry point of its own) belongs in
+# packages-uv.txt instead.
+#
+# Example:
+# ruff

agent_containers/_assets/agent-images/claude-code/Dockerfile

@@ -0,0 +1,171 @@
+FROM python:3.14-slim-trixie AS base
+
+ARG TARGETARCH
+
+# Shared Node.js, containment, gateway-client, and cloudflared baseline for
+# the first-party Python-and-Node workload images.
+COPY --from=shared install-workload-base.sh /usr/local/lib/agent/install-workload-base.sh
+RUN TARGETARCH="$TARGETARCH" bash /usr/local/lib/agent/install-workload-base.sh
+
+# Optional profile-managed organisational CAs. The canonical context carries
+# only a marker; onboarding replaces this directory with the selected file or
+# certificate directory before building. The merged system bundle is then
+# available to curl/git/OpenSSL clients on the read-only runtime rootfs.
+COPY proxy-ca.d/ /tmp/agent-containers-proxy-ca/
+RUN set -eu; \
+    mkdir -p /usr/local/share/ca-certificates/custom; \
+    found=0; \
+    for cert in /tmp/agent-containers-proxy-ca/*; do \
+        [ -f "$cert" ] || continue; \
+        name="$(basename "$cert")"; \
+        [ "$name" = ".keep" ] && continue; \
+        case "$name" in *.crt) ;; *) name="${name%.*}.crt" ;; esac; \
+        cp "$cert" "/usr/local/share/ca-certificates/custom/$name"; \
+        found=1; \
+    done; \
+    if [ "$found" -eq 1 ]; then update-ca-certificates; fi; \
+    rm -rf /tmp/agent-containers-proxy-ca
+
+# User-configurable default software (gh, jq, ripgrep, ...) — see
+# packages-apt.txt. Kept as a separate RUN from the baseline block above so
+# the required-infra list stays untouched by editing that file.
+COPY --from=shared install-additional-packages.sh /usr/local/lib/agent/install-additional-packages.sh
+COPY packages-apt.txt /tmp/packages-apt.txt
+RUN bash -c '. /usr/local/lib/agent/install-additional-packages.sh \
+        && install_apt_packages /tmp/packages-apt.txt' \
+    && rm -f /tmp/packages-apt.txt
+
+# uv/uvx (Python package & venv manager), copied in rather than switching
+# the base image — uv manages venvs against this image's existing system
+# Python just as well as against a uv-provisioned one, without disturbing
+# the apt/Node.js setup above.
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
+
+# packages-uv.txt — general Python libraries (not CLI tools; see
+# tools-uv.txt below), installed via `uv pip install --system` into this
+# system Python. Runs as root, before the claude user exists, since it
+# writes into the image's system site-packages rather than $HOME.
+COPY packages-uv.txt /tmp/packages-uv.txt
+RUN bash -c '. /usr/local/lib/agent/install-additional-packages.sh \
+        && install_uv_packages /tmp/packages-uv.txt' \
+    && rm -f /tmp/packages-uv.txt
+
+RUN npm install -g @anthropic-ai/claude-code
+
+# The claude account is created here, at a fixed placeholder UID/GID
+# (1000:1000), purely so the root-only installers below (npm, uv tool,
+# claude plugin) have a real non-root account to run as. `final` remaps
+# this account to the operator's actual host UID/GID instead of recreating
+# it, so a rebuild for a different host user reuses everything installed
+# below unchanged rather than reinstalling it over the network.
+RUN groupadd -g 1000 claude \
+    && useradd -m -u 1000 -g 1000 -s /bin/bash claude \
+    && mkdir -p /home/claude/.claude /workspace \
+    && chown -R claude:claude /home/claude /workspace
+
+# gosu switches UID/GID but, unlike a login shell, does not reset $HOME —
+# without this, plugin install (below) and the runtime `claude` process would
+# both try to use root's $HOME instead of /home/claude.
+ENV HOME=/home/claude
+
+# npm's default global-install prefix (/usr/local) sits on the read-only
+# rootfs at runtime; repoint it to a location under the claude user's home
+# so `npm install -g` works there instead. This doesn't affect the
+# `npm install -g @anthropic-ai/claude-code` above, which already ran as
+# root before this user/prefix existed. Set via ENV (not `npm config set`,
+# which would only write ~/.npmrc into the image — that file wouldn't reach
+# a volume that already has content the first time it's mounted here, since
+# Docker's volume copy-up only seeds genuinely empty volumes) so the prefix
+# applies regardless of what's already in the mounted $HOME volume.
+ENV npm_config_prefix=/home/claude/.npm-global
+# Home-managed installations intentionally precede profile-managed tools. The
+# latter are image-owned under /opt so a populated home volume cannot hide a
+# rebuilt profile image's requested versions.
+ENV PATH="/home/claude/.local/bin:/home/claude/.npm-global/bin:/opt/agent-tools/bin:/opt/agent-tools/npm/bin:${PATH}"
+
+# $HOME (uv's default cache location) and /workspace are deliberately
+# separate mounts in this containment model, so uv's hardlink/reflink
+# optimisation can never apply between them — declare the copy fallback
+# explicit rather than have uv warn about it on every install.
+ENV UV_LINK_MODE=copy
+
+# packages-npm.txt / tools-uv.txt — see packages-apt.txt above. Profile-managed
+# tools live outside the persistent home, so changing an image changes the
+# visible managed version even when a populated home volume is mounted.
+COPY packages-npm.txt /tmp/packages-npm.txt
+COPY tools-uv.txt /tmp/tools-uv.txt
+RUN mkdir -p /opt/agent-tools/npm /opt/agent-tools/uv-tools /opt/agent-tools/bin \
+    && chown -R claude:claude /opt/agent-tools \
+    && gosu claude env \
+        npm_config_prefix=/opt/agent-tools/npm \
+        UV_TOOL_DIR=/opt/agent-tools/uv-tools \
+        UV_TOOL_BIN_DIR=/opt/agent-tools/bin \
+        bash -c '. /usr/local/lib/agent/install-additional-packages.sh \
+        && install_npm_packages /tmp/packages-npm.txt \
+        && install_uv_tools /tmp/tools-uv.txt' \
+    && rm -f /tmp/packages-npm.txt /tmp/tools-uv.txt
+
+COPY plugin-marketplaces.txt /tmp/plugin-marketplaces.txt
+COPY plugins.txt /tmp/plugins.txt
+
+# The official marketplace is always available; plugin-marketplaces.txt lists
+# any additional (non-official) marketplaces to add before installing plugins,
+# since plugins.txt entries may reference any of them via "<plugin>@<marketplace>".
+RUN gosu claude claude plugin marketplace add anthropics/claude-plugins-official \
+    && while IFS= read -r marketplace; do \
+        case "$marketplace" in ''|'#'*) continue ;; esac; \
+        gosu claude claude plugin marketplace add "${marketplace}"; \
+    done < /tmp/plugin-marketplaces.txt \
+    && while IFS= read -r plugin; do \
+        case "$plugin" in ''|'#'*) continue ;; esac; \
+        gosu claude claude plugin install "${plugin}" --scope user; \
+    done < /tmp/plugins.txt \
+    && rm /tmp/plugin-marketplaces.txt /tmp/plugins.txt
+
+# Everything above this line is UID/GID-independent and layer-cacheable
+# across hosts: the claude account exists at the fixed placeholder UID/GID
+# only so the installers above have a non-root account to run as. From here
+# down, `final` remaps that account to the operator's actual host UID/GID
+# with --build-arg UID=$(id -u) --build-arg GID=$(id -g) — the base stage
+# above is reused unchanged from cache, and nothing installed above is
+# reinstalled, rather than rebuilding per host user.
+FROM base AS final
+ARG UID=1000
+ARG GID=1000
+
+# Only remap when the caller supplied a different UID/GID than the fixed
+# placeholder baked into `base` above — usermod/groupmod plus a chown -R
+# walk over already-installed content is far cheaper than rerunning the
+# npm/uv-tool/plugin installs above, but it's skippable entirely for the
+# common case where the caller never overrides UID/GID. Deliberately no -o:
+# without it, usermod/groupmod refuse to reuse an ID already assigned to
+# another account, so a caller can never remap claude onto UID/GID 0 (root)
+# or collide it with another in-image identity — the build fails instead of
+# silently succeeding.
+RUN if [ "$UID" != "1000" ] || [ "$GID" != "1000" ]; then \
+        groupmod -g "$GID" claude \
+        && usermod -u "$UID" -g "$GID" claude \
+        && chown -R "$UID":"$GID" /home/claude /workspace /opt/agent-tools; \
+    fi
+
+COPY --from=shared egress-allowlist.sh /usr/local/lib/agent/egress-allowlist.sh
+COPY --from=shared workload-entrypoint.sh /usr/local/lib/agent/workload-entrypoint.sh
+
+COPY entrypoint.sh /usr/local/bin/entrypoint.sh
+RUN chmod +x /usr/local/bin/entrypoint.sh /usr/local/lib/agent/workload-entrypoint.sh
+
+# Strip setuid/setgid bits from the base image and every package installed
+# above — required infra (install-workload-base.sh), packages-apt.txt,
+# packages-npm.txt, packages-uv.txt, tools-uv.txt, and installed plugins —
+# run last so nothing installed by any of those is missed. NoNewPrivs=1 (set
+# by every documented run invocation) already makes these bits inert on
+# execve, but that's an argument for stripping them, not against: if any
+# single control ever regresses, a setuid-root `mount` becomes a live
+# escalation primitive. None of these binaries are needed at runtime, so
+# none should ship exploitable-shaped.
+RUN find / -xdev -perm /6000 -type f -exec chmod a-s {} + || true
+
+WORKDIR /workspace
+
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
+CMD ["claude"]

agent_containers/_assets/agent-images/claude-code/entrypoint.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+set -euo pipefail
+
+# Older images mounted the persistent volume directly at /home/claude/.claude;
+# it's now mounted at /home/claude so uv/npm state under $HOME persists too.
+# A volume from before this change has its old .claude contents sitting at
+# its own root, so /home/claude/.claude won't exist yet — nest them one
+# level down to match where Claude Code still expects them. Both the check
+# and the action run as the claude user (via gosu): /home/claude is
+# 0700-owned by claude, and root lacks CAP_DAC_OVERRIDE under --cap-drop=ALL,
+# so root can't even stat into it — checking as root would misreport
+# "missing" on every single start (not just genuinely legacy volumes) and
+# re-run the sweep repeatedly, corrupting a volume that's already migrated.
+if ! gosu claude test -d /home/claude/.claude; then
+    echo "[entrypoint] Migrating legacy claude-home volume layout into ~/.claude ..." >&2
+    gosu claude mkdir -p /home/claude/.claude
+    gosu claude find /home/claude -mindepth 1 -maxdepth 1 ! -name .claude -exec mv -t /home/claude/.claude -- {} +
+fi
+
+# Claude-specific state migration stays here; all containment setup and the
+# privilege drop are shared with the other first-party Node.js workload images.
+exec /usr/local/lib/agent/workload-entrypoint.sh claude claude "$@"

agent_containers/_assets/agent-images/claude-code/examples/egress-allowlist.txt

@@ -0,0 +1,14 @@
+# Hosts/IPs the container is allowed to reach outbound, one per line.
+# Blank lines and lines starting with '#' are ignored.
+#
+# Accepted forms of each entry:
+#   example.com              Hostname (resolved via dnsmasq, both A/AAAA)
+#   203.0.113.10              IPv4 address or CIDR (e.g. 203.0.113.0/24)
+#   2001:db8::1               IPv6 address or CIDR
+#
+# Mount this file to /etc/agent/egress-allowlist.txt in the container.
+# A file mount here takes precedence over $AGENT_ALLOWED_EGRESS.
+# If neither is set, all outbound traffic is denied by default.
+#
+# Example:
+api.anthropic.com

agent_containers/_assets/agent-images/claude-code/examples/settings.local-model.json

@@ -0,0 +1,7 @@
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "https://your-local-model.example.com",
+    "ANTHROPIC_AUTH_TOKEN": "replace-with-your-token",
+    "ANTHROPIC_MODEL": "your-local-model-name"
+  }
+}