Podos A lightweight container platform Early development · not released

Operations

Install and set up a server

Requirements

Supported
Operating system Ubuntu 24.04 (other systemd distributions may work; not tested). Available The install script supports Ubuntu 24.04 and 26.04.
Kernel features cgroup v2, overlayfs; Available Linux 5.6 or newer
Init system systemd (the daemon uses transient systemd scopes for containers); Available systemd 245 or newer
Packages crun, conmon; Available nft (Ubuntu package nftables). Available The install script provides crun and conmon itself.
For build Available BuildKit and crun 1.15 or newer. Ubuntu 24.04's own crun is 1.14, which is too old. The install script provides both.
Privileges root (see Security model)
Architecture amd64 or arm64

podos setup checks for crun, conmon, systemctl and systemd-run. Available It also checks for nft and that the kernel is Linux 5.6 or newer; it does not check the systemd version. The networking needs the kernel, systemd and nft minimums.

Podos runs on Linux only. On macOS or Windows, use a Linux VM.

Next to Docker or another firewall

Available Podos detects Docker's, ufw's and firewalld's firewalls dropping packets: the daemon logs a warning and podos setup prints one, with the exact commands for the firewall it found, as described in the rest of this section. It checks forwarded and incoming traffic.

If another firewall on the server drops packets by default, Podos traffic is dropped even though Podos accepts it. This happens on two paths:

Docker does this on the forward path: it sets the policy of its iptables FORWARD chain to drop. ufw and firewalld drop both. Docker's own containers keep working; Podos traffic does not.

Podos recognises ufw, firewalld and Docker. It changes only its own firewall table and never changes another firewall, so it does not fix this itself. It detects it: the daemon logs a warning at start and whenever the situation changes, and podos setup prints a warning on standard error after its normal output (the exit code is unchanged). The warning names the chains, says what is dropped and prints the exact commands for the firewall it found. An example:

warning: another firewall on this server drops packets by default:
  table ip filter, chain FORWARD (forward hook, policy drop, docker)
Packets that no rule there accepts are dropped even though Podos accepts them:
  forward hook: containers cannot reach the internet and published ports cannot be reached from outside;
Podos changes only its own firewall table; the owner of that firewall decides.
Docker's firewall drops forwarded packets. To let Podos traffic pass:
  1. add  "ip-forward-no-drop": true  to /etc/docker/daemon.json
  2. run  iptables -P FORWARD ACCEPT
Step 1 keeps the setting after a reboot; step 2 applies it now.
This sets Docker's FORWARD policy to accept: forwarded traffic that no Docker rule drops passes, for Docker's containers as well as for Podos'.

Under ufw or firewalld, without the commands below, containers have no service names and no outbound access, and the ingress is not reachable from outside. A deploy still reports success.

ufw. The rules let everything on the Podos interfaces (names starting with pd) be forwarded and reach the DNS port of the server, and open the ingress ports to anyone. ufw keeps them after a reboot. With other ingress ports (--http-listen, --https-listen), the warning names those ports instead of 80 and 443.

sudo ufw route allow in on pd+
sudo ufw route allow out on pd+
sudo ufw allow in on pd+ to any port 53
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

firewalld. This puts every Podos interface in the trusted zone, which accepts all traffic from them to the server and through it, and opens the web ports to anyone. For other ingress ports, the warning prints --add-port commands instead of the services.

sudo firewall-cmd --permanent --zone=trusted --add-interface=pd+
sudo firewall-cmd --permanent --add-service=http --add-service=https
sudo firewall-cmd --reload

Docker. Available Add the setting to /etc/docker/daemon.json (merge it with any settings already there), then change the policy now:

{
  "ip-forward-no-drop": true
}
sudo iptables -P FORWARD ACCEPT

Docker reads daemon.json when it starts, so the first step keeps the setting after a Docker restart or a reboot; the second applies it now, without restarting Docker. This has been tested with Docker 29.1.3 through a Docker restart and a reboot.

Other firewalls: the warning gives general advice. Allow, in that firewall, the Podos interfaces (names starting with pd): forwarding in and out, input to port 53, and the ingress ports to the outside.

Podos looks at the default of a chain: a drop policy, or rules that end in a drop or a reject. It does not check single rules. A server whose firewall already allows the Podos interfaces can still show the warning, so the warning means that packets may be dropped, not that they are.

Install today

Available There are no release binaries yet. Build from source with Go 1.26 or newer (on any machine; the binary is static):

git clone https://github.com/podos-org/podos.git
cd podos
GOOS=linux GOARCH=amd64 make build     # or GOARCH=arm64

Copy bin/podos to the server, for example to /usr/local/bin/podos. Then, on the server:

sudo apt update
sudo apt install -y crun conmon nftables
sudo podos setup
sudo podos daemon

podos setup creates /var/lib/podos (mode 0700) with the secrets key and the state database, and checks the host tools. Available It also creates the internal CA and the first admin token, which it prints once, and prints the CA fingerprint. podos daemon runs in the foreground; run it under your own supervisor (for example a systemd service you write). Available The install script installs a unit.

This path needs the apt packages above, and it does not give you build: the crun from Ubuntu 24.04 is too old and BuildKit is not installed. To get a server that can build, install a binary you built with the script, as described next.

Build with the web UI

Available make build does not include the web UI. A binary built that way answers on the HTTPS address with a page that says the UI is not built in; the API and the CLI are not affected. To include the UI, run make ui before make build:

make ui
GOOS=linux GOARCH=amd64 make build

make ui needs Node 22.22 or newer and npm. It runs npm ci and npm run build in web/ and copies the result into the source tree that make build embeds. make build and make test themselves need only Go.

Install a binary you built, with the script

Available The install script also installs a local binary instead of a release, so it works today. From a clone of the repository, as root on the server (copy the podos binary and scripts/install.sh there first):

sudo env PODOS_BINARY=/root/podos sh install.sh

PODOS_BINARY must be an absolute path to a regular file. The script then installs the pinned crun, conmon and BuildKit from their upstream releases, checked against SHA-256 values written into the script. The podos binary you point at is not checked: you built it.

podos version --licenses prints the licenses of the third-party software compiled into the binary.

Install script

Available One command on a fresh server installs the binary, pinned versions of crun, conmon and BuildKit, and a systemd unit for the daemon, then runs podos setup and starts the daemon. The same script upgrades and uninstalls.

There are no release binaries yet. The command below works once a release exists; until then it answers "not found". Install today by building from source. A shorter address for the script is planned.

Once a release exists:

curl -fsSL https://github.com/podos-org/podos/releases/latest/download/install.sh | sudo sh

Or download install.sh first, read it, and run it with sudo sh install.sh.

Supported: Ubuntu 24.04 and 26.04, on amd64 and arm64, with systemd as init and cgroup v2. Anything else is refused, unless you set PODOS_INSTALL_UNSUPPORTED=1 to try anyway; nothing is promised then.

What it installs. Every download is HTTPS only. crun, conmon and BuildKit are pinned versions with a SHA-256 written in the script. The podos binary is checked against the SHA-256 published with the release. A mismatch stops the script before anything is installed. Files are replaced atomically.

Path What
/usr/local/bin/podos The program: daemon and CLI.
/usr/local/lib/podos/bin/ crun 1.31, conmon v2.2.1, and BuildKit v0.35.0 (buildkitd, buildctl). Not on PATH.
/usr/local/lib/podos/installed Which versions the script installed.
/usr/local/lib/podos/podos.previous The binary before the last upgrade, for the rollback.
/etc/systemd/system/podos.service The daemon's unit.
/etc/modules-load.d/podos.conf Kernel modules loaded at boot.
/etc/modprobe.d/podos-blacklist.conf Protocol modules that no Podos host needs, disabled host-wide (SCTP, DCCP, AF_ALG, RDS, TIPC, Bluetooth, CAN and others). Set PODOS_SKIP_MODPROBE_BLACKLIST=1 to skip it.

It also installs nftables from the distribution with apt-get when nft is missing. It needs curl.

On a server installed this way, Podos looks for crun, conmon, buildkitd and buildctl in /usr/local/lib/podos/bin before the system path. You do not need apt install crun conmon there. The Install today path (a binary you copy yourself) does need those packages.

What it prints first. Before it changes anything, the script prints the list of changes it is about to make. When nothing needs changing it says so and changes nothing.

Arguments for podos setup. Everything after -- is passed to podos setup:

curl -fsSL https://github.com/podos-org/podos/releases/latest/download/install.sh | sudo sh -s -- -- --acme-email me@example.com --listen 0.0.0.0:8443 --tls-name host.example.com

When you run a downloaded script, that is sudo sh install.sh -- --acme-email me@example.com --listen 0.0.0.0:8443 --tls-name host.example.com. On a server that is already set up, arguments after -- run podos setup again with them: the daemon is stopped for it and started again, and running containers keep running.

The admin token is shown once. A first install runs podos setup, which prints the first admin token and the CA fingerprint once, to a terminal. When standard output is not a terminal (a pipe into a log, for example), the script refuses to start: run it in a terminal (over ssh: ssh -t), or set PODOS_TOKEN_FILE=/absolute/path and podos setup writes the token to that new file with mode 0600 instead. Nothing is changed when it refuses.

Finish the setup in a browser. Available Instead of an admin token on the terminal, the script can leave the first setup to a browser:

sudo sh install.sh -- --web --listen 0.0.0.0:8443 --tls-name host.example.com

This passes --web to podos setup. No admin token is created, so the script needs no terminal and no PODOS_TOKEN_FILE. It prints the address, a one-time setup code (valid 30 minutes) and the CA fingerprint of the server. When the output is not a terminal, the code is in the script's output. Open the address, compare the CA fingerprint with the browser's certificate warning, and enter the code. See Web UI for the steps and for a new code. sudo podos setup --web issues a new code while the setup is pending.

Variables. All are optional.

Variable Meaning
PODOS_VERSION Release tag to install, for example v0.1.0. Default: the latest release.
PODOS_BINARY Absolute path of a local podos binary to install instead of downloading a release.
PODOS_RELEASE_URL Base URL of the releases. https only. Default https://github.com/podos-org/podos/releases.
PODOS_TOKEN_FILE Absolute path where podos setup writes the first admin token (mode 0600) instead of printing it. Needed when standard output is not a terminal.
PODOS_SKIP_STATE_CHECK=1 Skip the check that the state database is not newer than the new binary.
PODOS_INSTALL_UNSUPPORTED=1 Try an operating system or architecture the script refuses.
PODOS_SKIP_MODPROBE_BLACKLIST=1 Do not write /etc/modprobe.d/podos-blacklist.conf. An existing one is left alone.
PODOS_WAIT_SECONDS How long to wait for the daemon to answer after a start. Default 300.

Running it again on an up-to-date server prints that Podos is already installed and changes nothing. To upgrade, see Upgrade and backup.

The unit. It starts podos daemon without flags: the settings come from podos setup. It restarts the daemon on failure, writes no core dumps, and runs with a reduced capability set (it drops, among others, the capabilities to load kernel modules, set the time, reboot and read the audit log). Stopping or restarting the unit never stops containers: they run in their own systemd scopes. The file is replaced on upgrade; put changes in a drop-in file (systemctl edit podos).

Uninstall

sudo sh install.sh uninstall

This stops and disables the daemon and removes the unit, /usr/local/bin/podos, the files in /usr/local/lib/podos that the script installed, and the two files in /etc/modules-load.d and /etc/modprobe.d. It keeps /var/lib/podos (database, secrets key, images, volumes). It does not stop running containers: they keep running without a daemon, and nothing restarts, routes or supervises them until you install Podos again, which adopts them.

sudo sh install.sh uninstall --purge

--purge also stops and removes all containers, deletes the Podos firewall table and network interfaces, and deletes /var/lib/podos and /run/podos with all data, including the secrets key. This cannot be undone. When the data directory is a mount point of its own (a dedicated disk), its content is deleted and the mount point stays. At the end the script lists anything of Podos that is still there.

Files and directories

Path Content
/var/lib/podos Data directory: state database, secrets key, images, container root filesystems and logs. Mode 0700. Override with --data-dir or PODOS_DATA_DIR.
/run/podos/podos.sock The daemon's Unix socket, mode 0600, root only. Override the directory with --run-dir or PODOS_RUN_DIR.

Remote access

Available By default the daemon opens no TCP port. With --listen ADDR:PORT (or podos setup --listen) it also serves the API over HTTPS, with a certificate from the internal CA for the --tls-name names. You choose the port, for example 8443, and open it in the server's firewall. See Several servers with contexts.

Upgrading an M2 server

Available Install nftables first (sudo apt install -y nftables); the new daemon needs nft for the container networks. A server set up with M2 has no admin token. After you install the new binary and restart the daemon, run as root on the server:

sudo podos token create --name admin --kind admin

The local socket keeps working as before; root there is an administrator. sudo podos ca fingerprint prints the CA fingerprint for podos login. To enable remote access, add --listen and --tls-name as described in Several servers with contexts.

Available Before it changes the database schema, the daemon writes a backup state.db.before-v<N> next to the database and logs each migration; see Upgrade and backup. Containers started by a version before M3 keep running after the upgrade, but without networking, until you deploy the application again. The daemon logs a warning for each of them.

Ports

Available The daemon opens these ports:

Port Why How to change it
80 and 443 The built-in proxy for domains. podos setup --http-listen, --https-listen, or --ingress off
The one you choose, for example 8443 The remote HTTPS API, only with --listen. podos setup --listen, --reset listen
Each port you publish Published ports of your services. the publish key

Podos does not open firewall ports for you. Two environments cannot publish the same host port, and a port the server already listens on (such as 22) cannot be published. The message is the same for every reason: port tcp/N cannot be published on this server.

Network settings

Available Each project and environment gets a private network carved from 10.88.0.0/16 in /24 slices. Change the range with podos setup --network-pool (private ranges only). By default containers reach the internet and the server's private networks; the cloud metadata address is always blocked. podos setup --strict-egress stops containers from reaching private networks, and --allow-egress CIDR lists the exceptions. See podos setup.

Let's Encrypt

Available tls = "auto" needs podos setup --acme-email EMAIL, which also records your agreement to the certificate authority's terms of service. It has only been tested against a test ACME server, not yet against the real Let's Encrypt service. See Domains and HTTPS.

Available By default the daemon uses the Let's Encrypt production directory. Two daemon flags change that (they are flags only; podos setup does not save them):

Node protection and disk guard

Available At every start the daemon reads the server's memory, CPU count and disk. It caps all containers together at the server's memory minus a system reserve, and at 80% of the kernel's process limit. A service whose memory limit is larger than what the server can give to containers is refused at deploy. Deploys and image pulls are refused with "not enough free disk space on the server" when the data directory's file system is nearly full; running containers are never stopped because of it. These are the defaults and the daemon flags that change them (flags only; podos setup does not save them):

Setting Default Flag
System reserve (memory kept for the system) 10% of the server's memory, at least 256 MiB, at most 2 GiB --system-reserve-memory SIZE, for example 512M or 1G
Free-disk threshold the larger of 1 GiB and 5% of the file system, at most 10 GiB --min-free-disk SIZE, for example 2G

See Limits.