Podos A lightweight container platform Early development · not released

Reference

CLI reference

podos is one binary with subcommands. Every command prints its own help:

podos --help
podos deploy --help
podos help env set

Flags are written with two dashes (--env); one dash also works. The common ones also have a one-letter form (-e); see Short flags. For env, secret, file and logs, flags may come before or after the other arguments.

Command overview

Command Purpose Status
podos setup Prepare this server: data directory, secrets key, database (Available internal CA, first admin token, network, proxy and TLS settings) Available
podos daemon Run the daemon Available
podos init Write a starter manifest Available
podos manifest validate Validate the manifest and show what would be deployed Available
podos deploy Deploy the application Available
podos ps List the containers of an environment Available
podos logs Show the logs of a service Available
podos down Remove an environment's deployment, with its data (--delete-volumes Available) Available
podos env Manage env values (set, list, unset; create Available) Available
podos secret Manage secrets (set, list, unset) Available
podos file Manage files mounted into containers (set, list, get, unset) Available
podos cert Manage uploaded TLS certificates (set, list, remove) Available
podos image pull Pull an image into a local content store (developer command) Available
podos version Print the version, limits or licenses Available
podos login Save the address, CA and token of a server as a context Available
podos logout Delete the saved token of a context Available
podos context List and switch between servers (list, use, remove) Available
podos whoami Show which token the selected server sees Available
podos token Manage API tokens (create, list, revoke) Available
podos ca fingerprint Print the fingerprint of the server's CA Available
podos releases List the releases of an environment Available

All commands in this list are in the code on the main branch; there are no release binaries yet.

Exit codes

All commands use the same exit codes:

Code Meaning
0 Success.
1 The operation failed or was refused, including a server certificate that does not match the saved CA. Fix the cause and try again.
2 Usage error: unknown command or flag, missing argument.
3 Try again later: the daemon is unreachable, busy or rate limited, another deployment is running, you disconnected before the result, or a followed log stream was replaced by a redeploy.

Connecting to the daemon

On the server, client commands talk to the daemon over a Unix socket that only root can use, so run them as root. Available From another machine they talk to the daemon's HTTPS API with a token saved in a context; see Several servers with contexts.

A command picks its server in this order, first match wins:

  1. the flag --context NAME of the command;
  2. the global flag --socket PATH, before the command (podos --socket /run/podos/podos.sock ps), or the command's own --socket flag: the local socket;
  3. the environment variable PODOS_CONTEXT;
  4. the environment variable PODOS_SOCKET: the local socket;
  5. Available the context key of the manifest for the environment (see Binding an environment to a server);
  6. Available the current context, set by podos login --use or podos context use. A first podos login also sets it, but only when there is no current context and no podos daemon answers on this machine's local socket;
  7. the local socket.

--context and --socket together are a usage error. The context name local is built in and always means the daemon socket on this machine.

The local socket is found in this order: --socket, PODOS_SOCKET, $PODOS_RUN_DIR/podos.sock, /run/podos/podos.sock.

Available Every command that talks to a server other than the local socket prints on standard error which context and URL it uses and what chose it.

Contexts are kept in $XDG_CONFIG_HOME/podos/contexts.json (default ~/.config/podos/contexts.json), mode 0600, in a directory with mode 0700. The file holds tokens; a file that others can read or write is refused. Proxy environment variables are ignored for server connections.

Choosing the project and environment

deploy reads the manifest. ps, logs, releases, down, env and secret work on one project and environment, chosen like this:

So in an application directory with a single-environment manifest, no flags are needed. Elsewhere, give both: podos ps --project shop --env prod.

Available When both are missing, the error names both, for example --project is required and --env is required: there is no manifest in the application directory to take them from.

These flags are shared by ps, logs, releases, down, env and secret:

Flag Meaning
-d, --dir DIR Application directory holding the manifest. Default: the current directory.
-p, --project NAME Project. Default: from the manifest.
-e, --env NAME Environment. Default: the manifest's only environment.
--socket PATH Daemon socket. Default: see above.
-c, --context NAME Available Server to use: a context made with podos login, or local. Default: see Connecting to the daemon.

Available podos cert takes the same flags. deploy takes --dir, --env, --socket and --context.

Short flags

The common flags have a one-letter form. A letter means the same in every command that has the long flag.

Short Long Commands that have it
-p --project ps, logs, releases, down, env, secret, file, cert, init, token create
-e --env deploy, manifest validate, ps, logs, releases, down, env, secret, file, cert, token create
-c --context every command that talks to a server, including deploy, whoami and token
-d --dir deploy, manifest validate, init, ps, logs, releases, down, env, secret, file, cert
-j --json ps, releases, file list, cert list, token list, context list, whoami, manifest validate, image pull
-y --yes down, the command that asks for confirmation
-f --follow logs
-t --tail logs
-r --replica logs

-h is help. Help prints both forms on one line, for example -e, --env string.

When you give both forms of one flag, the last one wins. Flags that delete data or weaken security (--delete-volumes, --raw, --secrets-write), --socket, and every flag of podos daemon and podos setup have no short form on purpose, so that a typo cannot trigger them.

podos logs web -p demo -e prod -f -t 20

podos setup

podos setup [flags]

Run once, as root, on the server. Creates the data directory (mode 0700), the secrets key, the state database, Available the internal certificate authority (CA) and the first admin token. It also checks that crun, conmon, systemctl and systemd-run are installed and prints their versions. Available It also checks that nft is installed and that the kernel is Linux 5.6 or newer.

Available The first admin token is printed once, and only to a terminal, or written to the file named by --token-file. Only its hash is stored. The CA fingerprint is printed on every run; compare it when you run podos login from another machine.

Running it again on a set-up server changes nothing and prints no token, unless you pass --new-admin-token. It never creates a new key or database next to an existing one, and refuses while a daemon runs. It needs no network access.

Flag Meaning
--data-dir DIR Data directory. Default: $PODOS_DATA_DIR, then /var/lib/podos.
--listen ADDR:PORT Available Save the HTTPS listen address of podos daemon, for example 0.0.0.0:8443.
--tls-name NAME Available Save a DNS name or IP address of this server for the HTTPS certificate. Repeatable. Needed with --listen on all interfaces.
--token-file PATH Available Write the admin token to this absolute path (mode 0600, never over an existing file) instead of printing it. Required when standard output is not a terminal.
--new-admin-token Available Create another admin token on a server that is already set up.
--web Available Do the first setup in a browser: prepare the server, create no admin token, and print the address and a one-time setup code. Needs --listen and --tls-name. See below.
--web-ui on|off Available Serve the web UI on the HTTPS listener. Saved; default on.
--ingress on|off Available Serve domains through the built-in proxy. Saved; default on.
--http-listen ADDR:PORT Available Save the proxy's HTTP address. Default :80.
--https-listen ADDR:PORT Available Save the proxy's HTTPS address. Default :443.
--acme-email EMAIL Available Enable tls = "auto" (Let's Encrypt): save EMAIL as the contact and agree to the certificate authority's terms of service (https://letsencrypt.org/repository/). Only this setting enables auto.
--network-pool CIDR Available The range application networks are carved from, in /24 slices. Default 10.88.0.0/16; it must be inside a private range.
--strict-egress Available Containers may not reach private networks, other than those given with --allow-egress.
--allow-egress CIDR Available With --strict-egress: a prefix containers may still reach. Repeatable.
--reset NAME Available Turn a saved setting off again: listen, http-listen, https-listen, acme-email, network-pool, strict-egress, allow-egress. Repeatable. An empty flag value never resets anything.
--check-state Available Check that this binary can open the state database in the data directory, without changing it, and exit. Read-only; the install script uses it before an upgrade.
--print-modprobe-blacklist Available Print the modprobe blacklist for this host and exit. Read-only; the install script uses it to write /etc/modprobe.d/podos-blacklist.conf.

Available With --web (and --listen ADDR:PORT --tls-name NAME) the first setup is finished in a browser. podos setup prepares everything that cannot be done remotely, creates no admin token, and prints the address, a one-time setup code (30 minutes, paused after every five wrong attempts, void after 40) and the CA fingerprint. The admin token is shown once, at the end of the wizard. The web UI is served by the HTTPS listener; --web-ui off turns that off. See Web UI. --web cannot be combined with --token-file or --new-admin-token. While the setup is pending, running podos setup --web again issues a new code.

Settings are saved and merged: a flag changes only its own setting. They are saved in settings.json in the data directory.

sudo podos setup --acme-email admin@example.com
sudo podos setup --strict-egress --allow-egress 10.0.5.0/24
sudo podos setup --reset strict-egress

Without --acme-email, a route with tls = "auto" is reported as broken in podos ps and everything else works. Let's Encrypt has only been tested against a test ACME server, not yet against the real service.

Back up the secrets key and the database together; secrets cannot be recovered without the key.

Available After its normal output, podos setup prints a warning on standard error when Docker's firewall drops forwarded packets by default, with the steps that fix it. It also checks incoming packets, recognises ufw and firewalld, and prints the exact commands for each. The exit code does not change, and Podos never changes another firewall. See Next to Docker or another firewall.

podos daemon

podos daemon [flags]

Runs the daemon until it receives SIGINT or SIGTERM. Run it as root, after podos setup. It listens on a Unix socket (podos.sock, mode 0600, root only; root there is an administrator). Available With --listen it also serves the API over HTTPS for remote use with bearer tokens; without it, no TCP port is open. The HTTPS certificate comes from the internal CA, covers the --tls-name names, and is renewed and reloaded without a restart. Plain HTTP is never offered. Available The same address serves the web UI unless --web-ui off. Containers keep running when the daemon stops; when it starts again it finds them. Available The daemon also runs the built-in proxy on ports 80 and 443 (see --ingress).

Flag Meaning
--data-dir DIR Data directory. Default: $PODOS_DATA_DIR, then /var/lib/podos.
--run-dir DIR Runtime directory holding podos.sock. Default: $PODOS_RUN_DIR, then /run/podos.
--listen ADDR:PORT Available Serve the API over HTTPS on this address, for example 0.0.0.0:8443. Default: $PODOS_LISTEN, then the setting saved by podos setup --listen, then off.
--tls-name NAME Available DNS name or IP address clients use for this server. The certificate covers it and other Host names are refused. Repeatable. Default: $PODOS_TLS_NAMES, then the saved setting, then the listen address.
--ingress on|off Available Serve domains through the built-in proxy. Default: the setting saved by podos setup --ingress, then on.
--web-ui on|off Available Serve the web UI on the HTTPS listener. Default: the saved setting, then on. Never served on the Unix socket.
--http-listen ADDR:PORT Available Proxy address for HTTP. Default: the saved setting, then :80.
--https-listen ADDR:PORT Available Proxy address for HTTPS. Default: the saved setting, then :443.
--acme-directory URL Available ACME directory to use, https only. Default: Let's Encrypt production. For example Let's Encrypt staging or a private CA. Flag only; podos setup does not save it.
--acme-ca-file PATH Available PEM file with the only root certificates trusted for the ACME connection, instead of the system roots (a private CA). Use an absolute path. The file must be a regular file, not a symbolic link, owned by root or the daemon's user, and not writable by group or others; its directory must not be writable by group or others either, so a file in /tmp is refused. Flag only.
--system-reserve-memory SIZE Available Memory kept for the system and out of the containers' ceiling, for example 512M or 1G. Default: 10% of the server's memory, at least 256 MiB and at most 2 GiB. Flag only.
--min-free-disk SIZE Available Free space on the data directory's file system below which deploys and image pulls are refused, for example 2G. Default: the larger of 1 GiB and 5% of the file system, at most 10 GiB. Flag only.
--files-memory SIZE Available Size of the memory file system that holds secret files and templates with secrets, for example 64M. Counted inside the system reserve and at most half of it. Default: 2% of the server's memory, at least 16 MiB and at most 256 MiB. Plain files go to the data disk. Flag only. See Limits.
--build-timeout DURATION Available Deadline of one build on this server, for example 20m. Between 1 minute and 6 hours. Default 15m. Flag only.
--build-memory SIZE Available Memory ceiling of the builder, all builds together, for example 2G. At least 256 MiB. Default: half of the server's memory, at least 512 MiB and at most 8 GiB. Flag only.
--build-cache-max SIZE Available Largest size of the build cache, for example 5G. At least 256 MiB. Default 10 GiB. Flag only.
--build-context-max SIZE Available Largest source a build accepts, for example 100M. At least 1 MiB. Default 256 MiB. Flag only.
--build-parallel N Available Builds that run at once, 1 to 8. Default: the number of CPUs, at most 4. Sources are always received in parallel. Flag only.
--build-tool-dir DIR Available Directory searched for buildkitd, buildctl and crun before /usr/local/lib/podos/bin. For development; absolute path; repeatable.
--network-prefix PREFIX Available Interface name prefix of the application networks. For development; default pd.
--network-table NAME Available nftables table name. For development; default podos.
--registry-allow-private HOST:PORT Allow a registry on an internal network. For development; repeatable.
--registry-plain-http HOST:PORT Allow a registry over plain HTTP. For development; repeatable.

Without the two registry flags, registries on internal addresses and plain HTTP are refused. A plain-HTTP registry must also be listed with --registry-allow-private, unless it is a loopback address such as 127.0.0.1:5000.

Available The install script installs a systemd unit that runs podos daemon without flags. The settings then come from podos setup. The flags above marked "flag only", such as the build flags, are not saved by podos setup. To use one, put it in a drop-in file (systemctl edit podos) that clears and sets ExecStart, for example:

[Service]
ExecStart=
ExecStart=/usr/local/bin/podos daemon --build-parallel 2

The unit file itself is replaced on upgrade; a drop-in is kept.

How builds use these limits is described in Build from source.

podos init

podos init [flags]

Writes a starter podos.toml (or podos.yaml) into the application directory. It never overwrites an existing manifest. With a Dockerfile in the directory the service uses build = "."; otherwise you fill in image. With several environments it also writes an override file per environment, holding only comments that show an example.

Flag Meaning
-d, --dir DIR Application directory. Default: the current directory.
-p, --project NAME Project name. Default: the directory name, when it is a valid name.
--environments LIST Comma-separated environments, for example test,prod. Default: a single prod environment.
--format FORMAT toml or yaml. Default: toml.
podos init --project shop --environments test,prod

podos manifest validate

podos manifest validate [flags]

Loads podos.toml, podos.yaml or podos.yml from --dir, with any podos.<environment>.* override files, and reports every problem found. On success it prints what would be deployed in each environment. It works offline and needs no daemon.

Flag Meaning
-d, --dir DIR Application directory. Default: the current directory.
-e, --env NAME Validate one environment. Default: all.
-j, --json Print the resolved manifest as JSON, one line per environment.

Exit code 0 when valid, 1 when problems were found.

podos deploy

podos deploy [flags]

Validates the manifest locally, sends the resolved manifest for --env to the daemon and follows the progress until the release is active or has failed. With several environments declared, --env is required.

Press Ctrl+C to disconnect: the daemon finishes the deployment anyway; check podos ps. Available A build in progress is cancelled on the server.

Available A service with build = "DIR" is built on the server first. The directory is packaged (inside a Git work tree the files Git does not ignore, otherwise every file; then .dockerignore is applied), uploaded, and built with BuildKit from its Dockerfile while the build log is shown. The release uses the image that came back. A failing build stops the deploy and the running release stays. Without a manifest, a directory with a Dockerfile is deployed as service web of a project named like the directory. See Build from source.

Flag Meaning
-d, --dir DIR Application directory. Default: the current directory.
-e, --env NAME Environment to deploy. Required when the manifest declares several.
--socket PATH Daemon socket.
-c, --context NAME Available Server to use. See Connecting to the daemon.
Exit code Meaning
0 The release is active.
1 The release failed or was refused (failed, invalid, manifest problems). Available Also a build that failed. Fix it and deploy again.
2 Usage error.
3 Try again later: daemon unreachable or busy, another deployment in progress, or you disconnected and the outcome is not known yet. Available Also a full build queue or a build that waited too long.

When a deployment fails, the error shows the last lines of the failing container's output. The values of the service's secrets are replaced in those lines on a best-effort basis only: encoded forms, values shorter than 4 characters and partial values are not caught.

Available A service with build is refused when the server has no BuildKit or its crun is older than 1.15 (the message says so; image still works). Available A release is refused when a published port is in use on the server, when tls = "cert:NAME" names a certificate that does not exist or does not cover the domains, or when a domain belongs to another project. The error names the service and the value. See Limits.

podos ps

podos ps [flags]

Lists the containers of the project and environment: service, replica, container ID, release, status, Available ready, restarts, and start time (UTC). A stopped container shows its exit code and reason.

Available READY is yes, starting or no, and - until the daemon has checked the containers once after it started. RESTARTS is the number of consecutive failures before this container. Below the table, podos ps lists the services that are not ok, with the class of their last error, and findings about the project's domains (for example a missing certificate or tls = "auto" without --acme-email).

Flag Meaning
-j, --json Print the daemon's answer as JSON.
-d, --dir, -p, --project, -e, --env, --socket, -c, --context See Choosing the project and environment.

podos logs

podos logs [flags] SERVICE

Shows the output of the containers of SERVICE, merged in time order. Each line starts with the service and replica (web/0); stderr lines are marked with ! after the replica (web/0!).

Flag Meaning
-t, --tail N Lines per replica to start with: 0 to 10000, or all. Default 100. 0 with --follow shows only new lines.
-f, --follow Keep streaming new lines until Ctrl+C, until the containers exit, or until a redeploy replaces them.
--since DURATION Only lines newer than this, for example 10m or 2h.
-r, --replica N Only this replica. Default: all.
--timestamps Show the time of each line (UTC).
--raw Print bare lines, without prefix or cleaning of control characters. For pipes only, never to a terminal.
-d, --dir, -p, --project, -e, --env, --socket, -c, --context See Choosing the project and environment.

Container output is untrusted: control characters are replaced by ? unless you pass --raw. Container output can contain secrets by design; podos logs shows it as the container wrote it.

With --follow, the command ends with exit code 3 when a redeploy replaces the containers it follows; run it again to follow the new ones.

podos logs web --tail 20 --timestamps
podos logs web -f --tail 0
podos logs web --replica 1 --since 10m
podos logs web -p demo -e prod -f -t 20       # the same flags, short forms

podos down

podos down [flags]

Stops and removes all containers of the project and environment and deletes the environment: its releases and its env values and secrets, which cannot be recovered. The project itself is kept. Available It also removes the environment's network, its domains, its published ports and its uploaded certificates. Volume data is kept on the server unless you pass --delete-volumes.

You are asked to type the environment name to confirm, unless you pass --yes. When standard input is not a terminal, --yes is required.

Flag Meaning
-y, --yes Do not ask for confirmation.
--delete-volumes Available Also delete the data of the environment's volumes. It has no short form.
-d, --dir, -p, --project, -e, --env, --socket, -c, --context See Choosing the project and environment.

podos env

Env values are stored per project and environment, in clear text, and used in the manifest as ${env.NAME}. Setting a value creates the project and environment on the server if needed.

podos env set [flags] KEY=VALUE...
podos env list [flags]
podos env unset [flags] KEY...
podos env create [flags]
podos env set LOG_LEVEL=info WORKERS=4
podos env list --env test
podos env unset WORKERS

env list shows name, update time (UTC) and value. Names match [A-Za-z_][A-Za-z0-9_]*, at most 256 characters, and must not start with PODOS_.

Values given as arguments appear in your shell history and in the process list of the machine. Put secrets in podos secret set instead.

Available env create creates the environment in the project and does nothing if it exists. It needs a project-admin or admin token, because a deploy token may only use environments that exist; only an admin creates a project. As root on the local socket you are an admin.

podos env create --project shop --env test

Flags: -d, --dir, -p, --project, -e, --env, --socket, -c, --context; see Choosing the project and environment.

podos secret

Secrets are stored encrypted and are write-only: they cannot be read back through Podos. They reach containers as ${secret.NAME}.

podos secret set [flags] NAME
podos secret list [flags]
podos secret unset [flags] NAME...

secret set reads the value from standard input when it is not a terminal (one trailing newline is removed), or asks for it twice without echo on a terminal. The value is never accepted as an argument or environment variable, and never printed.

podos secret set DB_PASSWORD                  # prompted twice, no echo
podos secret set TLS_KEY < key.pem            # from a file
podos secret list                             # names and update times only
podos secret unset DB_PASSWORD

Flags: -d, --dir, -p, --project, -e, --env, --socket, -c, --context; see Choosing the project and environment.

podos file

Available Files are stored per project and environment and mounted into services with files.NAME in the manifest, read-only. Setting a file creates the project and environment on the server if needed. See Files in containers.

podos file set [flags] NAME PATH
podos file list [flags]
podos file get [flags] NAME
podos file unset [flags] NAME...
podos file set NGINX_CONF ./default.conf       # a plain file
podos file set --secret TLS_KEY ./site.key     # encrypted, never shown again
generate-config | podos file set APP_CONFIG -  # from standard input
podos file list
podos file get NGINX_CONF
podos file unset NGINX_CONF

A change takes effect at the next podos deploy: a release pins the contents of its files.

Flag Meaning
--secret file set: store the file encrypted and never show its content again. It has no short form.
-j, --json file list: print the files as JSON.
--raw file get: print the bytes even to a terminal, without checking them. It has no short form.
-d, --dir, -p, --project, -e, --env, --socket, -c, --context See Choosing the project and environment.

podos cert

Available Uploaded TLS certificates belong to a project and environment. A service uses one with tls = "cert:NAME".

podos cert set [flags] NAME
podos cert list [flags]
podos cert remove [flags] NAME...

cert set uploads the certificate chain (--cert, PEM, leaf first) and its unencrypted private key (--key, PEM) under NAME. The key is sent to the server, stored encrypted and never shown again. The certificate must cover the service's domains when you deploy. It needs permission to write secrets. cert set takes effect at once, without a redeploy.

cert list shows the names, the hosts covered and the expiry, never key material; --json prints it as JSON.

cert remove removes certificates. The routes of services that still use one are not served at once: their HTTPS handshakes fail and podos ps reports the missing certificate; other routes are unaffected. The next podos deploy of such a service is refused until the certificate exists again.

Flag Meaning
--cert FILE cert set: PEM file with the certificate chain, leaf first.
--key FILE cert set: PEM file with the unencrypted private key.
-j, --json cert list: print the certificates as JSON.
-d, --dir, -p, --project, -e, --env, --socket, -c, --context See Choosing the project and environment.
podos cert set shop-cert --cert fullchain.pem --key privkey.pem
podos cert list
podos cert remove shop-cert

podos image pull

podos image pull [flags] REFERENCE

A developer and diagnostic command. Resolves REFERENCE on its registry, downloads the manifest, config and layers into the content store under --root, and verifies every blob against its digest. Anonymous pulls only. It does not talk to the daemon; the daemon pulls images itself during podos deploy. Do not point --root at the daemon's data directory.

Flag Meaning
--root DIR Content store directory. Required; created with mode 0700 if missing.
--platform OS/ARCH[/VARIANT] Platform to pull. Default: Linux on the architecture of this machine.
-j, --json Print the result as one JSON object.
--allow-private HOST:PORT Allow a registry, token realm or redirect target on an internal address. Repeatable.
--plain-http HOST:PORT Allow a registry over plain HTTP. Repeatable.

podos version

podos version [flags]
podos --version
Flag Meaning
--limits Print the limits of this version.
--licenses Print the licenses of the third-party software in this binary.

podos login

Available

podos login [flags] https://HOST:PORT

Connects to a server's HTTPS API, shows the fingerprint of its CA and, after you confirm that it matches what podos setup printed on the server (or what podos ca fingerprint prints there), saves the CA with the address and your token as a named context. From then on the server is verified strictly against that CA. If the CA ever differs, every command fails and nothing is trusted again silently (trust on first use).

The token is read from a prompt without echo, from standard input, or from PODOS_TOKEN. There is no flag for it, so it never appears in a process list. Without a terminal, give --ca-fingerprint.

Flag Meaning
--name NAME Name of the context. Default: the first label of the server's host name.
--ca-fingerprint SHA256:... Fingerprint of the server's CA, for use without a terminal. It must match what the server presents.
--use Make the new context the current one at once. Default: only when there is no current context and no podos daemon answers on this machine's local socket. Otherwise the context is saved and the podos context use hint is printed.
podos login https://server.example.com:8443 --name prod-eu --use

podos logout

Available

podos logout [NAME]

Deletes the token saved in the context NAME (default: the current context). The server address and CA are kept. The token stays valid on the server until it is revoked with podos token revoke.

podos context

Available

podos context list [-j | --json]
podos context use NAME
podos context remove NAME

list shows the contexts and marks the current one with *; tokens are never shown. use makes a context the one used when no --context, PODOS_CONTEXT or manifest context applies. remove deletes a context with its saved token and CA; the token stays valid on the server until revoked. local is built in, means the daemon socket on this machine, and can be selected with use but not removed.

podos whoami

Available

podos whoami [-j | --json] [-c | --context NAME] [--socket PATH]

Asks the selected server which token you are: its name, kind, scope and expiry, and which context and address the answer came from. The token itself is never shown.

podos token

Available Tokens give remote clients access to the HTTPS API. Run these commands as root on the server, or with an admin token. A project-admin token can create tokens inside its own project. See Security model.

podos token create --name NAME [flags]
podos token list [-j | --json]
podos token revoke NAME|ID

create prints the token once on standard output; only its hash is stored, so it cannot be shown again.

Flag Meaning
--name NAME Name of the token. Required; lowercase letters, digits and hyphens.
--kind KIND admin, project-admin, deploy or read. Default: read.
-p, --project NAME Project the token is limited to. Required for every kind but admin.
-e, --env ENV Limit a deploy or read token to this environment of the project.
--secrets-write Let a deploy token set and delete secrets. It has no short form.
--expires DURATION Lifetime, for example 90d, 12w or 36h. Default: never expires.
-c, --context NAME, --socket PATH Server to use.

The kinds:

Kind Can do
admin Everything. Only an admin creates admin tokens.
project-admin Everything in one project except cascading deletes: environments, tokens and all that is in them. Creates tokens inside its own project.
deploy Releases and values in a project, optionally one environment. Secrets only with --secrets-write.
read Read access in a project, optionally one environment.

A deploy token can read its environment's secrets indirectly, through the containers it deploys.

list shows kind, scope, status and last use; neither tokens nor hashes are ever shown. revoke takes the name or ID, never the token itself, and the token stops working at once.

podos token create --name ci-shop-test --kind deploy --project shop --env test --expires 90d
podos token list
podos token revoke ci-shop-test

podos ca fingerprint

Available

podos ca fingerprint [--data-dir DIR] [--socket PATH]

Run as root on the server. Prints the SHA-256 fingerprint of the server's CA, the one podos login asks you to compare. It is public and changes nothing. It works while the daemon runs; it then asks the daemon on its socket.

podos releases

Available

podos releases [flags]

Lists the newest releases of the project and environment with their status, age and, for failed releases, the first line of the failure reason. Secrets in a reason are replaced by ***. Available When a rollout failed and was rolled back automatically, the reason says why.

Flag Meaning
--limit N How many releases to show, newest first, 1 to 1000. Default 20.
--full Show the whole failure reason, not just its first line.
-j, --json Print the releases as JSON.
-d, --dir, -p, --project, -e, --env, --socket, -c, --context See Choosing the project and environment.

Environment variables

Variable Used by Meaning
PODOS_DATA_DIR setup, daemon, ca fingerprint Data directory. Default /var/lib/podos.
PODOS_RUN_DIR daemon, client commands Runtime directory holding podos.sock. Default /run/podos.
PODOS_SOCKET client commands Path of the daemon socket. Selects the local socket.
PODOS_CONTEXT client commands Available Name of the context to use. Beaten by --context and --socket.
PODOS_TOKEN login Available The token to save, instead of a prompt.
PODOS_LISTEN daemon Available HTTPS listen address, as --listen.
PODOS_TLS_NAMES daemon Available Names for the HTTPS certificate, as --tls-name.
XDG_CONFIG_HOME client commands Available Parent of the podos/ directory holding contexts.json. Default ~/.config.