cardinal v2.0.3
Philosophy

Design principles, not feature checklists.

Six ideas explain why there is no daemon, why the binary is 5 MB, and why security is on before you ask for it. Everything on this site — and in the codebase — traces back to one of them.

01

What isn't running can't break.

No daemon, no dockerd, no hidden service. cardinal is a short-lived CLI that talks to the kernel when you invoke it — and nothing else exists in between. When you are not using cardinal, there are no processes to crash, no sockets to secure, no memory to leak, and no orphaned background workers to babysit.

In practice

  • cardinal run is a short-lived process: it sets up namespaces, execs the container, and exits.
  • cardinal ps reads container state files directly — no daemon is needed to answer.
  • Nothing listens on a port while you are not using cardinal; idle is truly idle.
  • The only persistent piece is the opt-in systemd supervisor, and only for containers you explicitly marked --restart always.
02

Size is a feature.

One ~5 MB static binary with zero runtime dependencies. Every kilobyte of code is potential attack surface, memory pressure, and boot time. Container runtimes got heavy by accumulating features as separate products; cardinal stays small by keeping the core tight and shipping the extras as built-in commands.

In practice

  • A single static Go binary (~5 MB) — copy it onto a fresh VPS and it works.
  • No dockerd, no containerd, no client/server split, no system components to install.
  • Less code means fewer CVEs and a smaller review surface for your security team.
  • Starts in milliseconds — there is no daemon to warm up before your first command.
03

The kernel is the API.

No middleware layer inventing its own reality. cardinal uses the primitives a sysadmin already knows — unshare, pivot_root, overlayfs, cgroups v2, iptables — and exposes them directly. What you see on the host is what actually happens: real processes, real bridges, real firewall rules.

architecture · what actually runs 
cardinal run -d
  ├─ unshare --fork --pid --mount --net --uts --ipc cardinal init <id>
  │   └─ cardinal init → pivot_root to overlay → /proc + eth0 → exec CMD
  └─ cardinal console-serve <id>   (only when detached: logs + attach)

In practice

  • Each container is unshare + pivot_root into an overlay rootfs, then exec of your command.
  • Container processes are visible to ps aux — no virtualization boundary hiding them.
  • Networking is real: ip link show cardinal0 shows the bridge, iptables -t nat -L shows the DNAT rules.
  • cardinal stats reads cgroups v2 directly — the numbers are the kernel's numbers.
04

Persistence is a choice.

Containers die cleanly. Restart behaviour is an explicit decision — <code>no</code>, <code>on-failure</code>, or <code>always</code> — never a hidden service deciding for you. The supervisor is installed only when you opt into auto-start, and when you say stop, it stops.

In practice

  • --restart no (default) — one-shot: it runs, it exits, it is gone.
  • --restart on-failure — retry with backoff and a crash-loop budget (--restart-max-attempts).
  • --restart always — the systemd supervisor takes over and brings it back after reboots and crashes.
  • cardinal bootstrap --install is an explicit command — nothing persistent is installed until you choose it.
05

Secure by default, not after the incident.

The safe configuration is the default configuration. Seccomp is on, AppArmor is on, dangerous capabilities are dropped, privilege escalation is blocked — out of the box. Security is not a checklist item you reach at the end of a deployment; it is the starting point.

In practice

  • A default seccomp profile blocks 30+ dangerous syscalls: mount, ptrace, reboot, bpf, init_module and more.
  • A default AppArmor profile (cardinal-container) restricts host path access.
  • The capability set is minimal and Docker-compatible; SYS_ADMIN and SYS_MODULE stay dropped.
  • One flag gets you further hardening: --isolated (network segmentation), --readonly, --no-new-privs.
  • Backups can be encrypted with AES-256-GCM — key management included.
06

Capabilities are features, not products.

When you outgrow one container, you should not have to install a second product. Clusters, serverless, backups, audit logging — all live in the same binary, behind the same CLI. One install, one update, one command tree to learn, no version skew between components.

In practice

  • cardinal cluster init / join — multi-node orchestration, no extra agent.
  • cardinal service scale web 5 — replicated services with rolling updates and service discovery.
  • cardinal fn deploy — serverless functions with auto-scaling and scale-to-zero.
  • cardinal backup enable — scheduled, encrypted backups with retention.
  • cardinal serve — a Docker-compatible HTTP API for existing tooling.