Components

Soul Stack is four binaries with distinct roles: two daemons (Keeper and Soul) and two operator tools (soulctl and soul-lint).

Component	Role
Keeper	The central server: registries, rendering and delivery of Destiny, RBAC, audit. A stateless cluster over shared PostgreSQL + Redis. Serves the built-in operator web UI at /ui.
Soul	The agent on a managed host: applies Destiny, in pull (daemon) and push (one-shot over SSH) modes.
soulctl	The operator’s client CLI — a thin wrapper over the Operator API.
soul-lint	An offline linter for Destiny / scenarios / services / plugin manifests.

How they fit together

At the center is Keeper: one or several stateless instances over shared PostgreSQL (cold state) and Redis (presence, coordination). Keeper holds the registries, renders Destiny, and manages the souls over a long-lived gRPC stream on top of mTLS.

On every managed host runs Soul: an agent that initiates the connection to Keeper itself (no inbound ports need to be opened on the hosts), receives the rendered tasks, and applies them through core modules. The same binary also runs in push mode (one-shot over SSH, with no permanent daemon).

The operator works through the Operator API (HTTP/OpenAPI). On top of it sits soulctl: a thin CLI for the same endpoints (registering hosts, running scenarios, inspecting incarnations), plus a built-in web UI that Keeper serves at /ui out of the box (no separate deployment). Before any configuration is applied, soul-lint statically validates Destiny, scenarios, services, and plugin manifests — on a workstation or in CI, executing nothing.

flowchart TB
    Op["operators<br/>soulctl · OpenAPI / MCP"] --> K
    K["Keeper<br/>Operator API · render · registries<br/>RBAC · audit · stateless cluster"]
    K --> PG[("PostgreSQL — state")]
    K --> R[("Redis — presence, coordination")]
    S1["Soul"] -->|"gRPC bidi-stream over mTLS<br/>connection initiated by Soul"| K
    S2["Soul"] --> K
    S3["Soul"] --> K
    S4["Soul"] --> K
    SL["soul-lint — offline, next to the operator: validates artifacts before applying"]

Each component is covered in detail via the links in the table above.