Skip to content

System Architecture & Topology

StackPilot is designed around an autonomous agent-hub model engineered for resilience, isolation, and low operational overhead.

1. Architectural Topology

flowchart TB
    subgraph Browser ["Web Client / Admin Console"]
        UI["SPA Dashboard (Vanilla JS)"]
        Components["Modular UI Engines\n(MetricsEngine, WorkloadFilter, WorkloadTable)"]
        UI --- Components
    end

    subgraph Hub ["StackPilot Central Hub (Node.js / Express)"]
        Router["Express REST API (:8081)\n(CSP Nonce, Double-Submit CSRF, Helmet)"]
        AuthStore["Auth Store\n(Bcrypt / PBKDF2 + Forward-Auth)"]
        TokenStore["Agent Token Store\n(0600 Permissions, Atomic Persistence)"]
        ConfigSource["Config Store\n(Default Overlays)"]
        TemplateEngine["Template Engine\n(In-Memory Cached Templates)"]

        Router --> AuthStore
        Router --> TokenStore
        Router --> ConfigSource
        Router --> TemplateEngine
    end

    subgraph Node ["Managed Host (Rootless Linux Host)"]
        subgraph Agent ["StackPilot Agent (:9091)"]
            PyAgent["Python ZipApp (:9091)\n(TLS + Pinned SHA-256 Fingerprint)"]
            Watchdog["Self-Heal Systemd Timer\n(1-min Active Check + Critical Monitor)"]
        end
        subgraph Systemd ["Systemd User Manager"]
            Quadlets["Quadlet Units\n(*.container, *.pod, *.volume)"]
            Journald["systemd-journald\n(Structured Workload Logs)"]
        end
        subgraph Podman ["Podman Runtime"]
            Containers["Rootless Containers & Pods"]
        end
        PyAgent <--> Systemd
        PyAgent <--> Podman
        Systemd --> Podman
    end

    Browser <== "HTTPS / REST + Nonce CSP" ==> Hub
    Hub <== "mTLS + X-Agent-Token" ==> Node

2. Core Architectural Tenets

1. Rootless by Default

All workloads, agent collectors, and self-heal timers run within unprivileged user namespaces. Root privilege is never required for normal operations.

2. First-Class Systemd Native (Daemonless Quadlets)

Instead of maintaining a continuous container management daemon, StackPilot compiles definitions into native systemd unit files (.container, .pod, .volume, .network). Systemd manages supervision, cgroups resource limits, journal logging, and restarts.

3. Zero-Dependency Agent

The StackPilot agent (stackpilot_agent.pyz) is distributed as a single Python ZipApp utilizing only the Python 3 standard library (http.server, urllib, ssl, json, subprocess). No pip, no virtual environments, and no package manager access required on managed hosts.

4. Decoupled Agent-Hub Topology

Managed nodes operate autonomously. If the Central Hub goes offline, containers, health checks, self-heal timers, and systemd units continue running unaffected.

5. Deterministic Template Interpolation

Host setup, agent installation, and Quadlet conversions are driven by static templates with strict snapshot-tested verification, eliminating script drift.