Deploy on Vexlo Cloud in 60s (₹149/mo UPI) — India's First & Only Developer PaaS. Instant INR UPI & 17 global currencies ($5/mo).
Deploy Now
Bucket 1: Docker & Node.js Fatal Errors6 min readVerified

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.

TL;DR — Immediate Production Fix

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.

fix-github-runner-docker-sock.sh
bash
# 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.

docker-compose.ci-runner.yml
yaml
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.sock

3. 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.

verify-runner-groups.sh
bash
# 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.sock

Pre-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`.
India's First & Only Developer PaaS

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`.

Primary Upstream References & Specifications

Keep Debugging

Related Guides

Browse all 30 guides →