lzpody

README

lzpody

A small native Podman terminal UI inspired by lazydocker.

The TUI talks directly to Podman's Libpod REST API over the rootless Unix socket or a configured HTTP(S) endpoint. It does not invoke Docker CLI or require a Docker compatibility layer.

preview

🎬 Click to view showcase

https://github.com/user-attachments/assets/be54a50e-2339-49b2-852a-880f9aa18df1

Features

• Native rootless Libpod API over the Podman Unix socket.
• Containers, Pods, Images, Volumes, and Networks views.
• Lazydocker-style stacked resource panels, focused detail view.
• Libpod actions for pulling/building/pushing/pruning images, image history, tag/untag, registry search, save/load/import, registry login/logout, creating and running containers, managing pods/volumes/networks, executing commands, and copying files.
• Long-running pull, build, push, and system-prune operations show progress in the Bubble Tea UI and can be cancelled with Esc.
• Container init/wait/rename/commit/export, rootfs mount, healthcheck, filesystem diff, checkpoint/restore, Kubernetes YAML, systemd, and Quadlet.
• Live stats and event streams with filtering, history graphs, multi-select, and safe batch actions.
• Kubernetes play/generate/down, image manifest workflows, storage usage, and storage consistency checks.
• Persistent settings for endpoint, refresh interval, theme, log limits, and destructive-action confirmation.
• A single Go binary with no runtime dependencies beyond Podman and its API.

Run

Make sure the rootless Podman socket is available:

systemctl --user enable --now podman.socket
./lzpody

From a source checkout, ./lzpody uses go run; a release install executes the downloaded binary directly.

Install the latest release to ~/.local/bin with curl:

curl -fsSL https://raw.githubusercontent.com/roubilibo/lzpody/master/install.sh | sh

Run the same command again to update an existing installation. The installer verifies the release checksum and version, then replaces the installed binary atomically. It does not require root. Override the destination with PREFIX or BIN_DIR, and pin a release for install or update with LZPODY_VERSION:

curl -fsSL https://raw.githubusercontent.com/roubilibo/lzpody/master/install.sh | LZPODY_VERSION=v1.2.3 sh

Release binaries can also check for and install updates from the TUI: open the action menu (x or ?) and choose Check for updates. The update is verified before replacing the current binary; restart lzpody afterward. This option is unavailable for development builds and binaries in unwritable locations.

For development, clone the repository and run ./lzpody; this uses go run when no local binary is present. This source-checkout launcher is separate from the installed release binary.

For a fork or another release host, override the binary URL with LZPODY_BINARY_URL or its release directory with LZPODY_RELEASE_BASE_URL. Release directories should publish both SHA256SUMS and the matching binary assets. When using a standalone LZPODY_BINARY_URL, also set LZPODY_CHECKSUM_URL to a manifest containing that asset; without it, the installer warns that the custom binary is not checksum-verified. The installer supports Linux amd64, arm64, and armv7 builds.

If the socket was enabled before but its file is missing, recover it with:

systemctl --user restart podman.socket

The default socket is:

$XDG_RUNTIME_DIR/podman/podman.sock

Override it when needed:

LZPODY_SOCKET=/path/to/podman.sock ./lzpody

For a remote Podman service, use an HTTPS endpoint (or HTTP on a trusted network):

LZPODY_URL=https://podman.example.test ./lzpody

The client uses Libpod API v5.0.0 by default. If the Podman service exposes a different compatible API version, override it explicitly:

LZPODY_API_VERSION=v4.0.0 ./lzpody

lzpody — Keyboard Shortcuts

1. Navigation

Mouse input is enabled in supported terminals. Click a panel or item to focus it, click a detail tab to open it, click menu entries to activate them, and use the scroll wheel over a panel or detail view to navigate. Right-click an item or the detail view to open its resource-specific context menu.

Shortcut	Action
↑ / ↓	Select previous / next item
j / k	Select next / previous item
← / →	Switch resource panels
h / l	Switch resource panels
Tab	Move to the next panel
1 – 6	Focus a specific resource panel
Enter	Open the main detail view
Esc	Return to resource panels

2. Detail View

Shortcut	Action
↑ / ↓	Scroll up / down
j / k	Scroll down / up
PgUp / PgDn	Scroll one page up / down
Ctrl-U / Ctrl-D	Scroll one page up / down
Home	Jump to the beginning
End	Jump to the end
[ / ]	Switch detail tabs

3. Action Menu

Shortcut	Action
x / ?	Open action menu
↑ / ↓	Navigate actions
j / k	Navigate actions
/	Search/filter actions in the command palette
Enter / Space	Select an action
Esc / q	Close action menu

4. Container Actions

Container shortcuts follow LazyDocker conventions.

Shortcut	Action	Description
e	Toggle Stopped	Show / hide stopped containers
p	Pause / Unpause	Pause or resume a container
s	Stop	Stop a running container
S	Start	Start a stopped container
r	Restart	Restart a container
m	Logs	Open container logs
a	Attach	Attach to a container
E	Shell	Open an embedded shell inside a container; Esc closes it
d	Remove	Remove a container
i	Config	Show container configuration
t	Stats	Show container statistics
K	Kill	Forcefully terminate a container
Space	Mark	Select containers/pods for batch actions

5. General Shortcuts

Shortcut	Action
/	Filter items
F5	Refresh resources
P	Pull image
B	Build image
U	Push image
C	Create and run container
q	Quit application

While a pull, build, push, or system-prune operation is running, press Esc to cancel it. After completion, press any key to close its report.

6. Libpod actions

Open x or ? for the complete action menu. Actions that need values open an input overlay; use | to separate values:

Action	Input format
Pull image	image-reference (live layer progress is shown in the detail panel)
Create and run container	Tabbed form: Basic, Network, Runtime, and Security; fields can be revisited without a linear wizard
Create secret	secret-name, then a local secret file path
Build image	context-directory | image-tag
System prune	YES | all | volumes | build | filters (filters comma-separated, e.g. until=24h,label=app=demo)
Storage check	quick yes/no | repair yes/no | repair-lossy yes/no | max age
Push image	local-image | registry-destination
Tag image	Select an image, then repository | tag
Search registry	search-term | limit
Save image	Select an image, then a .tar destination path
Load/import image	A local .tar path, with optional import reference
Registry login/logout	Registry credentials (password is masked), or ALL to log out everywhere
Execute command	command
Copy to container	local-file | container-path
Copy from container	container-path | local-path
Create pod/volume/network	Network form also accepts driver, subnet, gateway, IP range, IPv6, internal, labels, and driver options
Connect/disconnect network	container-name-or-id
Relationships	Select a container, pod, volume, or network and open Relationships to see links and usage
Prune images	type YES

The menu also exposes volume mount/unmount, System info, storage usage and consistency checks, Kubernetes actions, systemd/Quadlet generation, Settings, and Events. Stats and Events use native Libpod streaming endpoints while the detail panel is open.

Settings are stored at $XDG_CONFIG_HOME/lzpody/config.json, or ~/.config/lzpody/config.json when XDG_CONFIG_HOME is not set.

---

Note: Detail actions such as Logs, Config, Environment, Top, and Stats automatically focus the detail panel. All Detail View navigation shortcuts apply there as well.

Omarchy appearance

The TUI reads the active Omarchy palette from ~/.config/omarchy/themes/<active-theme>/colors.toml and applies the foreground, accent, selection, muted, green, red, and yellow colors to the panels, focus state, actions, and status line. It falls back to the bundled Akane-compatible palette when Omarchy is unavailable.

Development

The Go TUI is built around Bubble Tea's model/update/view lifecycle. Terminal size and resize events come from Bubble Tea, styling is rendered with Lip Gloss, and Podman requests plus external commands run as Bubble Tea commands and return messages to Update.

go test ./...
go build -o lzpody-bin .
./lzpody-bin --help

Build release assets with names such as lzpody-linux-amd64:

GOOS=linux GOARCH=amd64 go build -trimpath -ldflags='-s -w' -o lzpody-linux-amd64 .

Pushing a v* tag runs the release workflow and publishes the three Linux assets consumed by install.sh.

License

This project is licensed under the MIT License.