Foxws

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, .volume or .network file 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 with podman quadlet, systemctl and journalctl.
  • systemd does the work. Starting at boot, restarting on failure, logs, timers, dependencies and podman auto-update all 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 podman or systemctl itself. It only runs lpod … --json and reads the JSON it returns. The CLI and the UI do the same thing, and you can always fall back to lpod in 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 in tests/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 by podman 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:install generates an ed25519 key pair. You add the public key to ~/.ssh/authorized_keys of 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.