Buildkite "permission denied ... docker.sock" on the agent in CI

By Kaveh Alemi·Latchkey

A Docker step on a self-hosted agent connects to the daemon through /var/run/docker.sock. If the agent user is not in the docker group (or the socket is not mounted), Docker returns permission denied.

What this error means

A docker or docker-compose step fails with "permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock".

permission denied while trying to connect to the Docker daemon socket
at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/v1.45/version":
dial unix /var/run/docker.sock: connect: permission denied

Common causes

The agent user is not in the docker group

On a self-hosted agent, the user running buildkite-agent lacks membership in the docker group, so it cannot open the daemon socket.

The socket is not available inside the agent container

When the agent itself runs in a container, /var/run/docker.sock is not mounted, so Docker-in-the-step has no daemon to reach.

How to fix it

Grant the agent user Docker access

1. Add the agent user to the docker group on the host.
2. Restart the agent so the new group membership takes effect.
3. Re-run a Docker step to confirm access.

sudo usermod -aG docker buildkite-agent
sudo systemctl restart buildkite-agent

Mount the socket into a containerized agent

If the agent runs in a container, bind-mount the host Docker socket so steps can reach the daemon.

docker run -v /var/run/docker.sock:/var/run/docker.sock \
  buildkite/agent:3

How to prevent it

• Provision self-hosted agents with the agent user already in the docker group.
• Mount the Docker socket when running the agent in a container.
• Bake Docker access into the agent image so every host is consistent.

Frequently asked questions

Related guides

References

• GitHub Actions documentation