Documentation

Everything you need to run containers.

From first install to multi-node clusters and serverless functions — the full cardinal reference, in one place.

Quick start

Install, pull an image, and run your first container. cardinal needs a Linux host with unshare, nsenter, ip, iptables, mount, pgrep, PID/Mount/Net/UTS/IPC namespaces and overlayfs.

quick start

cardinal pull nginx:alpine
cardinal run -d -n web -p 8080:80 nginx:alpine
cardinal ps
curl http://localhost:8080
cardinal logs web
cardinal stop web && cardinal rm web

Installation

The universal installer works on any Linux distribution. Native packages are also available for Debian/Ubuntu (.deb + APT repo), Fedora/RHEL (.rpm), Arch (.pkg.tar.zst), Alpine (.apk), Snap, and portable AppImages for desktop Linux.

universal installer

curl -fsSL https://raw.githubusercontent.com/animesao/cardinal/main/install.sh | sudo bash

debian / ubuntu (APT)

curl -fsSL https://raw.githubusercontent.com/animesao/cardinal/main/scripts/install-apt.sh | sudo bash

Update anytime with cardinal update — it replaces the binary in place.

Image commands

Pull, search, list, remove, and verify OCI images from Docker Hub or any registry.

images

cardinal pull alpine                 # pull image
cardinal pull nginx:alpine           # with tag
cardinal search nginx                # search Docker Hub
cardinal images                      # list local images
cardinal verify nginx:alpine         # verify digests
cardinal rmi nginx:alpine            # remove image

Build & publish

Build images from a Dockerfile, publish them to a registry, and move them between hosts.

build & push

cardinal build -t myapp:v1 .                    # build from a Dockerfile
cardinal build -t myapp:prod -f Dockerfile.prod --build-arg VERSION=1.0 ./src
cardinal login registry.example.com                 # save registry credentials
cardinal push myapp:v1
cardinal push registry.example.com/team/myapp:v1    # to a specific registry

transfer & auth

cardinal export myapp:v1 -o /data/images/myapp-v1.tar.gz
cardinal import /data/images/myapp-v1.tar.gz
cardinal logout registry.example.com

cardinal build handles the common Dockerfile instructions — FROM, RUN, COPY, WORKDIR, ENV, CMD, HEALTHCHECK — including multi-stage builds with COPY --from=.

Container lifecycle

Create, stop, start, rename, and inspect containers — or commit a container to a new image.

lifecycle

cardinal run --rm alpine echo hi                 # one-shot
cardinal run -d -n web -p 80:80 nginx            # detached
cardinal run -i -t alpine sh                     # interactive
cardinal ps -a                                   # list all
cardinal stop web                                # stop (files stay mounted)
cardinal start web                               # start stopped
cardinal restart web                             # restart
cardinal rename web web-new                      # rename
cardinal set web --memory 2g --cpus 4            # change params
cardinal set web --restart always                # auto-restart
cardinal rm -f web                               # force remove
cardinal commit web my-image:v1                  # image from container
cardinal system df                               # disk usage
cardinal info                                    # system info

Logs, attach & filesystem

Stream logs, attach to a running container's stdio, browse the overlay filesystem even after it stops, and copy files in or out.

logs & exec

cardinal logs web                                # current run
cardinal logs --previous web                     # previous run
cardinal logs -f web                             # follow
cardinal attach web                              # recent output + live stdio
cardinal exec web cat /etc/hostname              # run command inside
cardinal exec -i -t web /bin/sh                  # interactive shell
cardinal console web                             # auto-detect shell
cardinal top web                                 # processes inside

filesystem browser

cardinal fs ls web /etc/nginx
cardinal fs cat web /etc/nginx/conf.d/default.conf
cardinal fs tree mc-server /data --max-depth 2
cardinal fs find web --name "*.conf" --grep "server_name"

cardinal cp app.py web:/app/                    # host → container
cardinal cp web:/etc/nginx/nginx.conf .         # container → host

Monitoring & events

Live resource usage, per-container process lists, and a stream of lifecycle events.

monitoring

cardinal stats                       # CPU / memory / I/O (cgroups v2)
cardinal stats --no-stream web       # single sample, then exit
cardinal top web                     # processes running inside
cardinal inspect web                 # full container state as JSON
cardinal events                      # stream lifecycle events
cardinal events --since "2026-01-01 00:00:00"

Networks & ports

Beyond the built-in cardinal0 bridge, create custom networks — and add or remove port mappings on a running container without recreating it.

custom networks

cardinal network create --subnet 10.20.0.0/24 appnet
cardinal network ls
cardinal network inspect appnet
cardinal run -d --network appnet -n api myapp:v1
cardinal network rm appnet

dynamic ports

cardinal port web                  # show current mappings
cardinal port add web 8080:80        # add a mapping on a running container
cardinal port add game 27015:27015/udp
cardinal port remove web 8080

Dynamic port changes apply iptables DNAT rules instantly — no restart — and persist in the container's state across restarts.

Volumes

Named volumes keep data outside the container's writable overlay and survive rm.

volumes

cardinal volume create app-data
cardinal volume ls
cardinal volume inspect app-data
cardinal volume prune                 # remove volumes no container uses
cardinal volume rm app-data           # destructive

Compose

Declare multi-container stacks in cardinal.toml and drive them with cardinal up / cardinal down.

cardinal.toml

[container.web]
image = "nginx:alpine"
ports = ["80:80", "443:80"]
volumes = ["./html:/usr/share/nginx/html"]
restart = "always"

[container.db]
image = "postgres:16"
ports = ["5432:5432"]
env = { POSTGRES_PASSWORD = "secret", POSTGRES_DB = "myapp" }
volumes = ["pg_data:/var/lib/postgresql/data"]
restart = "always"

compose commands

cardinal up              # create/start all
cardinal up web          # start only web
cardinal down            # stop/remove all
cardinal down -a         # remove ALL containers

Backups

Schedule automatic backups of a container's writable overlay and named volumes. Archives can be encrypted with AES-256-GCM and verified with checksums.

backups

cardinal bootstrap --install                            # supervisor for schedules
cardinal backup enable minecraft --interval 6h --retention 14
cardinal backup status minecraft
cardinal backup list
cardinal backup create minecraft                           # manual backup
cardinal backup verify FILE.tar.gz                         # verify archive
cardinal backup disable minecraft

Cluster

cardinal clusters nodes over HTTP gossip with a leader/worker model. Services scale across nodes, roll out updates, and are discovered through a built-in DNS server.

cluster

# leader
cardinal cluster init --name prod --bind 0.0.0.0 --port 7946 --api-port 2375 --serve

# worker
cardinal cluster join 10.0.0.1:7946 --bind 0.0.0.0 --port 2375 --serve

cardinal cluster ls

# services
cardinal service create --name web --replicas 3 --port 80:80 nginx:alpine
cardinal service scale web 5
cardinal service update web --image nginx:1.25
cardinal service rm web

From inside any container, services resolve as web.svc.cluster.local with round-robin load balancing across replicas.

FaaS / serverless

Deploy images as serverless functions with warm replicas, per-invocation timeouts, and scale-to-zero after an idle window.

serverless

cardinal fn deploy --name hello --port 8080 --timeout 30 --idle 300 myfunc
cardinal fn call hello --data '{"name": "cardinal"}'
cardinal fn ls
cardinal fn rm hello

Docker-compatible API

cardinal serve exposes a Docker-compatible REST API, so existing tooling — Portainer, VS Code Dev Containers, CI runners — talks to cardinal without changes.

cardinal serve

cardinal serve                                # 127.0.0.1:2375, loopback only
cardinal serve -H 0.0.0.0 -p 2375 --token "$CARDINAL_TOKEN" -d
# TLS for external access (a Bearer token is still required)
cardinal serve --tls-cert /etc/cardinal/server.crt --tls-key /etc/cardinal/server.key

External binds require a Bearer token (--token or CARDINAL_TOKEN); CARDINAL_HOST overrides the bind address and port.

See the full Docker API reference — every endpoint with curl examples — or start the API as a service with cardinal serve on.

Security

cardinal is hardened out of the box: a default seccomp profile blocks 30+ dangerous syscalls, AppArmor profiles can be applied per container, devices are restricted, and --isolated segments containers from each other on the network.

security flags

cardinal run -d --seccomp-profile ./profile.json nginx:alpine
cardinal run -d --apparmor-profile my-profile nginx:alpine
cardinal run -d --isolated nginx:alpine
cardinal run -d --encrypted-backup --audit-log nginx:alpine

Diagnostics

Read-only host checks that verify everything cardinal needs to run — no packages installed, no containers started or stopped.

doctor

cardinal doctor            # host / runtime prerequisites
cardinal doctor --strict   # warnings count as failures
cardinal security check    # security posture of the host

System & updates

Cleanup, self-update, and the systemd supervisor that keeps containers and backups alive.

system

cardinal system prune                  # remove unused containers and images
cardinal update --check                # is there a newer release?
cardinal update                        # self-update (checksum verified)
cardinal bootstrap --install           # install cardinal-bootstrap.service
cardinal bootstrap --remove
cardinal supervisor                    # restart + scheduled-backup daemon

The bootstrap supervisor is what powers --restart always recovery and scheduled backups. Shell completion for bash, zsh, fish and PowerShell is built in:

shell completion

cardinal completion bash | sudo tee /etc/bash_completion.d/cardinal > /dev/null
cardinal completion zsh > "${fpath[1]}/_cardinal"
cardinal completion fish > ~/.config/fish/completions/cardinal.fish

Run options

The most common flags for cardinal run.

Flag	Description
`-d`	Detach (background)
`-n`	Container name
`-p`	Port mapping `host:container`
`-v`	Volume mount `src:dst` (`:ro`/`:rw`)
`-e`	Environment variable (repeatable)
`-i` / `-t`	Interactive / allocate TTY
`--rm`	Auto-remove on exit
`--restart`	`no`, `always`, `on-failure`, `unless-stopped`
`--memory` / `--cpus` / `--disk`	Resource limits
`--healthcheck-*`	Health check command, interval, retries, timeout
`--startup`	Startup script (inline or `@file`) — overrides CMD
`--isolated`	Network segmentation from other containers