container-superposition 0.1.6 → 0.1.8

package/overlays/alertmanager/verify.sh

@@ -6,19 +6,18 @@ echo "🔍 Verifying Alertmanager installation..."
 # Track overall success
 ALL_CHECKS_PASSED=true
 
-# Check if Alertmanager service is running
-if docker ps --format '{{.Names}}' | grep -q alertmanager; then
-    echo "✓ Alertmanager service is running"
+# Check if Alertmanager API is accessible (primary health signal).
+# docker ps is used for info only — it may not be accessible in all setups.
+if curl -s -o /dev/null -w "%{http_code}" http://alertmanager:9093/-/healthy 2>/dev/null | grep -q "200"; then
+    echo "✓ Alertmanager API is accessible"
 else
-    echo "✗ Alertmanager service is not running"
+    echo "✗ Alertmanager API not responding (http://alertmanager:9093/-/healthy)"
     ALL_CHECKS_PASSED=false
 fi
 
-# Check if Alertmanager API is accessible
-if curl -s -o /dev/null -w "%{http_code}" http://alertmanager:9093/-/healthy 2>/dev/null | grep -q "200"; then
-    echo "✓ Alertmanager API is accessible"
-else
-    echo "⚠️ Alertmanager API not responding yet (may still be starting)"
+# Informational: check via docker ps if available.
+if docker ps --format '{{.Names}}' 2>/dev/null | grep -q alertmanager; then
+    echo "✓ Alertmanager container visible in docker ps"
 fi
 
 # Final result

package/overlays/all/README.md

@@ -0,0 +1,43 @@
+# Meta Overlay
+
+Internal testing overlay that activates **all available overlays** at once. Used to verify that the full overlay catalogue can be composed without errors.
+
+> **Not shown in the interactive questionnaire.** Use it directly in a `superposition.yml` or test script.
+
+## Purpose
+
+The `all` overlay exists to make CI/integration testing straightforward: selecting it expands to every non-preset, non-hidden overlay in the live registry, exercising the full composition pipeline in one pass.
+
+```yaml
+# superposition.yml
+stack: compose
+containerName: meta-test
+overlays:
+    - all
+outputPath: .devcontainer
+```
+
+## How expansion works
+
+There is no `requires` list in `overlays/all/overlay.yml`. Instead, the dependency resolver in
+`resolveDependencies()` detects the special `all` overlay ID and replaces it with the full live
+overlay registry (excluding hidden and preset overlays) at resolution time. This means:
+
+- New overlays are automatically included the moment they are added to the catalogue — no manual
+  update to this file is needed.
+- The expansion is driven by the live registry, not a hard-coded list.
+
+## Conflicts
+
+Some overlays expanded from `all` are mutually exclusive at runtime:
+
+| Conflict                           | Details                                                 |
+| ---------------------------------- | ------------------------------------------------------- |
+| `docker-in-docker` ↔ `docker-sock` | Two different Docker access strategies — cannot coexist |
+
+The composer will emit warnings for these conflicts. They are expected and do not block the build. The intent is to test patch composition, not to produce a runnable container.
+
+## References
+
+- [Overlay authoring guide](../../docs/creating-overlays.md)
+- [All overlays](../../docs/overlays.md)

package/overlays/all/devcontainer.patch.json

@@ -0,0 +1,6 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {},
+    "customizations": {},
+    "forwardPorts": []
+}

package/overlays/all/overlay.yml

@@ -0,0 +1,14 @@
+id: all
+name: All Overlays
+description: Internal testing overlay that activates all available overlays to verify the full build
+category: dev
+hidden: true
+supports: []
+requires: []
+suggests: []
+conflicts: []
+tags:
+    - internal
+    - testing
+    - all
+ports: []

package/overlays/amp/setup.sh

@@ -3,6 +3,11 @@
 
 set -e
 
+# Source shared setup utilities (provides load_nvm)
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+load_nvm
+
 echo "📦 Installing Sourcegraph Amp CLI..."
 
 # Install @sourcegraph/amp globally

package/overlays/bun/setup.sh

@@ -34,7 +34,7 @@ if ! command -v bun &> /dev/null; then
     BUN_URL="https://github.com/oven-sh/bun/releases/download/bun-v${BUN_VERSION}/bun-linux-${BUN_ARCH}.zip"
     
     echo "   Downloading Bun version ${BUN_VERSION} for ${ARCH}..."
-    if ! wget "${BUN_URL}" -O /tmp/bun.zip 2>&1; then
+    if ! wget -q "${BUN_URL}" -O /tmp/bun.zip; then
         echo "   ❌ Failed to download Bun from ${BUN_URL}"
         exit 1
     fi
@@ -61,6 +61,15 @@ fi
 export BUN_INSTALL="$HOME/.bun"
 export PATH="$BUN_INSTALL/bin:$PATH"
 
+# Persist PATH so verify script (and interactive shells) can find bun
+for _shell_rc in "$HOME/.bashrc" "$HOME/.profile"; do
+    if [ -f "$_shell_rc" ] && ! grep -q 'BUN_INSTALL' "$_shell_rc" 2>/dev/null; then
+        echo 'export BUN_INSTALL="$HOME/.bun"' >> "$_shell_rc"
+        echo 'export PATH="$BUN_INSTALL/bin:$PATH"' >> "$_shell_rc"
+    fi
+done
+unset _shell_rc
+
 # Verify installation
 if command -v bun &> /dev/null; then
     INSTALLED_VERSION=$(bun --version)

package/overlays/bun/verify.sh

@@ -7,10 +7,15 @@ echo "🔍 Verifying Bun overlay..."
 echo ""
 
 # Check Bun is installed
+# The verify script runs in a non-interactive shell that may not have ~/.bun/bin on PATH.
 echo "1️⃣ Checking Bun..."
-if command -v bun &> /dev/null; then
+BUN_BIN="${BUN_INSTALL:-$HOME/.bun}/bin/bun"
+if command -v bun &>/dev/null; then
     bun --version
     echo "   ✅ Bun found"
+elif [ -x "$BUN_BIN" ]; then
+    "$BUN_BIN" --version
+    echo "   ✅ Bun found (at $BUN_BIN)"
 else
     echo "   ❌ Bun not found"
     exit 1

package/overlays/claude-code/setup.sh

@@ -3,6 +3,11 @@
 
 set -e
 
+# Source shared setup utilities (provides load_nvm)
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+load_nvm
+
 echo "📦 Installing Anthropic Claude Code CLI..."
 
 # Install @anthropic-ai/claude-code globally

package/overlays/cloudflared/setup.sh

@@ -13,18 +13,15 @@ echo "📦 Installing cloudflared..."
 # Check https://github.com/cloudflare/cloudflared/releases for newer versions
 CF_VERSION="${CLOUDFLARED_VERSION:-2025.2.1}"
 
-# Detect architecture
-ARCH=$(uname -m)
-case "$ARCH" in
-    x86_64) CF_ARCH="amd64" ;;
-    aarch64 | arm64) CF_ARCH="arm64" ;;
-    *) echo "   ⚠️  Unsupported architecture: $ARCH" ; CF_ARCH="amd64" ;;
-esac
-
-CF_URL="https://github.com/cloudflare/cloudflared/releases/download/${CF_VERSION}/cloudflared-linux-${CF_ARCH}"
-curl -sSL "$CF_URL" -o /tmp/cloudflared
-sudo install -m 755 /tmp/cloudflared /usr/local/bin/cloudflared
-rm -f /tmp/cloudflared
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+
+detect_arch amd64
+
+install_binary \
+    "https://github.com/cloudflare/cloudflared/releases/download/${CF_VERSION}/cloudflared-linux-${CS_ARCH}" \
+    "cloudflared" "755"
 
 # Verify installation
 if command -v cloudflared &> /dev/null; then

package/overlays/codex/README.md

@@ -5,6 +5,7 @@ Adds OpenAI Codex CLI with a persistent `.codex` folder for configurations.
 ## Features
 
 - **OpenAI Codex CLI** - AI-powered code generation and assistance from the command line
+- **Bubblewrap** - Linux sandbox dependency installed as `bwrap` for Codex
 - **Codex directory** - Creates `$HOME/.codex` for persistent configurations
 
 ## What is OpenAI Codex CLI?
@@ -26,8 +27,9 @@ The OpenAI Codex CLI (`@openai/codex`) provides command-line access to OpenAI's
 
 This overlay:
 
-1. Installs OpenAI Codex CLI globally via npm (`npm install -g @openai/codex`)
-2. Creates the `$HOME/.codex` directory for persistent configurations
+1. Installs the Linux `bubblewrap` package so `bwrap` is available for Codex sandboxing
+2. Installs OpenAI Codex CLI globally via npm (`npm install -g @openai/codex`)
+3. Creates the `$HOME/.codex` directory for persistent configurations
 
 **After setup:**
 
@@ -39,12 +41,13 @@ This overlay:
 After setup, run the verification script to ensure proper installation:
 
 ```bash
-bash .devcontainer/verify-codex.sh
+bash .devcontainer/scripts/verify-codex.sh
 ```
 
 This will check:
 
 - Codex CLI is installed and in PATH
+- `bwrap` is installed and in PATH
 - `.codex` directory exists
 
 ## Troubleshooting
@@ -90,7 +93,7 @@ codex explain "what does this regex do: /^[a-zA-Z0-9]+$/"
 codex complete "function fibonacci(n) {"
 ```
 
-For full documentation, visit: [OpenAI Codex CLI Documentation](https://github.com/openai/openai-codex-cli)
+For full documentation, visit: [OpenAI Codex CLI Documentation](https://github.com/openai/codex)
 
 ## Optional: Persistent .codex Mount
 
@@ -104,7 +107,7 @@ Then add this mount to your `devcontainer.json`:
 
 ```json
 "mounts": [
-  "source=${localEnv:HOME}${localEnv:USERPROFILE}/.codex,target=${containerEnv:HOME}/.codex,type=bind,consistency=cached"
+  "source=${localEnv:HOME}${localEnv:USERPROFILE}/.codex,target=/home/vscode/.codex,type=bind,consistency=cached"
 ]
 ```
 
@@ -124,5 +127,5 @@ This allows you to:
 
 ## Additional Resources
 
-- [OpenAI Codex CLI](https://github.com/openai/openai-codex-cli)
+- [OpenAI Codex CLI](https://github.com/openai/codex)
 - [OpenAI Platform](https://platform.openai.com/)

package/overlays/codex/devcontainer.patch.json

@@ -1,3 +1,9 @@
 {
-    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json"
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "bubblewrap",
+            "apk": "bubblewrap"
+        }
+    }
 }

package/overlays/codex/setup.sh

@@ -3,6 +3,11 @@
 
 set -e
 
+# Source shared setup utilities (provides load_nvm)
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+load_nvm
+
 echo "📦 Installing OpenAI Codex CLI..."
 
 # Install @openai/codex globally

package/overlays/codex/verify.sh

@@ -5,6 +5,14 @@ set -e
 
 echo "🔍 Verifying Codex overlay setup..."
 
+# Check if bubblewrap is installed for Codex sandboxing on Linux
+if ! command -v bwrap &> /dev/null; then
+    echo "✗ bubblewrap is not installed or not in PATH"
+    exit 1
+fi
+
+echo "✓ bubblewrap is installed: $(bwrap --version 2>/dev/null | head -n 1 || echo 'installed')"
+
 # Check if codex CLI is installed
 if ! command -v codex &> /dev/null; then
     echo "✗ codex CLI is not installed or not in PATH"

package/overlays/comfyui/.env.example

@@ -0,0 +1,34 @@
+# ComfyUI Configuration
+
+# ComfyUI models storage strategy:
+#
+# Option A (default) — named Docker volume (no host path needed):
+#   Leave COMFYUI_MODELS_HOST_PATH unset. Models persist in the Docker volume
+#   named "comfyui-models" and are shared between devcontainer and ComfyUI.
+#
+# Option B — bind mount to host directory (also accessible from host tools):
+#   Set COMFYUI_MODELS_HOST_PATH to an absolute host path.
+#   Docker creates the directory if it does not exist.
+#   Note: Docker Compose does not expand '~' in .env files; always use full absolute paths.
+#   macOS/Linux examples:
+#     COMFYUI_MODELS_HOST_PATH=/home/you/.cache/comfyui/models
+#     COMFYUI_MODELS_HOST_PATH=/home/you/ComfyUI/models
+#   Windows (Docker Desktop — use absolute path, no tilde):
+#     COMFYUI_MODELS_HOST_PATH=C:/Users/you/.cache/comfyui/models
+#
+# COMFYUI_MODELS_HOST_PATH=
+
+# Where ComfyUI-generated images/videos are saved.
+# Leave unset to use the named Docker volume "comfyui-output" (default),
+# or set to an absolute host path to save outputs to the host filesystem.
+# COMFYUI_OUTPUT_PATH=
+
+# ComfyUI Docker image tag. Use 'latest-cuda' for NVIDIA GPU, 'latest-rocm' for AMD/ROCm, or 'latest-cpu' for CPU-only.
+COMFYUI_VERSION=latest-cuda
+
+# Host port for the ComfyUI web UI. Default: 8188.
+COMFYUI_PORT=8188
+
+# Extra CLI arguments passed to ComfyUI at startup.
+# --listen 0.0.0.0 is required to accept connections from outside the container.
+CLI_ARGS=--listen 0.0.0.0

package/overlays/comfyui/README.md

@@ -0,0 +1,342 @@
+# ComfyUI Overlay
+
+Runs [ComfyUI](https://github.com/comfyanonymous/ComfyUI) as a Docker Compose service, providing a reproducible, containerised node-based image and video generation environment with a shared models directory accessible from both the devcontainer and the ComfyUI sidecar.
+
+## Features
+
+- **Node-based workflow UI** — Visual node editor for building Stable Diffusion and generative AI pipelines, accessible at `http://localhost:8188`
+- **REST and WebSocket API** — Programmatically submit workflows and receive results via ComfyUI's built-in API
+- **Custom node support** — Install community custom nodes to extend workflows with new models and operations
+- **Shared models directory** — Single volume root (`/opt/comfyui-models`) mounted into both the devcontainer and the ComfyUI sidecar; model files are accessible by scripts running in the devcontainer without going through the HTTP API
+- **Output persistence** — Generated images and videos are saved to a named volume (or host path) so they survive container restarts
+- **Port 8188** — Standard ComfyUI web UI port, auto-forwarded and opened in the browser
+
+## How It Works
+
+ComfyUI runs as a long-lived Docker Compose service (`comfyui`) alongside your devcontainer. The devcontainer reaches it via the hostname `comfyui` on port `8188`.
+
+**Service configuration:**
+
+- Image: `ghcr.io/ai-dock/comfyui:latest-cuda` (configurable via `COMFYUI_VERSION`)
+- Network: `devnet` (shared with the dev container)
+- Port: `8188` (ComfyUI web UI and REST API)
+- Volumes: single models root shared between devcontainer and ComfyUI sidecar
+
+The `COMFYUI_URL` environment variable is set to `http://comfyui:8188` in the devcontainer so scripts and tools can connect without hard-coding the address.
+
+The `COMFYUI_MODELS_DIR` environment variable is set to `/opt/comfyui-models` in the devcontainer — the fixed path where the shared models volume is mounted.
+
+## Shared Models Directory
+
+`/opt/comfyui-models` is the single models root visible to **both** the devcontainer and the ComfyUI sidecar. Files written to this directory from any side are immediately visible to the other — no restart required.
+
+### Subdirectory Layout
+
+`setup.sh` pre-creates all expected subdirectories on first run:
+
+```
+/opt/comfyui-models/
+├── checkpoints/      — Stable Diffusion base models (.safetensors, .ckpt)
+├── loras/            — LoRA fine-tuning weights
+├── controlnet/       — ControlNet guidance models
+├── clip_vision/      — CLIP Vision models
+├── vae/              — VAE decoder models
+├── embeddings/       — Textual inversion embeddings
+└── upscale_models/   — Image upscaling models (ESRGAN, etc.)
+```
+
+### Tier 1 (default): Named Docker Volume
+
+When `COMFYUI_MODELS_HOST_PATH` is **not** set (the default), a named Docker Compose volume `comfyui-models` is used. Models persist across container rebuilds without any host-side setup and work on all platforms.
+
+```yaml
+# docker-compose.yml (simplified)
+volumes:
+    comfyui-models:
+        name: comfyui-models
+```
+
+### Tier 2 (opt-in): Bind Mount to Host Path
+
+Set `COMFYUI_MODELS_HOST_PATH` in `.devcontainer/.env` to switch to a bind mount — the same Compose config handles both cases with no structural change:
+
+```bash
+# .devcontainer/.env
+# Note: Docker Compose does not expand '~' in .env files; always use full absolute paths.
+
+# macOS / Linux
+COMFYUI_MODELS_HOST_PATH=/home/you/.cache/comfyui/models
+
+# Windows (Docker Desktop — use absolute path, no tilde)
+COMFYUI_MODELS_HOST_PATH=C:/Users/you/.cache/comfyui/models
+
+# Reuse an existing local ComfyUI install
+COMFYUI_MODELS_HOST_PATH=/home/you/ComfyUI/models
+```
+
+### Reusing an Existing Local ComfyUI Install
+
+Point `COMFYUI_MODELS_HOST_PATH` at your existing models directory to avoid re-downloading multi-GB files:
+
+```bash
+# Use the full absolute path — Docker Compose does not expand '~' in .env files
+COMFYUI_MODELS_HOST_PATH=/home/you/ComfyUI/models
+```
+
+### Downloading Models from the Devcontainer
+
+Use `curl`, `wget`, or `huggingface-cli` inside the devcontainer to download models directly into the shared directory — they are immediately visible in ComfyUI's model browser:
+
+```bash
+# Download a checkpoint
+curl -L -o "${COMFYUI_MODELS_DIR}/checkpoints/my-model.safetensors" \
+     "https://huggingface.co/.../resolve/main/my-model.safetensors"
+
+# Download with wget
+wget -P "${COMFYUI_MODELS_DIR}/checkpoints/" \
+     "https://huggingface.co/.../resolve/main/my-model.safetensors"
+
+# Download with huggingface-cli (requires huggingface_hub)
+huggingface-cli download org/repo my-model.safetensors \
+    --local-dir "${COMFYUI_MODELS_DIR}/checkpoints/"
+```
+
+Files written to `$COMFYUI_MODELS_DIR` are **immediately visible in ComfyUI** — no restart is needed because the volume is live-mounted.
+
+### Windows Note
+
+Docker Compose does not expand `~` in `.env` files on any platform. Always use full absolute paths for `COMFYUI_MODELS_HOST_PATH`:
+
+```bash
+# Windows — use absolute path with forward slashes
+COMFYUI_MODELS_HOST_PATH=C:/Users/you/.cache/comfyui/models
+```
+
+## Common Workflows
+
+### Open the Web UI
+
+Once the container is running, open `http://localhost:8188` in your browser. The node editor loads automatically.
+
+### Load a Workflow
+
+1. Download a workflow JSON file (e.g. from [ComfyUI workflows](https://comfyworkflows.com/))
+2. In the ComfyUI UI, click **Load** and select the JSON file
+3. Connect missing model nodes to your available checkpoints and click **Queue Prompt**
+
+### Run Inference via CLI
+
+```bash
+# Submit a workflow JSON via the ComfyUI API from inside the devcontainer
+curl -X POST http://comfyui:8188/prompt \
+  -H "Content-Type: application/json" \
+  -d @workflow_api.json
+```
+
+### Save Outputs
+
+Generated images appear in the `comfyui-output` named volume by default, or at the path configured in `COMFYUI_OUTPUT_PATH`.
+
+## GPU Acceleration
+
+GPU passthrough is enabled out of the box. The `comfyui` service receives `gpus: all` via the `deploy.resources.reservations.devices` block in the overlay's `docker-compose.yml`:
+
+```yaml
+deploy:
+    resources:
+        reservations:
+            devices:
+                - driver: nvidia
+                  count: all
+                  capabilities: [gpu]
+```
+
+### Prerequisites
+
+GPU passthrough requires the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) installed and configured on the host:
+
+```bash
+# Verify NVIDIA driver is installed on the host
+nvidia-smi
+
+# Verify NVIDIA Container Toolkit
+docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi
+```
+
+> **Note:** On machines without an NVIDIA GPU or without the NVIDIA Container Toolkit, Docker Compose may warn about unresolvable device requests. Use `COMFYUI_VERSION=latest-cpu` to switch to CPU-only mode (see below).
+
+**See also:** The [`cuda`](../cuda/README.md) overlay installs NVIDIA CUDA toolkit support in the devcontainer itself.
+
+### CPU-Only Mode
+
+If you do not have an NVIDIA GPU, switch to the CPU image by setting `COMFYUI_VERSION` in `.devcontainer/.env`:
+
+```bash
+COMFYUI_VERSION=latest-cpu
+```
+
+CPU inference is significantly slower but works on any machine.
+
+### AMD GPU (ROCm)
+
+For AMD GPU support, use a ROCm-compatible image tag:
+
+```bash
+COMFYUI_VERSION=latest-rocm
+```
+
+**See also:** The [`rocm`](../rocm/README.md) overlay for ROCm toolkit support in the devcontainer.
+
+## Custom Nodes
+
+Custom nodes extend ComfyUI with new model types, loaders, and processing steps. To persist custom nodes across container rebuilds, add a named volume for the custom nodes directory via a custom Docker Compose patch in `.devcontainer/custom/docker-compose.patch.yml`:
+
+```yaml
+services:
+    comfyui:
+        volumes:
+            - comfyui-custom-nodes:/opt/ComfyUI/custom_nodes
+
+volumes:
+    comfyui-custom-nodes:
+```
+
+Then install custom nodes from inside the running container:
+
+```bash
+docker compose exec comfyui bash -c \
+  "cd /opt/ComfyUI/custom_nodes && git clone https://github.com/example/custom-node"
+```
+
+## API Usage
+
+ComfyUI exposes a REST and WebSocket API for programmatic workflow execution.
+
+### Submit a Workflow
+
+```bash
+# POST a workflow (in API format) to the queue
+curl -X POST http://comfyui:8188/prompt \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": { /* workflow nodes */ }, "client_id": "my-client"}'
+```
+
+### Check Queue Status
+
+```bash
+curl http://comfyui:8188/queue
+```
+
+### Retrieve Output Files
+
+```bash
+# List generated images
+curl http://comfyui:8188/history
+
+# Download a specific file by filename
+curl -O http://comfyui:8188/view?filename=ComfyUI_00001_.png&type=output
+```
+
+### WebSocket (real-time progress)
+
+```python
+import websocket, json
+
+ws = websocket.WebSocket()
+ws.connect("ws://comfyui:8188/ws?clientId=my-client")
+while True:
+    message = json.loads(ws.recv())
+    print(message)  # progress updates, execution events, etc.
+```
+
+## Configuration
+
+### Environment Variables
+
+Set these in `.devcontainer/.env` (copy from `.devcontainer/.env.example`):
+
+| Variable                   | Default               | Description                                                                                          |
+| -------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------- |
+| `COMFYUI_MODELS_DIR`       | `/opt/comfyui-models` | Path inside devcontainer where models are accessible (set in devcontainer.patch.json; do not change) |
+| `COMFYUI_MODELS_HOST_PATH` | _(unset)_             | Host-side bind mount source; when unset the named volume `comfyui-models` is used                    |
+| `COMFYUI_OUTPUT_PATH`      | _(unset)_             | Host path for generated outputs; when unset the named volume `comfyui-output` is used                |
+| `COMFYUI_VERSION`          | `latest-cuda`         | Docker image tag (`latest-cuda`, `latest-cpu`, `latest-rocm`)                                        |
+| `COMFYUI_PORT`             | `8188`                | Host port for the web UI                                                                             |
+| `CLI_ARGS`                 | `--listen 0.0.0.0`    | Extra CLI arguments passed to ComfyUI at startup                                                     |
+
+### Example `.env`
+
+```bash
+# Option A (default) — named Docker volume, no host path needed:
+# Leave COMFYUI_MODELS_HOST_PATH unset.
+
+# Option B — bind mount to host directory:
+# macOS/Linux:
+# COMFYUI_MODELS_HOST_PATH=~/.cache/comfyui/models
+# Windows (Docker Desktop):
+# COMFYUI_MODELS_HOST_PATH=C:/Users/you/.cache/comfyui/models
+
+# Where generated outputs are saved (named volume by default):
+# COMFYUI_OUTPUT_PATH=~/.cache/comfyui/output
+```
+
+## Troubleshooting
+
+### Missing Model Files
+
+**Symptom:** ComfyUI loads but shows "model not found" errors when running a workflow.
+
+**Solution:** Ensure model files exist in the correct subdirectory inside the shared models root:
+
+```bash
+ls "${COMFYUI_MODELS_DIR}/checkpoints/"   # Should list .safetensors files
+```
+
+If `COMFYUI_MODELS_HOST_PATH` is set, verify the host directory contains the expected subdirectories.
+
+### CUDA / GPU Not Detected
+
+**Symptom:** ComfyUI runs on CPU despite having an NVIDIA GPU.
+
+**Solutions:**
+
+1. Ensure the `deploy.resources.reservations.devices` block is present in the compose service (see [GPU Acceleration](#gpu-acceleration) above)
+2. Verify NVIDIA Container Toolkit is installed on the host: `nvidia-smi`
+3. Switch to `COMFYUI_VERSION=latest-cuda` if using a different tag
+
+### Port 8188 Already in Use
+
+**Symptom:** Container fails to start with "port already in use".
+
+**Solution:** Change the host port in `.devcontainer/.env`:
+
+```bash
+COMFYUI_PORT=8288
+```
+
+Then rebuild the container (`Dev Containers: Rebuild Container`).
+
+### Container Starts but UI is Unreachable
+
+**Symptom:** Browser shows "connection refused" on `http://localhost:8188`.
+
+**Solutions:**
+
+1. Check the container is running: `docker compose ps`
+2. Check logs for startup errors: `docker compose logs comfyui`
+3. Ensure `CLI_ARGS` includes `--listen 0.0.0.0` so ComfyUI accepts external connections
+
+## References
+
+- [ComfyUI GitHub Repository](https://github.com/comfyanonymous/ComfyUI)
+- [ComfyUI API Documentation](https://github.com/comfyanonymous/ComfyUI/tree/master/script_examples)
+- [ai-dock/comfyui Docker Image](https://github.com/ai-dock/comfyui)
+- [ComfyUI Workflows Community](https://comfyworkflows.com/)
+- [Civitai — Model Downloads](https://civitai.com/)
+
+**Related Overlays:**
+
+- [`cuda`](../cuda/README.md) — NVIDIA CUDA toolkit for GPU-accelerated workloads
+- [`rocm`](../rocm/README.md) — AMD ROCm toolkit for GPU-accelerated workloads
+- [`python`](../python/README.md) — Python runtime for automation scripts
+- [`ollama`](../ollama/README.md) — Local LLM inference server