Skip to content

StackPilot

Next-Generation Multi-Host Container Orchestration Powered by Rootless Podman & Native Systemd Quadlets

What is StackPilot?

StackPilot is an agent-hub orchestration platform engineered for Linux container hosts and homelabs. Rather than maintaining a heavy, privileged container daemon (like Docker Engine), StackPilot compiles declarative container definitions directly into native systemd user services via Podman Quadlets.

Systemd natively manages container lifecycles, dependencies (After=, Wants=), resource limits via cgroups v2, journal logging, and automatic self-healing restarts.

flowchart LR
    A["Central Hub\n(Dashboard & REST API)"] <== "mTLS + Bearer Tokens" ==> B["Node 1 (Agent)\nRootless Podman + Systemd"]
    A <== "mTLS + Bearer Tokens" ==> C["Node 2 (Agent)\nRootless Podman + Systemd"]
    A <== "mTLS + Bearer Tokens" ==> D["Node 3 (Agent)\nDocker Elevated Mode"]

Key Highlights

  • 🛡️ Rootless by Default: Workloads execute inside unprivileged user namespaces. Root privilege is never required, completely eliminating daemon breakout risks.
  • ⚡ Zero-Dependency Agent: The agent runs as a single ~15MB Python 3 standard library ZipApp (stackpilot_agent.pyz). No pip, no virtual environments, and no package manager dependencies required on managed hosts.
  • 🔄 Autonomous Self-Healing: Nodes run an independent systemd timer watchdog every 60 seconds. Workloads and agents heal and restart automatically even if the Central Hub is offline.
  • 🔒 Enterprise-Grade Security: Pinned TLS CA certificates, SHA-256 cert fingerprint registration, Double-Submit CSRF protection, Dynamic CSP Nonces, and canonical realpath traversal jails.
  • 🖥️ Ultra-Responsive UI: Clean vanilla SPA architecture with instant search filtering, sortable tables, CPU/RAM mini-bars, and multi-host aggregation.

Quick Navigation

- :material-rocket-launch: **[60-Second Quickstart](getting-started/quickstart.md)** --- Deploy the Central Hub and onboard your first managed Linux host with a single curl command. - :material-scale-balance: **[StackPilot vs Portainer & Dockge](getting-started/comparison.md)** --- Understand the architectural advantages of rootless systemd Quadlets over root Docker daemons. - :material-server-network: **[System Architecture](architecture/overview.md)** --- Deep dive into the Agent-Hub topology, Quadlet compilation, and rootless user lingering. - :material-shield-lock: **[Security & Threat Model](security/threat-model.md)** --- Explore our defense-in-depth security model, TLS pinning, and reverse proxy forward-auth.