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

agent_containers/_assets/agent-images/shared/workload-entrypoint.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+# Shared runtime entrypoint for first-party workloads that use Python and
+# Node.js. The Dockerfile supplies the fixed default executable and
+# unprivileged user as the first two positional arguments, rather than mutable
+# environment variables, so a runtime -e option cannot alter the privilege
+# drop target.
+
+set -euo pipefail
+
+agent_command="$1"
+agent_user="$2"
+shift 2
+
+if [ -n "${AGENT_LANGFUSE_PUBLIC_KEY_ENV:-}" ]; then
+    langfuse_public_name="$AGENT_LANGFUSE_PUBLIC_KEY_ENV"
+    if [ -n "${!langfuse_public_name+x}" ]; then
+        export LANGFUSE_PUBLIC_KEY="${!langfuse_public_name}"
+    fi
+fi
+if [ -n "${AGENT_LANGFUSE_SECRET_KEY_ENV:-}" ]; then
+    langfuse_secret_name="$AGENT_LANGFUSE_SECRET_KEY_ENV"
+    if [ -n "${!langfuse_secret_name+x}" ]; then
+        export LANGFUSE_SECRET_KEY="${!langfuse_secret_name}"
+    fi
+fi
+
+if [ "$agent_command" = "opencode" ] && [ -n "${AGENT_OPENCODE_CONFIG_JSON:-}" ]; then
+    printf '%s\n' "$AGENT_OPENCODE_CONFIG_JSON" > /tmp/agent-containers-opencode.json
+    chmod 0644 /tmp/agent-containers-opencode.json
+    export OPENCODE_CONFIG=/tmp/agent-containers-opencode.json
+fi
+
+if [ -n "${AGENT_GATEWAY_HOST:-}" ]; then
+    echo "[entrypoint] AGENT_GATEWAY_HOST=$AGENT_GATEWAY_HOST — tunneling all egress through the gateway." >&2
+    if [ -n "${AGENT_ALLOWED_EGRESS:-}" ] || [ -f /etc/agent/egress-allowlist.txt ]; then
+        echo "[entrypoint] AGENT_ALLOWED_EGRESS/egress-allowlist.txt are ignored in gateway mode — set the allowlist on the gateway container instead." >&2
+    fi
+    if [ -n "${AGENT_GATEWAY_BOOTSTRAP_ALLOW:-}" ]; then
+        echo "[entrypoint] Seeding a bootstrap allow rule for ${AGENT_GATEWAY_BOOTSTRAP_ALLOW} until the tunnel is up." >&2
+        # -m addrtype --dst-type LOCAL, not -o lo: sshuttle's own REDIRECT
+        # rules retarget outbound connections to 127.0.0.1:<its local proxy
+        # port> before this chain runs, but that retargeted packet's
+        # out-interface isn't reliably "lo" by the time OUTPUT filtering
+        # sees it. Matching the resolved destination instead reliably covers
+        # both loopback and this redirect-to-local-port case.
+        iptables -P OUTPUT DROP
+        iptables -A OUTPUT -m addrtype --dst-type LOCAL -j ACCEPT
+        iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+        ip6tables -P OUTPUT DROP
+        ip6tables -A OUTPUT -m addrtype --dst-type LOCAL -j ACCEPT
+        ip6tables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+        IFS=',' read -ra BOOTSTRAP_ALLOW <<< "$AGENT_GATEWAY_BOOTSTRAP_ALLOW"
+        for addr in "${BOOTSTRAP_ALLOW[@]}"; do
+            if [[ "$addr" == *:* ]]; then
+                ip6tables -A OUTPUT -d "$addr" -j ACCEPT
+            else
+                iptables -A OUTPUT -d "$addr" -j ACCEPT
+            fi
+        done
+    fi
+    install -m 600 /etc/agent/gateway-key /tmp/gateway-key
+    SSH_CMD="ssh -i /tmp/gateway-key -o StrictHostKeyChecking=yes -o UserKnownHostsFile=/etc/agent/gateway-known-hosts"
+    if [ -n "${AGENT_GATEWAY_ACCESS_HOSTNAME:-}" ]; then
+        echo "[entrypoint] Reaching the gateway via Cloudflare Access hostname ${AGENT_GATEWAY_ACCESS_HOSTNAME}." >&2
+        SSH_CMD="$SSH_CMD -o ProxyCommand='cloudflared access ssh --hostname ${AGENT_GATEWAY_ACCESS_HOSTNAME}'"
+    fi
+    sshuttle -r "${AGENT_GATEWAY_USER:-tunnel}@${AGENT_GATEWAY_HOST}:${AGENT_GATEWAY_PORT:-2222}" \
+        0.0.0.0/0 ::/0 --dns --daemon --pidfile=/tmp/sshuttle.pid \
+        -e "$SSH_CMD"
+else
+    source /usr/local/lib/agent/egress-allowlist.sh
+    configure_egress_allowlist
+fi
+
+# `docker run <image> <args>` replaces CMD entirely rather than appending to
+# it, so a flag-only invocation must prepend the image's default executable.
+case "${1:-}" in
+    -*) set -- "$agent_command" "$@" ;;
+    "") set -- "$agent_command" ;;
+esac
+
+exec gosu "$agent_user" "$@"

agent_containers/_assets/agent-images/volume-bridge/Dockerfile

@@ -0,0 +1,37 @@
+FROM debian:trixie-slim
+
+ARG UID=1000
+ARG GID=1000
+
+# rclone's WebDAV server is a userspace server, so it can expose only its
+# configured local backend without CAP_SYS_CHROOT or a root-owned source
+# volume. apache2-utils creates the persistent bcrypt password verifier.
+# iptables installs this image's own fixed deny-by-default INPUT/OUTPUT
+# policy (see entrypoint.sh); gosu drops from root to the unprivileged bridge
+# user once that policy is in place.
+RUN apt-get update \
+    && apt-get upgrade -y \
+    && apt-get install -y --no-install-recommends \
+        apache2-utils \
+        rclone \
+        iptables \
+        gosu \
+    && rm -rf /var/lib/apt/lists/* \
+    && groupadd -g "$GID" bridge \
+    && useradd -u "$UID" -g "$GID" --no-create-home --shell /usr/sbin/nologin bridge \
+    && mkdir -p /exports /state \
+    && touch /state/.keep \
+    && chown -R bridge:bridge /state \
+    && find / -xdev -perm /6000 -type f -exec chmod a-s {} + || true
+
+COPY serve.sh /usr/local/lib/agent/volume-bridge-serve.sh
+COPY entrypoint.sh /usr/local/bin/entrypoint.sh
+RUN chmod 755 /usr/local/bin/entrypoint.sh /usr/local/lib/agent/volume-bridge-serve.sh
+
+# The image starts as root: entrypoint.sh installs the fixed deny-by-default
+# network policy (needs NET_ADMIN/NET_RAW), then gosu drops to bridge before
+# rclone ever runs. This image no longer sets USER at build time.
+ENV HOME=/tmp
+
+EXPOSE 16080
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

agent_containers/_assets/agent-images/volume-bridge/entrypoint.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+set -euo pipefail
+
+# volume-bridge only ever serves inbound WebDAV reads from a local backend —
+# it has no legitimate reason to make outbound connections, and the only
+# thing that should ever be reachable inbound is that one WebDAV port — so
+# this is a small, fixed, non-configurable deny-by-default policy rather than
+# the shared agent-images/shared/egress-allowlist.sh: that script exists to
+# support opening exceptions, and this image should never have any to open.
+readonly webdav_port="${VOLUME_BRIDGE_LISTEN_ADDR:-0.0.0.0:16080}"
+readonly webdav_tcp_port="${webdav_port##*:}"
+
+iptables -P OUTPUT DROP
+iptables -A OUTPUT -o lo -j ACCEPT
+iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+ip6tables -P OUTPUT DROP
+ip6tables -A OUTPUT -o lo -j ACCEPT
+ip6tables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+
+iptables -P INPUT DROP
+iptables -A INPUT -i lo -j ACCEPT
+iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+iptables -A INPUT -p tcp --dport "$webdav_tcp_port" -m state --state NEW -j ACCEPT
+ip6tables -P INPUT DROP
+ip6tables -A INPUT -i lo -j ACCEPT
+ip6tables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+ip6tables -A INPUT -p tcp --dport "$webdav_tcp_port" -m state --state NEW -j ACCEPT
+
+exec gosu bridge /usr/local/lib/agent/volume-bridge-serve.sh

agent_containers/_assets/agent-images/volume-bridge/serve.sh

@@ -0,0 +1,66 @@
+#!/bin/sh
+set -eu
+
+readonly state_dir=/state
+readonly htpasswd_file="$state_dir/htpasswd"
+readonly username="${VOLUME_BRIDGE_USERNAME:-bridge}"
+
+if [ ! -w "$state_dir" ]; then
+    echo '[volume-bridge] /state must be an empty volume first mounted by this image, or be writable by the bridge UID/GID.' >&2
+    exit 1
+fi
+
+if [ -n "${VOLUME_BRIDGE_PASSWORD:-}" ] && [ -n "${VOLUME_BRIDGE_PASSWORD_FILE:-}" ]; then
+    echo '[volume-bridge] Set only one of VOLUME_BRIDGE_PASSWORD or VOLUME_BRIDGE_PASSWORD_FILE.' >&2
+    exit 1
+fi
+
+password=""
+if [ -n "${VOLUME_BRIDGE_PASSWORD_FILE:-}" ]; then
+    password="$(cat "$VOLUME_BRIDGE_PASSWORD_FILE")"
+elif [ -n "${VOLUME_BRIDGE_PASSWORD:-}" ]; then
+    password="$VOLUME_BRIDGE_PASSWORD"
+fi
+
+# The password is accepted only to initialise or rotate a bcrypt verifier in
+# the state volume. VOLUME_BRIDGE_PASSWORD_FILE is read once, right here, and
+# never lands in the daemon-persisted container config that
+# VOLUME_BRIDGE_PASSWORD leaves behind for `docker inspect` to read for the
+# container's whole lifetime — prefer it when the password can be
+# bind-mounted as a file. Do not put a reader private key or plaintext
+# credential in the image or state volume. A Docker administrator can already
+# read the source volumes directly, so they are the trusted provisioning
+# boundary for this input either way.
+if [ -n "$password" ]; then
+    case "$username" in
+        *:* | *'
+'*)
+            echo '[volume-bridge] VOLUME_BRIDGE_USERNAME must not contain a colon or newline.' >&2
+            exit 1
+            ;;
+    esac
+    umask 077
+    printf '%s\n' "$password" \
+        | htpasswd -B -C 12 -c -i "$htpasswd_file.new" "$username"
+    mv "$htpasswd_file.new" "$htpasswd_file"
+fi
+unset password
+
+if [ ! -s "$htpasswd_file" ]; then
+    echo '[volume-bridge] VOLUME_BRIDGE_PASSWORD or VOLUME_BRIDGE_PASSWORD_FILE is required on first start.' >&2
+    exit 1
+fi
+chmod 600 "$htpasswd_file"
+
+# The source is the deliberately narrow /exports tree. rclone's WebDAV server
+# authenticates against the bcrypt verifier and exposes this backend as its
+# virtual root. The service listens on all container interfaces because Docker's
+# host-loopback port publishing forwards to the container address, not its
+# loopback address.
+exec rclone --config /dev/null --cache-dir /tmp/rclone-cache serve webdav \
+    --addr "${VOLUME_BRIDGE_LISTEN_ADDR:-0.0.0.0:16080}" \
+    --htpasswd "$htpasswd_file" \
+    --realm volume-bridge \
+    --read-only \
+    --dir-cache-time "${VOLUME_BRIDGE_DIR_CACHE_TIME:-1s}" \
+    :local:/exports

agent_containers/assets.py

@@ -0,0 +1,38 @@
+"""Access bundled canonical image build contexts."""
+
+from __future__ import annotations
+
+import shutil
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+from pathlib import Path
+
+
+def bundled_image_root() -> Traversable:
+    """Return the packaged image-context directory."""
+    return files("agent_containers").joinpath("_assets", "agent-images")
+
+
+def available_image_contexts() -> tuple[str, ...]:
+    """List bundled image directories in stable order."""
+    return tuple(sorted(item.name for item in bundled_image_root().iterdir() if item.is_dir()))
+
+
+def materialize_image_context(name: str, destination: Path) -> Path:
+    """Copy one bundled context to a filesystem directory for Docker."""
+    if name not in available_image_contexts():
+        raise ValueError(f"image context is not bundled: {name}")
+    _copy_tree(bundled_image_root().joinpath(name), destination)
+    return destination
+
+
+def _copy_tree(source: Traversable, destination: Path) -> None:
+    """Copy a Traversable tree without relying on filesystem-only metadata."""
+    destination.mkdir(parents=True, exist_ok=True)
+    for item in source.iterdir():
+        target = destination / item.name
+        if item.is_dir():
+            _copy_tree(item, target)
+        else:
+            with item.open("rb") as source_file, target.open("wb") as target_file:
+                shutil.copyfileobj(source_file, target_file)

agent_containers/build_context.py

@@ -0,0 +1,116 @@
+"""Prepare authoritative, profile-specific Docker build contexts."""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from agent_containers.assets import materialize_image_context
+from agent_containers.profile import Profile
+
+_PACKAGE_FILES = {
+    "apt": "packages-apt.txt",
+    "npm": "packages-npm.txt",
+    "uv_tools": "tools-uv.txt",
+    "uv_libraries": "packages-uv.txt",
+}
+_LANGFUSE_OPENCODE_PLUGIN = "@langfuse/opencode-observability-plugin"
+
+
+@dataclass(frozen=True)
+class BuildContexts:
+    """Filesystem paths passed to one isolated Docker build."""
+
+    image: Path
+    shared: Path
+
+
+def prepare_build_contexts(profile: Profile, destination: Path, profile_path: Path | None = None) -> BuildContexts:
+    """Materialize recipes and replace optional package lists from a profile.
+
+    ``destination`` must not exist. This prevents an apply operation from
+    silently merging generated files into user-maintained build contexts.
+    """
+    destination = destination.expanduser().resolve()
+    if destination.exists():
+        raise ValueError(f"build-context destination already exists: {destination}")
+    image = materialize_image_context(profile.agent.value, destination / "image")
+    shared = materialize_image_context("shared", destination / "shared")
+    for field, filename in _PACKAGE_FILES.items():
+        packages = _packages_for_profile(profile, field)
+        (image / filename).write_text(_package_file_content(packages), encoding="utf-8")
+    _materialize_agent_plugins(profile, image)
+    _materialize_proxy_cas(profile, image / "proxy-ca.d", profile_path)
+    return BuildContexts(image=image, shared=shared)
+
+
+def _packages_for_profile(profile: Profile, field: str) -> list[str]:
+    """Add only the package required by an explicitly enabled integration."""
+    packages = list(getattr(profile.packages, field))
+    required: str | None = None
+    if profile.langfuse.enabled and profile.agent.value == "opencode" and field == "npm":
+        required = _LANGFUSE_OPENCODE_PLUGIN
+    if required is not None and required not in packages:
+        packages.append(required)
+    return packages
+
+
+def _materialize_agent_plugins(profile: Profile, image: Path) -> None:
+    """Materialize marketplace/plugin selections for profile-enabled adapters."""
+    if profile.agent.value == "claude-code" and profile.langfuse.enabled:
+        _append_line(image / "plugin-marketplaces.txt", "langfuse/Claude-Observability-Plugin")
+        _append_line(image / "plugins.txt", "langfuse-observability@langfuse-observability")
+    if profile.agent.value == "codex" and profile.langfuse.enabled:
+        _append_line(image / "plugin-marketplaces.txt", "langfuse/codex-observability-plugin")
+        _append_line(image / "plugins.txt", "tracing@codex-observability-plugin")
+
+
+def _append_line(path: Path, value: str) -> None:
+    """Append an integration entry once while preserving canonical comments."""
+    existing = path.read_text(encoding="utf-8") if path.exists() else ""
+    if value not in existing.splitlines():
+        path.write_text(existing.rstrip() + ("\n" if existing.strip() else "") + value + "\n", encoding="utf-8")
+
+
+def _package_file_content(packages: list[str]) -> str:
+    """Render one package per line, preserving empty-list semantics."""
+    return "" if not packages else "\n".join(packages) + "\n"
+
+
+def _materialize_proxy_cas(profile: Profile, destination: Path, profile_path: Path | None) -> None:
+    """Copy profile CA inputs into the isolated image context for system trust."""
+    destination.mkdir(parents=True, exist_ok=True)
+    for item in destination.iterdir():
+        if item.name != ".keep":
+            if item.is_dir():
+                shutil.rmtree(item)
+            else:
+                item.unlink()
+    if profile.proxy is None or (profile.proxy.ca_file is None and profile.proxy.ca_dir is None):
+        return
+    if profile_path is None:
+        raise ValueError("profile_path is required when a proxy CA input is configured")
+    base = profile_path.expanduser().resolve().parent
+    if profile.proxy.ca_file is not None:
+        source = (base / profile.proxy.ca_file).resolve()
+        if not source.is_file():
+            raise ValueError(f"proxy CA file does not exist: {source}")
+        _copy_certificate(source, destination / "profile-ca.pem")
+    if profile.proxy.ca_dir is not None:
+        source = (base / profile.proxy.ca_dir).resolve()
+        if not source.is_dir():
+            raise ValueError(f"proxy CA directory does not exist: {source}")
+        files = sorted(item for item in source.iterdir() if item.is_file())
+        if not files:
+            raise ValueError(f"proxy CA directory is empty: {source}")
+        for index, item in enumerate(files):
+            _copy_certificate(item, destination / f"profile-ca-{index}-{item.name}")
+
+
+def _copy_certificate(source: Path, destination: Path) -> None:
+    """Copy one non-secret certificate input while rejecting private keys."""
+    contents = source.read_bytes()
+    if b"PRIVATE KEY" in contents:
+        raise ValueError(f"proxy CA input must not contain a private key: {source}")
+    destination.write_bytes(contents)

agent_containers/cli.py

@@ -0,0 +1,212 @@
+"""CLI entry point. Runtime operations are added as verified components mature."""
+
+import subprocess
+import sys
+import tomllib
+from importlib.metadata import version
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from pydantic import ValidationError
+from typer.core import TyperGroup
+
+from agent_containers.creation import ProfileCreationError, prompt_profile, write_profile
+from agent_containers.docker import DockerCommandError
+from agent_containers.lifecycle import (
+    DoctorReport,
+    LifecycleError,
+    apply_profile,
+    doctor_profile,
+    rollback_preview,
+    rollback_profile,
+)
+from agent_containers.planner import build_plan
+from agent_containers.profile import load_profile
+from agent_containers.shortcuts import ShortcutError, default_shortcuts_path
+from agent_containers.state import load_state
+
+_LOGO = """░█▀█░█▀▀░█▀▀░█▀█░▀█▀░░░█▀▀░█▀█░█▀█░▀█▀░█▀█░▀█▀░█▀█░█▀▀░█▀▄░█▀▀
+░█▀█░█░█░█▀▀░█░█░░█░░░░█░░░█░█░█░█░░█░░█▀█░░█░░█░█░█▀▀░█▀▄░▀▀█
+░▀░▀░▀▀▀░▀▀▀░▀░▀░░▀░░░░▀▀▀░▀▀▀░▀░▀░░▀░░▀░▀░▀▀▀░▀░▀░▀▀▀░▀░▀░▀▀▀"""
+
+
+class LogoGroup(TyperGroup):
+    """Render the required banner before Click dispatches any CLI invocation."""
+
+    def parse_args(self, ctx: Any, args: list[str]) -> list[str]:
+        """Print once for normal commands, help, version and parser errors."""
+        typer.echo(_LOGO)
+        return super().parse_args(ctx, args)
+
+
+app = typer.Typer(
+    help=(
+        "Onboarding and maintenance for hardened agent containers. "
+        "Profiles can be validated, planned, and applied with direct Docker commands."
+    ),
+    add_completion=False,
+    pretty_exceptions_enable=False,
+    cls=LogoGroup,
+)
+
+
+def show_version(value: bool) -> None:
+    """Read installed distribution metadata, avoiding a second version constant."""
+    if value:
+        typer.echo(f"agent-containers {version('agent-containers')}")
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version_flag: Annotated[
+        bool,
+        typer.Option("--version", callback=show_version, is_eager=True, help="Show version and exit."),
+    ] = False,
+) -> None:
+    """Display help without probing Docker or changing user configuration."""
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+
+
+@app.command()
+def validate(
+    profile: Annotated[
+        Path,
+        typer.Argument(exists=True, dir_okay=False, readable=True, help="TOML profile to validate."),
+    ],
+) -> None:
+    """Validate a TOML profile without contacting Docker or changing state."""
+    try:
+        document = load_profile(profile)
+    except (OSError, tomllib.TOMLDecodeError, ValidationError) as exc:
+        raise typer.BadParameter(str(exc), param_hint="profile") from exc
+    typer.echo(f"Valid profile: {document.name} ({document.agent.value})")
+
+
+@app.command()
+def create(
+    profile: Annotated[
+        Path,
+        typer.Argument(dir_okay=False, help="New TOML profile path to create interactively."),
+    ],
+) -> None:
+    """Interactively create a validated TOML profile without contacting Docker."""
+    try:
+        document = prompt_profile(profile)
+        write_profile(profile, document)
+    except (OSError, ProfileCreationError, ValidationError, ValueError) as exc:
+        raise typer.BadParameter(str(exc), param_hint="profile") from exc
+    typer.echo(f"Created profile: {profile.expanduser().resolve()} ({document.name}/{document.agent.value})")
+
+
+@app.command()
+def plan(
+    profile: Annotated[
+        Path,
+        typer.Argument(exists=True, dir_okay=False, readable=True, help="TOML profile to plan."),
+    ],
+    state: Annotated[
+        Path | None,
+        typer.Option("--state", exists=True, dir_okay=False, readable=True, help="Recorded deployment JSON."),
+    ] = None,
+) -> None:
+    """Show an offline plan without contacting Docker or changing state."""
+    try:
+        document = load_profile(profile)
+        recorded = load_state(state) if state is not None else None
+    except (OSError, tomllib.TOMLDecodeError, ValidationError, ValueError) as exc:
+        raise typer.BadParameter(str(exc), param_hint="profile/state") from exc
+    for line in build_plan(document, recorded, profile).summary_lines():
+        typer.echo(line)
+
+
+@app.command()
+def apply(
+    profile: Annotated[
+        Path,
+        typer.Argument(exists=True, dir_okay=False, readable=True, help="TOML profile to build and select."),
+    ],
+    state: Annotated[
+        Path | None,
+        typer.Option("--state", dir_okay=False, help="Override the XDG deployment-state JSON path."),
+    ] = None,
+) -> None:
+    """Build, safely seed, and select a profile deployment without launching it."""
+    try:
+        document = load_profile(profile)
+        if sys.platform == "darwin":
+            typer.echo(
+                "Note: macOS Docker Desktop builds retain the host UID and use image GID 1000 to avoid collisions."
+            )
+        record = apply_profile(document, profile, state, default_shortcuts_path())
+    except (
+        DockerCommandError,
+        LifecycleError,
+        ShortcutError,
+        OSError,
+        subprocess.CalledProcessError,
+        tomllib.TOMLDecodeError,
+        ValidationError,
+        ValueError,
+    ) as exc:
+        raise typer.BadParameter(str(exc), param_hint="profile/state") from exc
+    typer.echo(f"Selected deployment: {record.deployment_id} ({record.image})")
+
+
+@app.command()
+def rollback(
+    profile: Annotated[
+        Path,
+        typer.Argument(
+            exists=True, dir_okay=False, readable=True, help="TOML profile whose selected deployment is restored."
+        ),
+    ],
+    state: Annotated[
+        Path | None,
+        typer.Option(
+            "--state", exists=True, dir_okay=False, readable=True, help="Override the XDG deployment-state JSON path."
+        ),
+    ] = None,
+) -> None:
+    """Restore the immediately previous retained image and managed launch record."""
+    try:
+        document = load_profile(profile)
+        record = rollback_profile(document, state, default_shortcuts_path(), profile)
+    except (
+        LifecycleError,
+        ShortcutError,
+        OSError,
+        subprocess.CalledProcessError,
+        tomllib.TOMLDecodeError,
+        ValidationError,
+        ValueError,
+    ) as exc:
+        raise typer.BadParameter(str(exc), param_hint="profile/state") from exc
+    for line in rollback_preview(record):
+        typer.echo(line)
+
+
+@app.command()
+def doctor(
+    profile: Annotated[
+        Path,
+        typer.Argument(exists=True, dir_okay=False, readable=True, help="TOML profile whose deployment is inspected."),
+    ],
+    state: Annotated[
+        Path | None,
+        typer.Option("--state", dir_okay=False, help="Override the XDG deployment-state JSON path."),
+    ] = None,
+) -> None:
+    """Check Docker, recorded deployment state, and the selected image without mutating them."""
+    try:
+        document = load_profile(profile)
+        report: DoctorReport = doctor_profile(document, state)
+    except (LifecycleError, OSError, tomllib.TOMLDecodeError, ValidationError, ValueError) as exc:
+        raise typer.BadParameter(str(exc), param_hint="profile/state") from exc
+    for line in report.lines:
+        typer.echo(line)
+    if not report.healthy:
+        raise typer.Exit(1)