docs/stacks/CLAUDE.md

Notes for agents working in /opt/stacks (CT 104 "docker")

Most stacks here are intentional and active. Two things deserve explicit awareness so no agent "helpfully" reverts them:

Pocket-ID is gone from this CT (migrated 2026-05-20)

• Pocket-ID moved off CT 104 to dedicated CT 110 ("id", 192.168.1.5).
• The compose file /opt/stacks/pocketid/docker-compose.yml was deliberately renamed to docker-compose.yml.MIGRATED-TO-CT110-2026-05-20 so accidental docker compose up in that directory is a no-op.
• The data dir /opt/stacks/pocketid/data/ is a migration snapshot only. It is stale; authoritative writes happen on CT 110 since the cutover.
• Zoraxy upstream for id.nuclide.systems now points at 192.168.1.5:11000.
• Do not restart, compose up, or re-deploy pocket-id here. If something appears broken in OIDC, investigate CT 110 instead. SSH/Console access via pct enter 110 on the host, or https://192.168.1.5:11000/.

Dormant stacks — defined but not running on purpose

Per the audit on 2026-05-20, the following stack directories exist but their containers are intentionally not running. Some are planned to move to CT 109 "observe" when that LXC is built; others are legacy experiments waiting on a decision:

• /opt/stacks/arcane/ — Manager will move to CT 109; edge agent eventually deploys here
• /opt/stacks/dozzle/ — UI will move to CT 109; agent eventually deploys here
• /opt/stacks/homepage/ — replaced by Homarr on CT 109; can be removed once CT 109 lands
• /opt/stacks/arr-stack/, streamio/, nexa/, qdrant/, proxy/, vpn/ — legacy experiments

Do not start these without checking with the operator first.

MCP gateway leaves, MCP child containers stay (planned)

When CT 109 "observe" lands, /opt/stacks/ai/mcp-gateway/ moves to CT 109 (it's a control plane: OIDC, agent scheduling, token store, usage stats). The ~20 MCP child server containers in this CT (mcp-searxng, mcp-gotify, mcp-immich, mcp-fetch, mcp-time, comfyui-mcp, daytona-mcp, kroki-mcp, etc.) stay here on CT 104.

The migrated gateway will reach this CT's docker daemon over the planned docker-socket-proxy (see /docs/proxmox-optimizations.md §16). Until CT 109 exists, the gateway runs locally and uses the bind-mounted socket. Do not piecemeal-move the gateway; it's tied to the CT 109 build.

What is safe to do here

• Anything to do with the actively-running ~65 containers (Immich, n8n, Karakeep, ComfyUI, Daytona, Vaultwarden, Paperless, LobeChat, LiteLLM, MCP servers, etc.).
• Image pulls + rebuilds for the active stacks (mind the n8n version pin — see its docker-compose.yaml comment).
• Rotate exposed secrets in .env files (compose YAMLs themselves are git-tracked).