/docker-setup

name: docker-setup
description: Host-only, operator-invoked. Generates Docker scaffolding and walks the operator through token setup, build, start, MCP plugin configuration, workspace trust, and verification. Offers to back up and overwrite existing Docker files. Run after /hatch.
disable-model-invocation: true

Docker Setup

Generate Docker scaffolding for running hermit as an always-on autonomous agent in a container. Docker provides isolation, crash recovery, and a reproducible environment. The default `auto` mode (classifier-reviewed autonomy) works well for most Docker hermits. Operators who need zero prompts for fully unattended operation can opt into `bypassPermissions` via `/hermit-settings permissions`.

**Tone:** Friendly guided wizard. Celebrate progress. When something fails, help fix it.

**Important:** Step 0's container check is a hard short-circuit — run it first and abort on `container` before anything else. After confirming host execution, run `docker-preflight.ts` once (Step 1) — it gathers all the read-only signals (docker presence, config existence, WSL path, existing docker files, host `~/.gitconfig`, auto-memory seed, a live non-Docker owner of the state dir) as a single JSON blob, so don't fan those probes out into separate Bash calls. Reuse its result for the git-identity (Step 4) and auto-memory (Step 5) decisions rather than re-probing. Step 2's project-dependency scan stays normal file reads (Read tool) plus analysis. Everything that mutates state or drives the container (file backups, `docker compose`, `tmux`, `mkdir`/`touch` setup-mode, status polls, channel `send-keys`) must run strictly sequentially in its documented order — never batch those.

Templates live in `${CLAUDE_SKILL_DIR}/../../state-templates/docker/`.

Plan

0. Refuse to run inside the hermit container

This skill is host-only — it generates Docker scaffolding on the host filesystem and drives `docker compose up`.

Run: `[ -f /.dockerenv ] || [ -f /run/.containerenv ] && echo container || echo host`

If the output is `container`, **stop immediately** — do not proceed to step 1. Print:

> This skill generates host-side Docker scaffolding and then drives `docker compose up`. Run it from your host shell in the project root. To pair a channel later, run `/claude-code-hermit:channel-setup` from the host. To check what's already configured *inside* the running container, run `/claude-code-hermit:hermit-doctor`.

1. Prerequisites

Run the pre-flight probe once and parse its JSON: `bun ${CLAUDE_PLUGIN_ROOT}/scripts/docker-preflight.ts "$(pwd)"` — pass `"$(pwd)"` so the auto-memory path key is keyed off the shell's logical path, matching Claude Code even through a symlinked project root. It returns `{ dockerVersion, configExists, isWSL, existing: {dockerfile, entrypoint, compose}, gitconfigExists, memory: {pathKey, seedExists}, liveOwner }`. Hold the result — Steps 4 and 5 reuse `gitconfigExists` and `memory` instead of re-probing. Apply these gates:

1. If `dockerVersion` is null: "Docker isn't installed — grab it from https://docs.docker.com/get-docker/ and come back!" 2. If `configExists` is false: "Run `/claude-code-hermit:hatch` first, then come back." 3. If `isWSL` is true: abort — "Clone inside WSL2 (e.g. `/home/you/project`) and run from there." 4. If `liveOwner` is non-null (`{ mode, ageSecs }`): abort: "A live `<mode>` hermit owns this project's state (activity `<ageSecs>`s ago). Stop it first with `.claude-code-hermit/bin/hermit-stop` (run it from a separate terminal if this session *is* that hermit), then re-run this skill." The container's entrypoint refuses to boot beside it and goes inert, so this must abort before anything is backed up, written, or built. Do not offer to stop it for the operator, and do not suggest `HERMIT_FORCE_BOOT=1`: that override is for split-state recovery, not for a hermit that is simply still running. If the operator reports that `hermit-stop` itself refused ("No tmux session … but state activity Ns ago"), the recorded owner is a stale record, not a live hermit — the liveness it sees is this session's own; have them follow the `pgrep -af "claude --channels"` line `hermit-stop` prints, kill any orphan it names, and re-run `hermit-stop` once nothing is left. 5. If any of `existing.dockerfile` / `existing.entrypoint` / `existing.compose` is true:

• List them, then ask with `AskUserQuestion` (header: "Docker files"): **No — keep existing** (abort; remove or rename manually, then re-run) / **Yes — back up** (move to docker-backup/ and regenerate).
• "Yes — back up" → move to `docker-backup/`, continue
• "No — keep existing" → abort
• Never overwrite `.env` — only append missing vars (step 5).

1.5. Setup mode gate

Determine whether to run in **Quick** or **Advanced** mode.

**Argument-driven**: if invoked with the positional argument `quick` (e.g. `/claude-code-hermit:docker-setup quick`), skip the question below and run Quick directly. The operator can always re-invoke `/claude-code-hermit:docker-setup` without the arg later to drop into Advanced.

**Otherwise, ask:**

questions: [
  {
    header: "Setup mode",
    question: "How would you like to configure Docker?",
    options: [
      { label: "Quick", description: "OAuth + bridge networking, auto-mirror trusted plugins, build immediately" },
      { label: "Advanced", description: "Full wizard — pick auth, networking, every plugin, every package" }
    ]
  }
]

**Quick-mode contract — security non-negotiables.** Quick mode never bulk-accepts third-party plugins, never weakens the safelist, never skips the public-repo pre-flight, and never bypasses the write-time assertion. Those gates exist because that's the line where defaults stop being safe. Quick only auto-defaults the choices that have one obviously-correct answer (auth, networking, build-now) and the SAFE plugin batch (claude-plugins-official + gtapps/* — already vetted by the safelist). Minting the long-lived