Fixing unix:///var/run/docker.sock Permission Denied on Self-Hosted CI Runners
Fix 'Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock' on Ubuntu VPS and self-hosted GitHub Actions runners without chmod 666.
The error `Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock` occurs because the Unix domain socket `/var/run/docker.sock` is owned by `root:docker` with `0660` (`srw-rw----`) permissions, and the Linux user executing your command (e.g., `runner`, `github`, or `ubuntu`) either does not belong to the `docker` group OR its long-running background systemd service (`actions.runner.*.service`) was started before the group membership was added and still holds an outdated Linux process credential (`gid`) list. Fix it by adding the user to the `docker` group (`sudo usermod -aG docker $USER`) AND restarting the systemd runner daemon so the process reloads supplementary groups.
Verified Root Causes in Production Environments
- Missing Supplementary Group Membership (`docker`): Non-root users cannot write to `/var/run/docker.sock` (`root:docker 0660`) unless their UID is in `/etc/group` under `docker`.
- Unrestarted Systemd GitHub Actions Runner Daemon: Running `sudo usermod -aG docker runner` modifies `/etc/group` on disk, but an already-running `Runner.Listener` daemon retains the kernel group credentials from when it booted until `sudo ./svc.sh stop && sudo ./svc.sh start` is executed.
- Unmapped Host Socket GID in Containerized Runners (DinD / DooD): When running a self-hosted runner inside a Docker container with `-v /var/run/docker.sock:/var/run/docker.sock`, the GID of the `docker` group on the host (e.g., `998`) does not match the GID inside the container.
1. Fix Host User & Self-Hosted GitHub Actions Systemd Service Permissions
When you install Docker Engine on Ubuntu 22.04 or 24.04 LTS, the daemon creates `/var/run/docker.sock` with owner `root` and group `docker` (`srw-rw----`). Many developers run `sudo usermod -aG docker github-runner` and wonder why their next GitHub Actions workflow run STILL fails with `permission denied while trying to connect to the Docker daemon socket`.
In Linux, supplementary group memberships (`setgroups()`) are inherited at login or service startup time. A background systemd service like `actions.runner.<org>-<repo>.<hostname>.service` never logs out, so it never picks up `/etc/group` edits until you explicitly stop and start the service unit.
# 1. Verify the exact owner, group, and numeric GID of /var/run/docker.sock
ls -ln /var/run/docker.sock
ls -l /var/run/docker.sock
# Expected: srw-rw---- 1 root docker 0 Nov 17 10:00 /var/run/docker.sock
# 2. Add your CI runner user (e.g. 'runner' or 'ubuntu') to the 'docker' group
sudo groupadd -f docker
sudo usermod -aG docker runner
# 3. CRITICAL: Restart the GitHub Actions systemd service so it reloads /etc/group!
cd /home/runner/actions-runner
sudo ./svc.sh stop
sudo ./svc.sh start
sudo ./svc.sh status
# (If fixing an interactive SSH session instead of a daemon, run: newgrp docker)2. Fix Containerized Runners (Docker-Outside-of-Docker) via Group GID Mapping
If your self-hosted GitHub Actions runner or Jenkins agent itself runs inside a Docker container and mounts the host socket (`-v /var/run/docker.sock:/var/run/docker.sock`), adding the container's `runner` user to the container's `docker` group often still fails with `permission denied`.
Why? Because the Linux kernel checks numeric Group IDs (GIDs), not group names. If the `docker` group on your Ubuntu host has GID `998`, but inside your runner container the `docker` group has GID `1001`, the kernel denies access. Pass `--group-add $(stat -c '%g' /var/run/docker.sock)` (or `group_add` in `docker-compose.yml`) so the container process inherits the exact numeric GID of the host socket.
services:
github-runner:
image: myoung34/github-runner:latest
restart: unless-stopped
environment:
REPO_URL: https://github.com/your-org/your-repo
RUNNER_NAME: vexlo-mumbai-runner-01
ACCESS_TOKEN: ${GH_RUNNER_PAT}
RUNNER_WORKDIR: /tmp/runner/work
# Inject the host's exact numeric docker.sock GID (find via: stat -c '%g' /var/run/docker.sock)
group_add:
- "${DOCKER_GID:-998}"
volumes:
- /var/run/docker.sock:/var/run/docker.sock3. Why You Must Never Run chmod 666 /var/run/docker.sock in Production
Countless forum comments suggest running `sudo chmod 666 /var/run/docker.sock` as a quick fix. Never do this on a production or multi-service server: `/var/run/docker.sock` is root-equivalent. Making it world-writable (`0666`) allows any compromised unprivileged container or web process (`www-data`, `nobody`) with access to the path to mount the host `/` filesystem and gain instant root control. Additionally, `systemd` recreates `/var/run/docker.sock` with `0660` whenever `docker.socket` restarts, breaking the `chmod 666` workaround on reboot.
# Inspect the live supplementary GIDs of a running GitHub Actions Runner process
RUNNER_PID=$(pgrep -f "Runner.Listener" | head -n 1)
grep "^Groups:" /proc/${RUNNER_PID}/status
# Compare against the numeric GID of /var/run/docker.sock
stat -c "Socket GID: %g (%G)" /var/run/docker.sockPre-Deployment Verification Checklist
- Run `sudo usermod -aG docker <runner_user>` on the host machine.
- Restart the runner systemd service (`sudo ./svc.sh stop && sudo ./svc.sh start`) so `/proc/<pid>/status` includes the `docker` GID.
- For containerized runners mounting `/var/run/docker.sock`, pass `group_add: ["<host_docker_gid>"]` matching `stat -c '%g' /var/run/docker.sock`.
- Revert any insecure `chmod 666 /var/run/docker.sock` permissions back to `sudo chmod 660 /var/run/docker.sock`.
Deploy on Vexlo Cloud in 60s (₹149/mo UPI)
Automated Docker & Nixpacks builds, managed PostgreSQL/Redis, and AI Deployment Doctor. Instant INR UPI for India or USD/EUR/GBP across 17 global currencies.
Frequently Asked Questions
Why do I still get permission denied after running sudo usermod -aG docker $USER?
Linux only reads `/etc/group` when creating a new login session. In an interactive SSH terminal, run `newgrp docker` or log out and back in. For a background service like GitHub Actions Runner, restart the systemd service via `sudo ./svc.sh stop && sudo ./svc.sh start`.
Why did chmod 666 /var/run/docker.sock stop working after my Ubuntu server rebooted?
The `/var/run` directory resides on a `tmpfs` RAM disk, and the `docker.socket` systemd unit (`SocketMode=0660`) resets `/var/run/docker.sock` permissions to `0660` every time Docker restarts.
How do I find the numeric GID of /var/run/docker.sock on Linux?
Run `stat -c '%g' /var/run/docker.sock` in your terminal. It will output a number such as `998` or `999`, which you can pass to `--group-add`.