Docker

Alt-C or Command → Docker lists your containers in the active panel, grouped by Compose project, with containers that are not part of a project at the end. The other panel shows the selected container: its status, ports, networks, mounts, command, and restart policy, plus live CPU, memory, network, and disk use with a chart of the last minute. For a project, it shows the project’s folder, its containers, and their combined use. Esc closes the view and keeps its filter for the next time.

CPU shows as two figures. Now % is the latest reading, and Avg % is the average of the last few seconds, as in the activity monitor, so it holds steady while a container works in bursts. A list too narrow for both shows Avg % alone. The details show the same pair as CPU now and CPU avg, and a project adds up both over its running containers.

Key	Action
↑ ↓, PgUp, PgDn, Home, End	Move
← → / Enter	Fold or unfold a project; Enter on a container moves to its details
S / X / R	Start / stop / restart the container, or the project’s containers
P	Pause or resume
F	Browse the container’s files
E, Alt-2	Open a shell in the container, or go back to its open shell
Alt-1	Show the container’s overview again, also from inside its shell
D	Show disk use, or the containers again
/	Filter by name, service, image or project
Alt-O	Open the folder of the Compose file beside the list
Tab	Switch between the list and the details
Alt-W	Maximize the focused pane

Stop and restart ask for confirmation first. On a project, an action only affects the containers it would change, so Start starts only the stopped ones.

Alt-O opens the folder of the Compose file that started the container or project in the other panel, with the cursor on the file, or the project’s folder when Compose names no file. The list stays as it was, as in the activity monitor (see Activity and memory). A container that Compose did not start has no folder on this computer, so Alt-O says so, and F browses its files instead.

Container files

F on a running container closes the Docker view and shows the container’s file system in that panel, starting in its working directory. The panel title shows the container’s name. The other panel stays on your host folder, so F5 copies in either direction, while F3 views, F7 creates a folder, and F8 deletes inside the container. Search, sizes, previews, and editing only work on the host. Alt-C goes back to the Docker view, and .. at the container’s root returns the panel to the host folder it showed before. Browsing needs sh in the container, so minimal images without a shell cannot be listed.

While a panel shows a container’s files, the command line follows it: it becomes that container’s shell, started in the panel’s folder, with the container’s name at the start of the prompt. Commands run inside the container, the panel refreshes when they finish, and cd there moves the panel. Ctrl-O shows that container’s console, marked ▣ name console. On a host panel, the command line and Ctrl-O belong to the host again, and whatever you had typed there is still there. This is the same shell as the container’s Shell tab in the Docker view.

To keep the command line on the host, turn off Follow in Options → Plugins. Then, while a panel shows a container’s files, the command line is dimmed and marked ⌂ host, and Enter does nothing until a host panel is active, so a command never runs on the wrong machine.

Container shells

E opens a shell in the container (bash if the image has it, otherwise sh) on the Shell tab of the details panel, and sends your keys to it, function keys included. Alt-1 shows the overview, Alt-C returns to the list, and the mouse wheel scrolls back through the shell’s output. A shell keeps running while you look at other containers, close the Docker view, or use the host console; its container is marked ›_ in the list and counted on the Alt-C shortcut. The shell closes when you exit it, when its container stops, or when Borg quits (Borg asks first while shells are open).

The plugin uses the docker CLI and its current context, so it works with Docker Desktop, OrbStack, Colima, and remote engines alike. You can turn it off in Options → Plugins.

Disk use and cleanup

D in the Docker view, or F9 → Docker → Disk use, shows what Docker keeps on disk in place of the container list, one row per kind: Build cache, Dangling images, Unused images, Images in use, Stopped containers, Unused anonymous volumes, Unused named volumes, Volumes in use, and Unused networks. Each row has a count, a size, and what removing it frees, and the top line adds up everything you can reclaim. Borg measures with docker system df --verbose in the background, which can take a while on a busy engine. R measures again, and Borg does the same when the next command at the prompt ends after F8 typed one.

Dangling images are builds nothing names any more, usually because their tag moved to a newer build. Unused images have a name, and no container was made from them. Images and volumes that containers use, running or stopped, stay until those containers are removed, so their rows free nothing. An image frees only the layers no other image shares, which is why its reclaimable size can be far below its size.

→ or Enter unfolds a kind into its items, biggest first, and ← folds it again. The other panel shows the selected item: an image’s tags, ID, shared size, creation time, and container count; a build cache record’s type, whether it is shared or in use, and when a build last used it; a container’s image and status; a volume’s facts, which the next paragraphs describe. Sizes Docker could not measure show as ?, and / filters every kind at once. It also finds volumes by their Compose project and by the containers and images that use them.

Volume rows fill the room the Name column has to spare with Last used, Created, Project, and Used by, as many as fit, and Alt-W maximizes the pane to show them all. Project is the Compose project that made the volume. Used by lists the containers that mount it, running or stopped. Anonymous volumes go by the first 12 characters of their ID.

Last used reads in use while a container that mounts the volume runs. Otherwise it gives the day the last of those containers stopped, which Docker records exactly. Once the containers are removed, Docker keeps no record of the volume’s use. Where Borg reads a volume’s files directly, it also looks at when they last changed, and a later change shows as that day with ~ in front. That day is an estimate: reading a file leaves no trace, so the volume may have been used since. An empty cell means Borg knows neither.

The other panel shows the full time of the last use and of the creation, the Compose project with the volume’s name in it, and the Driver when the volume uses a driver other than local or has options. Each container that mounts the volume gets a line with its state and the path it mounts the volume at. For an anonymous volume, these are the containers it was Made for, with their images. Docker forgets that container once it is removed. Folder and Holds show where the files are on this machine and what is at the volume’s top.

Enter on a volume shows its files in the panel, read only. The title marks the panel with ▥ and read only, and paths start at the volume’s top. F3 views files, and F5 copies files out to the other panel. Borg refuses anything that would change the volume: editing, moving, deleting, new folders, packing, and copies into it. .. at the volume’s top returns the panel to the folder it showed before, and the command line stays in that folder all along. A session saved while a panel shows a volume opens that folder next time.

Borg reads a volume’s files directly when they are on this machine. With OrbStack on macOS, they are in OrbStack’s share in ~/OrbStack/docker/volumes, which macOS treats as a network volume: allow your terminal app Network Volumes in System Settings › Privacy & Security › Files & Folders. On Linux, Borg reads the volume’s folder when the engine runs on the same machine and Borg may open it, as with rootless Docker or when Borg runs as root. Search and sizes then work as in any folder.

Elsewhere, such as with Docker Desktop, a remote context, or Docker on Linux where only root reads its folders, Borg shows the files through a helper container. The helper runs the busybox image, pinned to one build, with no network, a read-only file system, and no privilege beyond reading files, and it mounts the volume read only. The first time, Borg asks before Docker downloads the image, about 2 MB, which then stays on the engine as borg-commander/volume-helper. The footer shows Downloading busybox… or Starting the helper container… until the panel opens. Borg removes the helper when the panel leaves the volume or when Borg quits, and a helper left behind stops by itself after a day. Search and sizes only work on the host there, as in a container’s files, and disk use doesn’t count the helper among the containers that use the volume.

Once a measurement ends, Borg reads the volumes it reaches directly in the background, biggest first, and the footer shows Reading volume files… until it is done. R reads them again as it measures.

F8 types the cleanup command for the selected row at the host shell’s prompt and shows the console. Nothing runs until you press Enter, so you can read the command, change it, or clear it with Ctrl-U first. On a kind, F8 types its prune, such as docker image prune -a for unused images or docker volume prune for unused anonymous volumes, and Docker asks for confirmation before it deletes anything. On an item, F8 types docker rmi, docker rm, or docker volume rm with that item, or with every marked image, container, or volume. Space or Insert marks an item, and * inverts the marks of the selected kind. An image goes by all its tags, since Docker deletes it with its last tag, or by its ID when it has none. Build cache records go together with docker builder prune. Borg never adds -f or --force. A name with a control character gets no command, since the prompt would take that character as a key.

Volumes hold the data containers saved, such as a database’s files, and a removed volume cannot be brought back. The other panel repeats this beside every volume command. When the docker CLI has more than one context, the commands name the one Borg measured, as in docker --context staging image prune, so they reach the same engine whatever context the shell would pick. They always go to the host’s shell, also while a panel shows a container’s files, because the Docker view keeps the command line on the host.