fix(infra): build claude-runner image out-of-band instead of via compose profile

The `claude-runner` image is a runtime dependency (the API spawns containers
from it per session), not a Compose service. A previous attempt shipped it as
a `profiles: [build-only]` service, but Compose excludes profiled services
from both build and run unless the profile is explicitly activated — which
Coolify does not do, causing `404 No such image: claude-runner:latest` when
the API tries to start a session.

Changes:
- Remove `claude-runner` service from infra/coolify/docker-compose.prod.yml
- Fix the Makefile `build-runner` tag (`claude-runner:latest`, no namespace)
- Make `make build` also build the runner
- Document the per-host one-time build in Quick Start, self-hosting guide,
  and Coolify guide (with pre-deployment command)
- Update CLAUDE.md decisions and troubleshooting

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mariuspruvot

CLAUDE.md

@@ -1,6 +1,7 @@
 ## Quick Start
 
 ```bash
+make build-runner                # One-time per Docker host: build the claude-runner image
 docker compose up --build        # Start all services (API :8000, Web :5173, Postgres :5432)
 make lint                        # Ruff check + format + mypy (API), ESLint (Web)
 make test                        # pytest (API), vitest (Web)
@@ -137,7 +138,7 @@ Key additions for production: `ENVIRONMENT=production`, `ADMIN_PASSWORD`, `CORS_
 - **Open source target**: designed for self-hosting with own Claude licenses
 - **Post-results to PR**: after session completion, the API can post score card as a PR comment — opt-in per installation via `post_results_to_pr` boolean; extraction and formatting in `container/pr_comment.py`, triggered in `_event_stream()` after `mark_completed()`
 - **Coolify deployment**: Two-domain setup via Traefik: `helprs.tech` (web) and `api.helprs.tech` (API). TLS via Let's Encrypt, managed by Coolify. Domains are set in Coolify UI (General > Domains for api / Domains for web) — they may get cleared on redeploy, re-check after each deploy. "Preserve Repository During Deployment" must be enabled so skills are available on the host. The prod compose uses `./` paths (repo-root-relative) because Coolify sets `--project-directory` to the repo root.
-- **claude-runner image**: built via a `profiles: [build-only]` service in the prod compose — Coolify builds the image but never starts the container. The API spawns it dynamically. Image name is `claude-runner:latest` (no namespace prefix).
+- **claude-runner image**: NOT a Compose service — it is a runtime dependency built once per Docker host with `make build-runner` (or a pre-deploy command on managed platforms). The API spawns containers from it dynamically via the mounted Docker socket. Image name is `claude-runner:latest` (no namespace prefix — hard-coded in `container/service.py:CLAUDE_RUNNER_IMAGE`). Previous attempt to include it as a `profiles: [build-only]` compose service was removed because `profiles:` excludes the service from both build and run unless the profile is explicitly activated — which Coolify does not do, causing `404 No such image` failures on spawn.
 - **Non-root API container**: production Dockerfile uses `appuser` with `chown -R appuser:appuser /app` for uv cache writes. Docker socket access requires `group_add: ["${DOCKER_GID:-994}"]` in the compose to match the host's docker group GID.
 - **BYOK supports OAuth tokens**: `validate_claude_key()` accepts both API keys (`sk-ant-api03-...`) and OAuth tokens (`sk-ant-oat...`). OAuth tokens skip server-side validation (validated at runtime by Claude Code CLI). Frontend setup page guides users to `claude setup-token`.
 - **VITE_* build args**: `VITE_API_URL` and `VITE_GITHUB_APP_SLUG` are build-time variables — must be passed as `args` in the compose and declared as `ARG`/`ENV` in `Dockerfile.web`. They cannot be set at runtime.

Makefile

@@ -18,9 +18,15 @@ test:
 
 build:
 	docker compose -f infra/coolify/docker-compose.prod.yml build
+	$(MAKE) build-runner
 
+# Builds the claude-runner image used by the API to spawn per-session
+# containers. This is a one-time setup per Docker host — the image is not a
+# service, it's a runtime dependency referenced by tag in
+# helprs/modules/container/service.py (CLAUDE_RUNNER_IMAGE). Re-run this
+# target whenever infra/docker/claude-runner/ changes.
 build-runner:
-	docker build -t helprs/claude-runner:latest infra/docker/claude-runner/
+	docker build -t claude-runner:latest infra/docker/claude-runner/
 
 migrate:
 	cd apps/api && uv run alembic upgrade head

README.md

@@ -42,8 +42,8 @@ cd helprs
 cp .env.example .env
 # Fill in .env (see docs/self-hosting.md for details)
 
+make build-runner                # One-time: build the Claude Code runner image (required before first session)
 docker compose up --build        # API :8000, Web :5173, Postgres :5432
-make build-runner                # Build the Claude Code container image
 ```
 
 Open [http://localhost:5173](http://localhost:5173), authenticate with GitHub, and you're ready to go.

docs/deploy-coolify.md

@@ -133,6 +133,21 @@ Click **Save**. Coolify generates Traefik routing rules and provisions Let's Enc
 
 - **Preserve Repository During Deployment**: **Enable this**. Without it, Coolify removes the cloned repo after building images. The `skills/` directory must remain on the host because the API mounts it into claude-runner containers at runtime.
 
+### Pre-deployment Command (required)
+
+The API spawns ephemeral containers from the `claude-runner` image. This image is **not** a Compose service — it is a runtime dependency that must exist on the Docker host before the API can start a session.
+
+Set Coolify's **Pre-deployment Command** to:
+
+```bash
+docker build -t claude-runner:latest /data/coolify/applications/<uuid>/infra/docker/claude-runner/
+```
+
+Replace `<uuid>` with your Coolify application directory (same one you use for `SKILLS_HOST_PATH` in step 7). The image is tagged `claude-runner:latest` with no namespace prefix — this is the exact tag the API references (`CLAUDE_RUNNER_IMAGE` in `apps/api/src/helprs/modules/container/service.py`).
+
+!!! tip "Why a pre-deploy command?"
+    Coolify runs `docker compose up --build`, which only builds services listed in the compose file. Keeping `claude-runner` out of the compose avoids two footguns: Compose trying to start a container that has no long-lived process, and `profiles:` silently excluding the service from the build. A one-line pre-deploy command is explicit and portable to any host. Re-runs are cheap (Docker caches the layers).
+
 ### Advanced > General
 
 - **Auto Deploy**: Enable for automatic redeployment on push to `main`.
@@ -144,9 +159,10 @@ Click **Save**. Coolify generates Traefik routing rules and provisions Let's Enc
 Click **Deploy**. Coolify will:
 
 1. Clone the repo
-2. Build the API, Web, and claude-runner images
-3. Start the API, Web, and DB containers (claude-runner is `profiles: [build-only]`, not started)
-4. Run Alembic migrations automatically (API entrypoint runs `alembic upgrade head`)
+2. Run the pre-deploy command to build `claude-runner:latest` on the host
+3. Build the API and Web images
+4. Start the API, Web, and DB containers (claude-runner is not a service — it is spawned per session by the API)
+5. Run Alembic migrations automatically (API entrypoint runs `alembic upgrade head`)
 
 ### Verify
 
@@ -223,17 +239,14 @@ docker ps | grep claude-runner
 # Should be empty (it's only spawned on demand, not a long-lived service)
 ```
 
-If the image is missing, the `claude-runner` service may have been excluded from the build. Verify the compose file includes:
+If the image is missing, the pre-deployment command did not run or failed. Build it manually:
 
-```yaml
-claude-runner:
-  build:
-    context: ./infra/docker/claude-runner
-  image: claude-runner
-  profiles:
-    - build-only
+```bash
+docker build -t claude-runner:latest /data/coolify/applications/<uuid>/infra/docker/claude-runner/
 ```
 
+Then re-check the pre-deployment command in Coolify (step 5) so future deploys rebuild it automatically. An image pruning operation (`docker image prune -a`) will also remove it — the pre-deploy command will rebuild it on the next deploy.
+
 ---
 
 ## 10. Install the GitHub App
@@ -295,7 +308,13 @@ The `DOCKER_GID` does not match your server's Docker group. See [step 8](#8-dock
 No such image: claude-runner:latest
 ```
 
-Verify the compose includes the claude-runner service with `profiles: [build-only]`. Redeploy to rebuild the image.
+This happens when the pre-deployment command (step 5) did not run or the image was pruned. Build it manually on the host:
+
+```bash
+docker build -t claude-runner:latest /data/coolify/applications/<uuid>/infra/docker/claude-runner/
+```
+
+Then verify the pre-deployment command is configured in Coolify so it rebuilds on every deploy. The image name must be exactly `claude-runner:latest` (no namespace prefix) — the API references this tag in `apps/api/src/helprs/modules/container/service.py`.
 
 ### Skills directory is empty
 

docs/self-hosting.md

@@ -169,17 +169,26 @@ POSTGRES_PASSWORD=    # Strong password for production DB
 ### Option A: Docker Compose (simplest)
 
 ```bash
-# Build and start all services (including claude-runner image)
+# 1. Build the claude-runner image (one-time per host; re-run if infra/docker/claude-runner/ changes)
+make build-runner
+
+# 2. Build and start services (api, web, db)
 docker compose -f infra/coolify/docker-compose.prod.yml up -d --build
 
-# Verify services are healthy
+# 3. Verify services are healthy
 docker compose -f infra/coolify/docker-compose.prod.yml ps
 ```
 
-!!! note "claude-runner image"
-    The `claude-runner` service in the compose file uses `profiles: [build-only]`.
-    It is built during `docker compose up --build` but does not run as a long-lived
-    service. The API spawns claude-runner containers on demand.
+!!! important "Why `claude-runner` is not in the compose file"
+    The `claude-runner` image is a **runtime dependency**, not a service. The API
+    spawns a new container from it for each session (via the mounted Docker socket)
+    — it is never run as a long-lived process. Putting it in the compose file would
+    either cause Compose to try to start it (and crash), or require a `profiles:`
+    flag that silently excludes it from automated builds. A plain `docker build` is
+    explicit and works on every Docker host.
+
+    Re-run `make build-runner` after editing anything under `infra/docker/claude-runner/`
+    or after a `docker image prune -a`.
 
 The API runs on port 8000, the frontend on port 80. You need a reverse proxy (nginx, Caddy, Traefik) in front to handle TLS and route traffic.
 
@@ -211,6 +220,9 @@ cd helprs
 cp .env.example .env
 # Edit .env with your values...
 
+# Build the claude-runner image (one-time per host)
+make build-runner
+
 # Start services
 docker compose -f infra/coolify/docker-compose.prod.yml up -d --build
 
@@ -318,7 +330,7 @@ If you enabled **Post results to PR** in installation settings, the score card i
 ### Container won't start
 
 - Verify Docker socket is mounted: check that `/var/run/docker.sock` is accessible to the API container
-- Verify the claude-runner image exists: `docker images | grep claude-runner`
+- Verify the claude-runner image exists: `docker images | grep claude-runner` — if missing, run `make build-runner` (the image is a per-host one-time build, not a Compose service)
 - Check `SKILLS_HOST_PATH` is an absolute path and the directory exists on the Docker host
 - Verify the `DOCKER_GID` matches the host's Docker group: `getent group docker | cut -d: -f3`
 - Check API logs for container creation errors: `docker compose logs api | grep container`

infra/coolify/docker-compose.prod.yml

@@ -60,12 +60,10 @@ services:
           memory: 128M
     restart: unless-stopped
 
-  claude-runner:
-    build:
-      context: ./infra/docker/claude-runner
-    image: claude-runner
-    profiles:
-      - build-only
+  # Note: the `claude-runner` image is NOT a service — it is a runtime
+  # dependency built once per Docker host with `make build-runner` (or via a
+  # Coolify pre-deploy command). The API spawns containers from it dynamically
+  # via the Docker socket. See docs/deploy-coolify.md and docs/self-hosting.md.
 
   db:
     image: postgres:16-alpine