Pods
A self-hosted web UI for Podman Quadlet, made for homelabs.
- Latest release
- 1.0.1
Documentation
Pods is a self-hosted web UI for Podman Quadlet, made for homelabs. It manages the applications, containers, pods, images, volumes, networks, secrets and journal of one or more Podman hosts, over SSH.
Upgrades within Pods 1.x keep your data: pods-update migrates the database and keeps your setup, and Pods 1.x stays on version 1 of lpod's JSON contract. An install has one owner. Pods exports volumes but doesn't restore them yet. See Backups to restore an archive on the host.
Why Pods
- Your applications are plain Quadlet files. A
.container,.volumeor.networkfile is a systemd unit that Podman ships with. Pods installs them, starts them and shows what they're doing, but it never adds a format of its own on top. Delete Pods and every application keeps running, managed by systemd as before. You can always edit, install or debug them withpodman quadlet,systemctlandjournalctl. - systemd does the work. Starting at boot, restarting on failure, logs, timers, dependencies and
podman auto-updateall come from systemd and Podman. Pods adds no daemon or agent of its own on the host. lpod is a shell script that Pods runs over SSH. - Nothing has to keep running. Applications can sleep until a request comes in, through systemd socket activation (see On-demand applications). Pods itself does the same: it's a container that starts when you open it and stops when you leave.
- One UI for several hosts. Every host is an SSH target, the one Pods runs on too.
Compared with
| What it is | How Pods differs | |
|---|---|---|
| Cockpit | A web console for a whole Linux server, with a Podman page for containers, pods and images | Pods is only about the applications on a host, and treats them as groups of Quadlet units: install from Git, routes, secrets, setup steps and updates. It runs fine next to Cockpit, and sleeps through a socket the same way cockpit.socket does. |
| lerd | A local Laravel development environment for Linux on rootless Podman | lerd is for developing on your own machine. Pods runs applications on your servers and homelab. An application you develop with lerd can ship Quadlet files and a pods.yml to be installed with Pods. |
| Laravel Sail | A Docker Compose development environment for one Laravel project | Sail is for development, with Docker and Compose. Pods is for running applications, with Podman and systemd, and isn't tied to Laravel. |
| Laravel Cloud | Managed hosting for Laravel applications | Laravel Cloud runs and scales your application for you. Pods runs any containerized application on hardware you own, and you're responsible for the host. |
| Portainer | A container UI for Docker, Swarm and Kubernetes, built around Compose stacks | Pods doesn't support Docker or Compose. Its applications are systemd units, so they behave like the rest of the host. |
Getting started
- Screenshots: see what Pods looks like before you install it.
- Installation: the requirements, and installing Pods on a host with one command.
- Getting Started: create the owner, install an application from the catalog, and make your own repository installable.
Guides
| Guide | What it covers |
|---|---|
| Application Manifest | pods.yml: secrets, setup steps, routes, on-demand and timers |
| Proxy | Hostnames and certificates for applications, with Caddy |
| On-demand Applications | Letting applications sleep until a request comes in |
| Backups | Volume sizes, exporting volumes and restoring them by hand |
| Health Checks | Checking that Pods itself is up |
| Development | Working on Pods: setup, commands and tests |
| Architecture | How Pods talks to hosts through lpod and SSH |
| Roadmap | What's planned next |
How it works
Browser ──HTTP──▶ Pods (Laravel) ──SSH──▶ host ──▶ lpod … --json ──▶ podman, systemctl, journalctl
- Every host is an SSH target, the local one too. Pods runs in a container and reaches the machine it runs on through
host.containers.internal, so local and remote hosts use the same code path. - lpod is the host agent. Pods never runs
podmanorsystemctlitself. It only runslpod … --jsonand reads the JSON it returns. The CLI and the UI do the same thing, and you can always fall back tolpodin a terminal. - The JSON contract is versioned. Every payload carries
"contract": 1. Pods refuses a host that speaks a contract it doesn't know. The fixtures intests/Fixtures/lpod/contract-1/are the spec lpod implements. - Quadlets are the source of truth. An application is a group of Quadlet units (
.container,.pod,.kube,.volume,.network) as reported bypodman quadlet list. Pods stores no copy of your containers. It only stores the environments (hosts) and its own users. - One SSH key per Pods instance.
pods:installgenerates an ed25519 key pair. You add the public key to~/.ssh/authorized_keysof the user that owns the Quadlets. When you add a host, Pods pins its host key and refuses to connect when it changes. - Secrets only travel on stdin. Secret values are piped to lpod and never end up in command arguments, logs or the database.
- Reads are cached for a few seconds per host (
PODS_CACHE_TTL). Actions such as start, stop or prune clear the cache, and the pages poll for the new state. Other open pages of the host reload what changed right away, over Reverb (pods-reverb, on Pods' own address), so pages only poll for changes made outside Pods, such as CPU and memory: every 10 seconds by default (Settings, General, Refresh host pages: off, 3, 5, 10, 15 or 30 seconds, 1, 3 or 5 minutes), and every 5 seconds (or the shorter setting) while a unit starts or stops.
See Architecture for the details.
