refactor(infra): use build-only service pattern for claude-runner

Switches from "out-of-band make build-runner" (previous commit) to a proper
Compose build-only service:

    claude-runner:
      build: { context: ./infra/docker/claude-runner }
      image: claude-runner:latest
      entrypoint: ["/bin/true"]
      restart: "no"

The container exits immediately on `docker compose up` (entrypoint is
overridden to `/bin/true`) and is not restarted, so it produces no runtime
overhead — but Compose still builds the image and leaves it tagged
`claude-runner:latest` on the host, ready for the API to spawn session
containers from via the Docker socket.

Benefits over the previous commit:
- `docker compose up --build` is the single command on every host (Coolify,
  VPS, local dev, ECS EC2)
- No Coolify pre-deployment command to configure in the UI
- No `make build-runner` step for users
- Rebuilds automatically whenever `infra/docker/claude-runner/` changes

Applied to both the dev `docker-compose.yml` and the prod
`infra/coolify/docker-compose.prod.yml`. `make build-runner` stays as a
convenience shortcut for quick iteration. Docs reverted to the simpler
"just run compose" narrative.

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

Author: mariuspruvot

CLAUDE.md

@@ -1,7 +1,6 @@
 ## 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)
@@ -138,7 +137,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**: 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.
+- **claude-runner image**: declared in both `docker-compose.yml` and `infra/coolify/docker-compose.prod.yml` as a **build-only service** — `entrypoint: ["/bin/true"]` + `restart: "no"` so the container exits immediately on `up`, leaving only the built image `claude-runner:latest` on the host. The API spawns containers from this image dynamically via the mounted Docker socket. Image tag is hard-coded in `container/service.py:CLAUDE_RUNNER_IMAGE` — it must stay `claude-runner:latest` (no namespace prefix). Earlier attempt with `profiles: [build-only]` was reverted: `profiles:` excludes a service from both build AND run unless the profile is explicitly activated, which Coolify does not do, causing `404 No such image` failures on session 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,13 +18,13 @@ 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.
+# Rebuild just the claude-runner image. Normally you don't need to call this
+# directly — both compose files declare claude-runner as a build-only service,
+# so `docker compose up --build` produces the image as a side-effect. This
+# shortcut is useful for quick iteration on infra/docker/claude-runner/ without
+# touching the API or web services. Image tag must match
+# CLAUDE_RUNNER_IMAGE in helprs/modules/container/service.py.
 build-runner:
 	docker build -t claude-runner:latest infra/docker/claude-runner/
 

README.md

@@ -42,8 +42,7 @@ 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
+docker compose up --build        # API :8000, Web :5173, Postgres :5432 (+ builds the claude-runner image)
 ```
 
 Open [http://localhost:5173](http://localhost:5173), authenticate with GitHub, and you're ready to go.

docker-compose.yml

@@ -34,6 +34,16 @@ services:
       - CHOKIDAR_USEPOLLING=true
     command: npx vite --host 0.0.0.0 --port 5173
 
+  # Build-only service: the API spawns containers from this image dynamically
+  # via the Docker socket. `entrypoint: /bin/true` + `restart: "no"` make the
+  # container exit immediately — the image stays available on the host.
+  claude-runner:
+    build:
+      context: ./infra/docker/claude-runner
+    image: claude-runner:latest
+    entrypoint: ["/bin/true"]
+    restart: "no"
+
   db:
     image: postgres:16-alpine
     ports:

docs/deploy-coolify.md

@@ -133,21 +133,6 @@ 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`.
@@ -159,10 +144,9 @@ Replace `<uuid>` with your Coolify application directory (same one you use for `
 Click **Deploy**. Coolify will:
 
 1. Clone the repo
-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`)
+2. Build the API, Web, and claude-runner images (claude-runner is a **build-only service** — the container exits immediately with `/bin/true`, leaving the image available on the host for the API to spawn session containers from)
+3. Start the API, Web, and DB containers
+4. Run Alembic migrations automatically (API entrypoint runs `alembic upgrade head`)
 
 ### Verify
 
@@ -235,17 +219,13 @@ The `docker-compose.prod.yml` has `group_add: ["${DOCKER_GID:-994}"]`. If your s
 docker images | grep claude-runner
 # Should show: claude-runner   latest   <id>   <date>   <size>
 
-docker ps | grep claude-runner
-# Should be empty (it's only spawned on demand, not a long-lived service)
+docker ps -a | grep claude-runner
+# Expected: an "Exited (0)" container from the last compose up — this is
+# normal, the service is declared as build-only (entrypoint /bin/true).
+# The API does NOT use this container — it spawns fresh ones per session.
 ```
 
-If the image is missing, the pre-deployment command did not run or failed. Build it manually:
-
-```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.
+If the image is missing, the compose build step failed. Check Coolify's **Logs** tab for build errors (usually a Dockerfile issue in `infra/docker/claude-runner/`) and redeploy.
 
 ---
 
@@ -308,13 +288,20 @@ The `DOCKER_GID` does not match your server's Docker group. See [step 8](#8-dock
 No such image: claude-runner:latest
 ```
 
-This happens when the pre-deployment command (step 5) did not run or the image was pruned. Build it manually on the host:
+The claude-runner service did not build. Verify `infra/coolify/docker-compose.prod.yml` includes the service block:
 
-```bash
-docker build -t claude-runner:latest /data/coolify/applications/<uuid>/infra/docker/claude-runner/
+```yaml
+claude-runner:
+  build:
+    context: ./infra/docker/claude-runner
+  image: claude-runner:latest
+  entrypoint: ["/bin/true"]
+  restart: "no"
 ```
 
-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`.
+Redeploy via Coolify. Check the deploy logs for errors in the `claude-runner` build step. 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`.
+
+If the image was pruned manually (`docker image prune -a`), just redeploy — Compose rebuilds it as part of the stack.
 
 ### Skills directory is empty
 

docs/self-hosting.md

@@ -169,26 +169,24 @@ POSTGRES_PASSWORD=    # Strong password for production DB
 ### Option A: Docker Compose (simplest)
 
 ```bash
-# 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)
+# Build and start all services. The claude-runner image is built as a side-
+# effect and left available on the host for the API to spawn containers from.
 docker compose -f infra/coolify/docker-compose.prod.yml up -d --build
 
-# 3. Verify services are healthy
+# Verify services are healthy
 docker compose -f infra/coolify/docker-compose.prod.yml ps
 ```
 
-!!! 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.
+!!! note "About the `claude-runner` "Exited" container"
+    The `claude-runner` service is a **build-only service**: `docker compose up`
+    builds the image, starts the container, which exits immediately (its entrypoint
+    is overridden to `/bin/true`) with `restart: "no"`. The container stays in
+    `Exited (0)` state and is not restarted — but the image `claude-runner:latest`
+    remains available on the host. The API spawns new containers from this image
+    per session via the Docker socket.
 
-    Re-run `make build-runner` after editing anything under `infra/docker/claude-runner/`
-    or after a `docker image prune -a`.
+    This pattern keeps `docker compose up --build` as the single source of truth
+    for the whole stack, including the runner image.
 
 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.
 
@@ -220,10 +218,7 @@ 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
+# Start services (the claude-runner image is built as a build-only service)
 docker compose -f infra/coolify/docker-compose.prod.yml up -d --build
 
 # Set up your preferred reverse proxy (Caddy example)
@@ -330,7 +325,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` — if missing, run `make build-runner` (the image is a per-host one-time build, not a Compose service)
+- Verify the claude-runner image exists: `docker images | grep claude-runner` — if missing, run `docker compose up --build` (the image is built as part of the normal compose up)
 - 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,10 +60,18 @@ services:
           memory: 128M
     restart: unless-stopped
 
-  # 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.
+  # Build-only service: the API spawns containers from this image dynamically
+  # via the Docker socket. We still declare it here so `docker compose up --build`
+  # produces the image; `entrypoint: /bin/true` + `restart: "no"` make the
+  # container exit immediately without becoming a long-lived service. The image
+  # `claude-runner:latest` then stays available on the host for the API to use.
+  # Image tag is hard-coded in helprs/modules/container/service.py.
+  claude-runner:
+    build:
+      context: ./infra/docker/claude-runner
+    image: claude-runner:latest
+    entrypoint: ["/bin/true"]
+    restart: "no"
 
   db:
     image: postgres:16-alpine