Skip to Content
TroubleshootingDocker Socket Denied

Docker Socket Denied

Symptom

ERROR  diagnostics_fail code=docker_socket_denied detail=permission denied while
       trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

The container starts, registration may succeed, but session.create jobs fail because the agent cannot list / pull / launch containers on the host.

Likely cause

The agent runs in a Docker container and reaches the host daemon via the bind-mounted socket at /var/run/docker.sock. The socket file is owned by root:docker and uses the host’s docker group GID. The agent container either:

  1. Wasn’t given the socket — the -v /var/run/docker.sock:/var/run/docker.sock flag is missing.
  2. Runs as a non-root user without the docker group — possible if you built a custom image overriding the upstream user.
  3. (macOS / WSL) Docker Desktop’s resource integration is off, so the socket inside WSL doesn’t exist.

Fix

Linux

Make sure the install command includes the socket mount:

docker run -d \
  --name cm-runner \
  -v /var/run/docker.sock:/var/run/docker.sock \   # <-- required
  ...
  ghcr.io/curate-me-ai/cm-runner:latest

If you’ve customized the image and switched to a non-root user, add the user to the docker group at build time:

RUN groupadd -g 999 docker && usermod -aG docker cmrunner

(The GID 999 is the typical value on Debian/Ubuntu. Match it to your host’s getent group docker output.)

macOS (Docker Desktop)

The socket lives at /var/run/docker.sock on the Docker Desktop VM, not the host filesystem. The default install command works as-is — confirm with:

docker exec cm-runner ls -la /var/run/docker.sock

If the file is missing, restart Docker Desktop.

Windows / WSL

  1. Open Docker Desktop → Settings → Resources → WSL Integration.
  2. Enable integration for the distribution you launched the agent from.
  3. Restart the WSL distribution (wsl --shutdown from PowerShell) and re-run the install command.

Don’t run the agent as --privileged. It doesn’t fix this error and expands the blast radius if the agent is compromised. The socket mount is the only Docker-related permission the agent needs.

Verify the fix

docker exec cm-runner docker info --format '{{.ServerVersion}}'

Expected: a Docker version string (e.g. 27.5.1). If you still get permission denied, the agent process inside the container can’t read the mounted socket — double-check the user/group mapping in your custom image.

Where to find logs

docker logs cm-runner --tail 100 | grep -E "docker|socket|permission"

Server-side: this surfaces in the dashboard machine card as Diagnostics: docker socket denied.

TroubleshootingImage Pull Failed