permission denied while trying to connect to the docker API

Docker still works. You just lost the shortcut that let you talk to it without a password. Omarchy 4.0.1 stopped putting your user in the docker group, and the update migration took existing users out of it. The daemon is running, the socket is there, and your containers are intact. Your user account simply cannot write to /var/run/docker.sock any more.

Everything below was checked against the v4.0.0 through v4.0.4 source trees and the v3.8.4 tree.

The fix

First confirm this is the group change and not a dead daemon.

1. Check the socket unit:

   systemctl is-active docker.socket

   It should say active. Omarchy still enables docker.socket at install time in every 4.x release.

2. Check the socket ownership and your groups:

   stat -c '%U %G %a %n' /var/run/docker.sock
   id -nG

   You will see root docker 660 /var/run/docker.sock and a group list with no docker in it. That combination is the whole problem.

3. Pick one of the two supported paths.

Path A, the default. Use sudo.

sudo docker ps
sudo docker compose up -d

This is what the manual tells you to do, and it needs no configuration. The d alias that Omarchy ships in ~/.local/share/omarchy/default/bash/aliases is a plain alias for docker, so d ps fails the same way. Type sudo docker or write your own sd alias.

Path B, opt back in, knowingly.

omarchy setup security sudoless docker

Or use the menu: Super + Space, then Setup > Security > Sudoless Docker. The script prints a warning explaining that the group is equivalent to passwordless root, asks you to confirm, runs sudo usermod -aG docker "$USER", records a reboot-required flag, and offers to reboot right away. Say yes. The change does not take effect until you do.

To go the other way later, the menu entry moves to Remove > Security > Sudoless Docker, or run omarchy remove security sudoless docker. Only one of the two entries is ever shown, which is what PR #8098 added.

On 3.x there is nothing to do. Omarchy 3.8.4 ran sudo usermod -aG docker ${USER} during install, and 4.0.0 still added the install user to the group in install/config/docker.sh. If you are still on 3.x, plain docker works and this page does not apply to you until you upgrade.

Verify it worked

If you chose sudo, sudo docker ps returning a table is the whole test.

If you opted into sudoless Docker and rebooted:

id -nG | tr ' ' '\n' | grep -x docker
docker ps
omarchy-sudo-docker; echo $?

omarchy-sudo-docker is Omarchy’s own answer to “does Docker need sudo right now”. It exits 0 when sudo is still needed and 1 when the socket is directly writable, so 1 is what you want. Add --configured and it answers for the account rather than this session, which is how it reports the window between enabling the group and the reboot that applies it.

The Docker TUI on Super + Shift + D is the other check. By default it opens behind a polkit prompt, because omarchy-launch-docker-tui runs lazydocker through pkexec whenever the socket is not writable. Once sudoless Docker is on and you have rebooted, it opens with no prompt at all.

Why it happens

Membership in the docker group is not a convenience, it is root. The daemon runs as root and owns the socket, so any process that can write to the socket can start a container with / bind-mounted inside it and edit any file on the host as root. You already have sudo, so on paper nothing new is granted. The difference is that sudo asks for a password and the socket does not, which means every script, editor extension, npm postinstall hook, or Omarchy plugin that runs as your user quietly inherits root. That is the reason Omarchy’s own setup script prints a warning before it adds you.

PR #8056 merged on 2026-08-24 and shipped in v4.0.1 on 2026-08-25, listed in the release notes under Security. The install no longer grants the group, first-boot provisioning refuses to replay it even if an older snapshot recorded it, and the Quattro upgrade path no longer adds it. Migration 1787580187.sh removes existing users from the group during omarchy update and refreshes the Docker launcher entry. A public write-up of the old default appeared on 0xcc.io on 2026-08-28, three days after the fix shipped.

The confusing part is the timing. The migration takes the group away immediately, but group membership is only read when a session is created, so the running session keeps working and the failure appears after the next reboot. Nothing on screen connects the two events. Issue #9101, filed from the dev branch, shows the resulting state: docker.socket active, the socket at root docker 660, and id with no docker in it. mattrayner had already found the migration and PR #8056 and was asking whether the update should have prompted him; he closed the issue himself fifteen minutes later, without a reply from anyone.

Omarchy’s own manual chapter on development tools documents the new default, including the sudo docker ps examples.

If that did not work

Still denied after enabling sudoless Docker. You did not reboot. The toggle scripts are explicit that a logout or newgrp is not reliably enough on Omarchy, which is why they set a reboot-required flag and prompt. Reboot and try again.

Registry logins stopped working. docker login writes credentials to $HOME/.docker/config.json. Under sudo docker you are reading root’s config instead, so you will be asked to log in again. Run sudo docker login once, or opt into the group.

Scripts and CI helpers that call bare docker. Anything that shells out to docker without sudo now fails, including some project task runners and agent tooling. Either edit the caller or opt in.

The Docker TUI prompt fails. That is a polkit problem, not a group problem. The same prompt is used by several Omarchy actions.

You want rootless containers instead. Omarchy does not ship them. Rootless Docker was requested in discussion #8293, and a Podman option was requested back in discussion #3839, which now has fifteen upvotes. PR #11032 by acrogenesis, opened 2026-09-09, proposes making Podman native with optional Docker compatibility, Quadlet user services for the development databases, and a container transfer path. Its two approving reviews come from an automated reviewer, a maintainer review found two migration bugs that the author then fixed, and the branch currently reports merge conflicts against quattro. The same author opened PR #11386 on 2026-09-11 with the other option, rootless Docker for the development containers. Both are open and unmerged as of 2026-09-16, and there is no podman anywhere in the v4.0.4 source tree. Treat them as proposals, not a plan you can wait for. The Docker to Podman page tracks what has and has not landed.

Related

• Migration failed mid update
• omarchy update fails or hangs
• The docker group root escalation
• Docker to Podman on Omarchy
• What migrations do
• omarchy-setup-security-sudoless-docker
• Omarchy 4.0.1 release notes