Podos A lightweight container platform Early development · not released

Get started

Quick start

This page runs a first application. It takes about ten minutes, most of it building the binary. The binary you build from the current source includes the features marked Available (networking, the HTTPS proxy, health checks, remote use and more). There are no release binaries yet.

Available The five-minute version. The flow is built: run the install script on a fresh server, podos login from your laptop, then podos deploy from your application directory, where a service with build = "." is built on the server from your Dockerfile, and open it on HTTPS. It needs the first published release, and there is none yet. Remote use with podos login is Available (see Several servers with contexts). Until a release exists, this page uses today's path: you build the binary yourself and set up the server as root.

What you need

Install the runtime packages on the server (nftables provides nft):

sudo apt update
sudo apt install -y crun conmon nftables

1. Build the binary

There are no release binaries yet. Build a static Linux binary from the source (set GOARCH=arm64 for an ARM server):

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

The binary is bin/podos. Copy it to the server, for example to /usr/local/bin/podos, and check it:

podos version

2. Set up the server

Run podos setup once, as root. It creates the data directory (/var/lib/podos, mode 0700), the secrets key and the state database, and checks the kernel version and that crun, conmon, nft, systemctl and systemd-run are installed:

sudo podos setup

Running it again changes nothing. Back up the secrets key and the database together: secrets cannot be recovered without the key.

Available You can also finish the setup in a browser instead: podos setup --web --listen ADDR:PORT --tls-name NAME creates no admin token and prints a one-time setup code. See Web UI. This page keeps the command line path.

3. Start the daemon

The daemon runs in the foreground until you stop it. (Available The install script sets up a systemd unit instead, once a release exists.) Keep this terminal open:

sudo podos daemon

It listens only on a Unix socket, /run/podos/podos.sock, which only root can use. All other commands below talk to that socket, so run them as root in a second terminal. (Available The daemon also starts the built-in proxy on ports 80 and 443; podos setup --ingress off turns it off. This example does not use it.)

sudo -i

4. Write a manifest

Create an application directory with a manifest. This one runs two replicas of a small BusyBox loop that prints a greeting and a secret every second:

mkdir -p ~/hello && cd ~/hello
TOML
project = "hello"

[service.web]
image = "busybox:1.36"
replicas = 2
command = ["/bin/sh", "-c", "while true; do echo \"$GREETING $API_TOKEN\"; sleep 1; done"]
env = { GREETING = "hello ${env.WHO}", API_TOKEN = "${secret.API_TOKEN}" }
YAML
project: hello

service:
  web:
    image: busybox:1.36
    replicas: 2
    command: ["/bin/sh", "-c", "while true; do echo \"$GREETING $API_TOKEN\"; sleep 1; done"]
    env:
      GREETING: "hello ${env.WHO}"
      API_TOKEN: "${secret.API_TOKEN}"

Save it as podos.toml (or podos.yaml; only one of the two may exist). podos init can write a starter manifest for you instead.

Check it:

podos manifest validate

It prints podos.toml: valid and what would be deployed, or every problem with its file, line and key.

5. Set a value and a secret

The manifest refers to ${env.WHO} and ${secret.API_TOKEN}. Both must exist in the environment before the deployment, or podos deploy refuses it and lists what is missing.

podos env set WHO=world
podos secret set API_TOKEN

podos secret set asks for the value twice without echo. You can also pipe it in on standard input. Values given to podos env set appear in your shell history, so never put secrets there.

6. Deploy

podos deploy

The daemon pulls the image, verifies every layer against its digest and starts two containers. The command follows the progress and ends with the release number and its state. Exit code 0 means the release is active.

podos ps
podos logs web --tail 5
podos logs web -f        # follow; Ctrl+C stops

podos ps lists service, replica, container ID, release, status and start time. Available It also shows READY (yes, starting or no, or - right after the daemon starts) and RESTARTS. In podos logs, a line from replica 0 starts with web/0.

The containers keep running when the daemon stops. Stop the daemon with Ctrl+C, start it again, and podos ps shows the same containers.

Change the manifest (for example replicas = 1) and run podos deploy again to roll out a new release. If the new release fails, the previous one keeps running. Available A container that crashes is restarted with a growing delay, and a release that never becomes healthy is rolled back automatically; podos releases shows why.

Each environment has its own private network (Available). A second service in this project could reach web by its name, for example http://web:8080/ if web listened on port 8080. To serve a service on a domain with HTTPS, see Domains and HTTPS.

7. Clean up

podos down

podos down asks you to type the environment name (prod), then stops and removes the containers and deletes the environment with its values and secrets, which cannot be recovered. The project is kept. Available It also removes the environment's network, domains and published ports; volume data is kept unless you pass --delete-volumes.

Deploy your own code

Available To deploy an application with a Dockerfile instead of a public image, write build = "." in the service (podos init does this when it finds a Dockerfile) and run podos deploy in that directory:

TOML
project = "myapp"

[service.web]
build = "."
port = 3000
YAML
project: myapp

service:
  web:
    build: .
    port: 3000

podos deploy uploads the source, the server builds it with BuildKit while the log is shown, and the release uses the image that came back. This needs BuildKit and crun 1.15 or newer on the server. The crun that Ubuntu 24.04 ships is too old, and the apt packages above do not include BuildKit; the install script provides both. See Build from source.

Next steps