fix(docker): let the agent sandbox reach the Docker daemon (#1460)

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: FelixTJDietrich

.changeset/agent-sandbox-reaches-docker.md

@@ -0,0 +1,7 @@
+---
+"hephaestus": minor
+---
+
+Practice reviews can now actually start. The application server and worker run unprivileged, so every attempt to launch an agent sandbox was refused by the Docker socket with a permission error and no review ever ran. They now join the host's Docker group.
+
+**Operators:** set `DOCKER_GROUP_ID` to the group id that owns `/var/run/docker.sock` on your host — `getent group docker | cut -d: -f3` prints it. There is no portable default, so a deployment that leaves it unset keeps failing the same way it does today.

docker/.env.example

@@ -238,6 +238,13 @@ GITLAB_WORKSPACE_CREATION=false
 # GIT_CHECKOUT_ENABLED enabled together. The agent job queue runs on PostgreSQL, not NATS —
 # NATS_ENABLED below is unrelated to practice review; it only gates webhook-driven sync ingest.
 
+# Supplementary group the application server and worker join so they can reach the Docker socket
+# the agent sandbox runs containers through. The image runs unprivileged and the socket is
+# root:docker 0660, so without this every sandbox start fails with "permission denied" and no
+# practice review can run. There is no portable default — read the host's group id with
+# `getent group docker | cut -d: -f3`.
+# DOCKER_GROUP_ID=999
+
 # Docker daemon endpoint (default: local socket)
 # SANDBOX_DOCKER_HOST=unix:///var/run/docker.sock
 

docker/compose.app.yaml

@@ -275,6 +275,12 @@ services:
       release-pin-fetcher:
         condition: service_completed_successfully
     restart: unless-stopped
+    # The image runs unprivileged (the buildpack's `cnb` user) while /var/run/docker.sock is
+    # root:docker 0660, so the sandbox runtime cannot reach the daemon without joining the host's
+    # docker group. There is no portable value: read the host's with
+    # `getent group docker | cut -d: -f3` and set DOCKER_GROUP_ID to it.
+    group_add:
+      - "${DOCKER_GROUP_ID:-999}"
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock
       - git-repos:/data/git-repos
@@ -404,6 +410,12 @@ services:
       release-pin-fetcher:
         condition: service_completed_successfully
     restart: unless-stopped
+    # The image runs unprivileged (the buildpack's `cnb` user) while /var/run/docker.sock is
+    # root:docker 0660, so the sandbox runtime cannot reach the daemon without joining the host's
+    # docker group. There is no portable value: read the host's with
+    # `getent group docker | cut -d: -f3` and set DOCKER_GROUP_ID to it.
+    group_add:
+      - "${DOCKER_GROUP_ID:-999}"
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock
       - git-repos:/data/git-repos

docker/preview/.env.example

@@ -110,3 +110,10 @@ TANSTACK_DEVTOOLS_ENABLED=true
 # rollout testing are supported. Enable one workspace's review model binding and trigger in the UI.
 
 # HEPHAESTUS_AGENT_IMAGE_REFERENCE=ghcr.io/ls1intum/hephaestus/agent-pi@sha256:<digest>  # preview override only
+
+# Supplementary group the application server and worker join so they can reach the Docker socket
+# the agent sandbox runs containers through. The image runs unprivileged and the socket is
+# root:docker 0660, so without this every sandbox start fails with "permission denied" and no
+# practice review can run. There is no portable default — read the host's group id with
+# `getent group docker | cut -d: -f3`.
+# DOCKER_GROUP_ID=999

docker/preview/compose.app.yaml

@@ -347,6 +347,12 @@ services:
       WEBHOOK_EXTERNAL_URL: ${WEBHOOK_EXTERNAL_URL:-https://staging.hephaestus.aet.cit.tum.de}
       THC_PORT: "8080"
       THC_PATH: /actuator/health/liveness
+    # The image runs unprivileged (the buildpack's `cnb` user) while /var/run/docker.sock is
+    # root:docker 0660, so the sandbox runtime cannot reach the daemon without joining the host's
+    # docker group. There is no portable value: read the host's with
+    # `getent group docker | cut -d: -f3` and set DOCKER_GROUP_ID to it.
+    group_add:
+      - "${DOCKER_GROUP_ID:-999}"
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock
       - git-repos:/data/git-repos