# permission denied while trying to connect to the docker API
Omarchy 4.0.1 stopped putting your user in the docker group, so plain docker commands now need sudo. How to opt back in, and what the Podman proposal changes.
> **Short answer:** Omarchy 4.0.1 deliberately removed you from the docker group, because that group is passwordless root. Run Docker with sudo (`sudo docker ps`, `sudo docker compose up`). If you want the old behaviour back, run `omarchy setup security sudoless docker` (Setup > Security > Sudoless Docker), accept the warning, and reboot. A logout is not enough.
- Applies to Omarchy: 4.0.1 and later
- Status: by-design
- Last verified: 2026-09-16
- Canonical: https://omarchylinux.org/fix/docker-permission-denied-after-group-change/
_Unofficial community page. Not affiliated with 37signals or the Omacom Foundation. Omarchy is a registered trademark of 37signals LLC._

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:

   ```bash
   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:

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

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

```bash
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:

```bash
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](https://omarchy.org/manual/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](/upgrade/docker-to-podman/) page tracks what has and has not landed.

## Related

- [Migration failed mid update](/fix/migration-failed-mid-update/)
- [omarchy update fails or hangs](/fix/omarchy-update-fails-or-hangs/)
- [The docker group root escalation](/security/docker-group-root-escalation/)
- [Docker to Podman on Omarchy](/upgrade/docker-to-podman/)
- [What migrations do](/upgrade/what-migrations-do/)
- [omarchy-setup-security-sudoless-docker](/reference/commands/omarchy-setup-security-sudoless-docker/)
- [Omarchy 4.0.1 release notes](/releases/v4.0.1/)

## Sources

- [PR #8056: Don't put the user in the docker group; make it opt-in](https://github.com/omacom/omarchy/pull/8056)
- [PR #8098: Offer to reboot when toggling sudoless Docker; show only the relevant menu entry](https://github.com/omacom/omarchy/pull/8098)
- [Issue #9101: Docker migration removes socket access without an apparent sudoless-Docker setup prompt](https://github.com/omacom/omarchy/issues/9101)
- [Discussion #8293: install docker as rootless docker to avoid root elevation](https://github.com/omacom/omarchy/discussions/8293)
- [Discussion #3839: feature request: option to select podman installation instead of docker](https://github.com/omacom/omarchy/discussions/3839)
- [PR #11032: Make Podman native with optional Docker compatibility](https://github.com/omacom/omarchy/pull/11032)
- [PR #11386: Run development containers with rootless Docker](https://github.com/omacom/omarchy/pull/11386)
- [Omarchy v4.0.1 release notes](https://github.com/omacom/omarchy/releases/tag/v4.0.1)
- [Omarchy manual: Development Tools](https://omarchy.org/manual/development-tools/)
- [Omarchy: Any User Process Can Escalate to Root](https://0xcc.io/posts/omarchy-root-creds/)