Docker (and Podman) container status in the Omarchy bar — for the local daemon and your remote servers, in one popup.
Every host is a plain Docker context. The local socket is the default
context; a remote server is a context with an ssh:// endpoint. Dockarchy
polls all of them in parallel and shows one section per host, containers
folded under their Compose projects, with CPU and memory per container. Start,
stop, restart, tail logs or open a shell — per container or per project —
search across hosts, and get a desktop notification when something breaks.
Site: https://xninety9.github.io/dockarchy/
- Omarchy 4.x (the Quickshell-based
omarchy-shell). dockerCLI andjqlocally;timeoutandwl-copycome with Omarchy.- Your user must be able to talk to the Docker socket directly. On Omarchy run
omarchy setup security sudoless-docker, then log out and back in. No sudo or pkexec is required: the plugin never elevates privileges. - Optional:
lazydockerfor the terminal buttons on the header, host headers and bar icon. - For remote hosts:
ssh <host>must work non-interactively (keys,~/.ssh/config), and your remote user must be able to rundocker.
omarchy plugin add https://github.com/XNinety9/dockarchy.git --enablePlugins land disabled unless you pass --enable; enable later with
omarchy plugin enable x99.dockarchy. To place it somewhere specific:
omarchy bar move x99.dockarchy --before omarchy.networkManual install works too: copy the folder to
~/.config/omarchy/plugins/x99.dockarchy/, run omarchy-shell shell rescanPlugins,
then omarchy plugin enable x99.dockarchy.
The plugin only reads: it never writes outside its own settings entry, which
Omarchy manages in ~/.config/omarchy/shell.json when you change a setting.
omarchy plugin remove x99.dockarchyThis deletes ~/.config/omarchy/plugins/x99.dockarchy/ and drops the widget
from the bar. Docker contexts you created (docker context ls) and any
~/.ssh/config entries are yours and are left untouched; remove a context with
docker context rm <name> if you no longer want it.
docker context create mainserv --docker "host=ssh://x99@mainserv"
docker --context mainserv ps # one-off sanity checkThat is all — the widget picks the new context up on its next poll. Remove a
host with docker context rm mainserv.
Podman has no contexts, so its hosts are listed in the podmanHosts setting:
local for this machine, user@host or user@host:port for podman over
ssh (your ~/.ssh/config applies). They show up as hosts named podman and
podman@host, with the same rows, stats, actions and update checks — the
collector runs podman ps/stats --format json on the host and reshapes it,
and actions use podman (locally or through ssh). podman compose is used
for project actions; lazydocker is docker-only and hidden for podman hosts.
omarchy bar set x99.dockarchy podmanHosts "local,me@podbox"docker --context ssh://… opens one SSH session per API call. That is
fine for a single docker ps, but docker stats opens one session per
container, in parallel — enough to exceed sshd's MaxSessions, look like a
brute-force attempt, and get your IP banned by fail2ban.
Dockarchy therefore never polls through docker --context. Each poll runs a
single ssh <host> bash -s that executes docker ps and docker stats on
the server and streams one result back. Add connection multiplexing to
~/.ssh/config so even that one session is reused between polls:
Host mainserv
ControlMaster auto
ControlPath ~/.ssh/sockets/%r@%h-%p
ControlPersist 10m
BatchMode yes
(mkdir -m 700 ~/.ssh/sockets once.) One-shot actions — start, stop, restart,
logs, shell — still go through docker --context, which is a single request.
| Button | Action |
|---|---|
| Left | Open / close the panel |
| Right | Open lazydocker (default context) |
| Middle | Refresh now |
| Target | Mouse |
|---|---|
| Header | Search · refresh · lazydocker buttons |
| Host row | Click to fold/unfold the host · eye button hides/shows its stopped containers · lazydocker |
| Project row | Click to fold/unfold · buttons: project logs · restart · start/stop all |
| Container row | Buttons: logs · shell · restart · start/stop · middle-click copies the name · right-click opens the menu |
| Update badge | An accent-coloured arrow after the name means a newer image exists in the registry; click it to pull (and recreate, for Compose containers) |
| Port chip | 8080→80 under the name: click opens http://<host>:8080 in your browser |
| Stats column | One line per chosen metric (CPU, memory, network, disk, PIDs) with a sparkline over the last polls; hover for details and min/avg/max over the window |
The context menu (right-click or m) gathers everything for one container:
open each published port, logs, shell, inspect (docker inspect | less),
restart, start/stop, copy name or ID, and Kill… / Remove… behind a
confirmation.
| Key | On a container | On a project row | On a host row |
|---|---|---|---|
j / k |
Move (across projects and hosts) | Move | Move |
⏎ |
Start / stop | Fold / unfold | Fold / unfold the host |
u / d |
Start / stop | Start / stop every container | — |
r |
Restart | Restart the running ones | — |
l / → |
Tail logs in a terminal | docker compose logs -f |
— |
s |
Shell (bash, falling back to sh) |
— | — |
i |
Inspect | — | — |
o |
Open the first published port | — | — |
p |
Pull the newer image (and recreate, if Compose) | Pull & recreate the whole project | — |
U |
Check registries for newer images now | same | same |
m |
Context menu | — | — |
x |
Kill (running) / remove (stopped), after confirming | — | — |
c |
Copy the container name | — | — |
h |
Hide / show stopped containers of this host | same | same |
z |
Fold / unfold every project | same | same |
t |
Cycle sort: State → Name → CPU → Memory | same | same |
/ |
Search | Search | Search |
R |
Refresh | Refresh | Refresh |
L |
lazydocker for the selected host | same | same |
Esc |
Close | Close | Close |
Folded hosts and projects, hidden-stopped hosts and the sort order are remembered in the widget's settings entry.
Search (/): every word you type must match somewhere in the name, image,
project, service, state or status line — unhealthy lists the sick ones on
every host, nginx blog narrows to a project. ↑/↓ move the cursor while
typing, ⏎ returns to the list, Esc clears. Hosts without a match are hidden.
The shortcut reminder at the bottom of the panel is always visible and follows
the selected row. Logs and shells open through omarchy-launch-tui, so they
use your default terminal; on remote hosts they run over your own ssh config.
Dockarchy compares each poll with the previous one and sends a desktop notification when:
- a container turns unhealthy or stops on its own — never for a stop, restart or start you asked for from the panel or its IPC;
- a host stops answering.
Set notifications to Problems and recoveries to also hear when a container
is healthy or running again, or a host is back. Health flaps are debounced
(2 min per container), stops 20 s. Off disables it.
The icon is the Nerd Font whale with an alert or check badge, rendered by
assets/render-icons (ImageMagick) into ~/.cache/dockarchy/ in your current
theme's colours when the shell starts and whenever the theme changes. Without
ImageMagick the pre-rendered PNGs in assets/ are used instead. Any Nerd Font
works; set DOCKARCHY_ICON_FONT to force one.
Every updateCheckHours (default 6) Dockarchy compares the digest of each
running container's image with what its registry currently serves for that
tag — one anonymous HEAD /v2/<repo>/manifests/<tag> per distinct image, run
on the host that owns the container (so the server's network, DNS and
mirrors apply). Results are cached in ~/.cache/dockarchy/updates.json; U
forces a check. Containers whose image is newer in the registry get a badge,
their project row gets a pull button, and the panel summary and {updates}
bar placeholder count them.
Pulling runs in a terminal so you see the progress: for Compose containers it
is cd <project dir> && docker compose pull <service> && docker compose up -d <service> (the whole project from the project row); standalone containers are
only pulled, since recreating them needs their original docker run flags.
Images built locally or pulled by digest cannot be compared and are skipped.
Docker Hub, ghcr.io, lscr.io, quay.io and any registry using the standard
token flow work; private images needing credentials show as unknown.
Running containers use the theme's text colour; stopped ones are dimmed. Unhealthy, restarting or dead containers, unreachable hosts, CPU or memory above 80 %, and the bar icon when anything needs attention, use a softened warning tint (the theme's text colour blended with its urgent colour) rather than a full red. Textual error messages stay in the theme's urgent colour.
Settings live in the widget's entry in ~/.config/omarchy/shell.json
(under bar.layout.<section>, the object with "id": "x99.dockarchy"). Edit
them there, in the shell's settings UI, or with
omarchy bar set x99.dockarchy <key> <value> — every change applies live.
| Key | Default | Meaning |
|---|---|---|
contexts |
(all) | Docker contexts to monitor. The settings UI offers a picker; omarchy bar set takes ctx1,ctx2. |
podmanHosts |
(none) | Podman hosts: local and/or user@host[:port], comma-separated. |
refreshIntervalSec |
15 |
Poll interval, 5–3600 s. |
timeoutSec |
10 |
Per-host limit before it is marked unreachable. |
showAll |
true |
Include stopped containers (docker ps -a). |
showStats |
true |
CPU % and memory per running container (docker stats, about a second extra per poll). |
showSparklines |
true |
Trend lines next to the stats. CPU is scaled to 100 %, the others to their own peak. |
sparkMetrics |
CPU,Memory |
Which metrics to show, one line each: CPU, Memory, Network, Disk, PIDs. Network and disk are bytes/s between two polls. |
sparkSamples |
20 |
Polls a sparkline spans (5–240). Window = this × refreshIntervalSec, shown in the tooltip. |
groupByProject |
true |
Fold containers under their Compose project with project-level actions. |
sortBy |
State |
State (running first, then name), Name, CPU or Memory (hungriest first). t cycles it. |
collapsedHosts, collapsedGroups, hideStoppedHosts |
(empty) | Comma-separated lists written by the panel itself as you fold or hide things. |
notifications |
Problems |
Off, Problems, or Problems and recoveries — see Notifications above. |
updateCheckHours |
6 |
Hours between registry checks for newer images; 0 disables. |
barFormat |
{running} |
Label next to the whale (see below). Empty = icon only. |
panelWidth |
700 |
Popup width in px (300–1400). |
panelMaxHeight |
800 |
The popup grows with its content up to this, then scrolls. |
alternateRows |
false |
Shade every other container row. |
runningAccent |
false |
Tint running containers with the theme's accent colour instead of the text colour. |
barFormat is a Python-style format string:
| Placeholder | Value |
|---|---|
{running} |
Running containers (aliases {alive}, {up}) |
{stopped} |
Not running (aliases {down}, {exited}) |
{total} |
All containers |
{unhealthy} |
Unhealthy, restarting or dead |
{unreachable} |
Hosts that did not answer |
{errors} |
{unhealthy} + {unreachable} |
{hosts} |
Hosts polled |
{updates} |
Containers whose image has a newer version |
Unknown names are left in place so a typo is visible; {{ and }} give
literal braces.
omarchy bar set x99.dockarchy barFormat '{running}/{total}'
omarchy bar set x99.dockarchy barFormat '{running} up · {errors} err'
omarchy bar set x99.dockarchy barFormat '' # icon onlyomarchy-shell x99.dockarchy toggle | open | close | refresh
omarchy-shell x99.dockarchy status # "27 running · 1 stopped · 1 unhealthy · 2 hosts"
omarchy-shell x99.dockarchy running # "27"
omarchy-shell x99.dockarchy action <context> <name|id> <start|stop|restart|pause|unpause|kill|rm>
omarchy-shell x99.dockarchy project <context> <project> <start|stop|restart>
omarchy-shell x99.dockarchy search <text> # open the panel with a filter
omarchy-shell x99.dockarchy sort <State|Name|CPU|Memory|next>
omarchy-shell x99.dockarchy version
omarchy-shell x99.dockarchy settings # resolved settings, for debugging
omarchy-shell x99.dockarchy rows # what the panel currently lists, for debugging
omarchy-shell x99.dockarchy history <context> <name|id> # the sparkline series
omarchy-shell x99.dockarchy checkUpdates # registry check now
omarchy-shell x99.dockarchy updates # images with a newer versionAdd a Docker submenu (panel, search, refresh, sort, lazydocker) to the Omarchy menu with:
~/.config/omarchy/plugins/x99.dockarchy/bin/dockarchy-menu install # or: removeIt appends a marked block to ~/.config/omarchy/extensions/omarchy-menu.jsonc
(backup kept next to it) and is only ever run by you. The menu reloads on save.
Handy for a Hyprland keybinding in ~/.config/hypr/bindings.lua:
o.bind("SUPER + SHIFT + D", "Docker containers", "omarchy-shell x99.dockarchy toggle")manifest.json plugin id, defaults and settings schema
Panel.qml bar button + popup: rows, cursor, keys, footer
Service.qml polling, actions, timers, watchdog
Model.js pure JS parsing, filtering, grouping, diffing — testable with node
assets/ render-icons (glyphs -> PNG) and fallback renders
test/ node --test suites and the stub docker/ssh they run against
bin/dockarchy-status queries every context in parallel (one ssh session per
remote host) and prints a single JSON document
bin/dockarchy-contexts lists context names for the settings picker
bin/dockarchy-menu adds/removes the Docker submenu in the Omarchy menu
bin/dockarchy-updates compares image digests with their registries (on each host)
bin/dockarchy-exec runs every spawned process with stdout/stderr byte ceilings
bin/dockarchy-status --all --stats --timeout 5 [ctx ...] | jq . shows exactly
what the widget sees.
node --test # or: npm testtest/model.test.mjs covers the pure logic in Model.js; test/status.test.mjs
runs the collector against a stub docker and ssh in test/stub/, so the
parallel query, ssh dispatch, stats merge, error and timeout paths are checked
without a daemon. CI runs the same plus shell syntax, manifest and icon checks.
docs/demo/compose.yml starts seven throwaway
containers covering every state the widget renders — healthy, running,
unhealthy and exited — grouped under the compose project demo;
docs/demo/monitoring.yml adds a second project:
docker compose -f docs/demo/compose.yml up -d
docker compose -f docs/demo/monitoring.yml up -d
docker compose -f docs/demo/compose.yml down && docker compose -f docs/demo/monitoring.yml downSettings changes apply live. For QML/JS changes the shell's file watcher does
recreate the widget, but Qt keeps serving the previously compiled type, so run
omarchy restart shell to pick code changes up. Follow the shell's log with
journalctl --user -f -o cat | grep -i dockarchy.
- 0.8.2 — hardening pass, see SECURITY.md: every spawned
process runs under
bin/dockarchy-execwith stdout/stderr ceilings; notification text is markup-escaped; clipboard copies avoid the shell; registry token realms must be https and responses are capped; pull & recreate shows the exact command and directory before running; fixed a recursive layout warning on container rows. - 0.8.1 — fix container names and images being elided with room to spare;
fix
{updates}in the bar label always reading 0; new screenshots and the project site. - 0.8.0 — Podman hosts (
podmanHosts: local or over ssh) alongside Docker contexts, with the same rows, stats, actions and update checks. - 0.7.0 — image update detection by registry digest, with a badge per
container, pull & recreate for Compose services and projects,
{updates}in the bar label. - 0.6.0 —
dockarchy-menuadds a Docker submenu to the Omarchy menu; notification icons are now Nerd Font glyphs rendered in the theme's colours; sparklines per running container for a chosen set of metrics (CPU, memory, network and disk throughput, PIDs) over a configurable number of polls, with min/avg/max in the tooltip; optional accent tint for running containers. - 0.5.0 — clickable port chips and
o; right-click /mcontext menu with inspect, copy ID, kill and remove behind a confirmation (x); host rows fold and can hide their stopped containers (h), remembered across restarts; sort by state, name, CPU or memory (t). - 0.4.0 — search across hosts (
/); containers grouped by Compose project with fold and project-wide start/stop/restart/logs; desktop notifications on unhealthy, unexpected stop or unreachable host, with recoveries optional; test suite and CI. - 0.3.0 — sticky shortcut footer; configurable panel size, bar label template and alternating row shading.
- 0.2.0 — CPU/memory per container;
lopens logs; softer warning colour; remote polling switched to a single SSH session per host. - 0.1.0 — first release: multi-context status, start/stop/restart, logs, shell, keyboard navigation.
See SECURITY.md for the trust boundaries, the byte and time limits applied to every host, and what the plugin never does.
WTFPL — do what you want with it.