A quick reference of Soul Stack terms — one or two lines per term with a link to the section where it is covered in more detail. The full mental model is in Concepts.
Soul Stack uses a soulful metaphor. The roles behind the names are the familiar ones from master/agent systems; the system and the documentation use only our terms.
| Term | What it is |
|---|
| Keeper | The central server: holds the registries and the service catalog, renders and delivers Destiny, keeps the audit log. Scales horizontally over shared PostgreSQL and Redis. See Keeper. |
| Soul / Souls | The agent on a managed host — a single Go binary, soul. Applies Destiny; works in pull and push modes. See Soul. |
| Destiny | A declarative description of a host’s desired state — a set of idempotent steps core.<module>.<state>. See DSL → Destiny. |
| Soulprint (Prints) | Typed facts about the host (OS, kernel, CPU, memory, network) collected by the agent. In expressions — soulprint.self.<path>. See Soul → Soulprint. |
| Essence | Parameters and secrets bound to a host or group. Secrets are resolved through Vault on the Keeper side and masked in the output. See DSL → Essence. |
| Coven | A stable logical tag for a group of agents (cluster, project, environment, data center). The basis for targeting, RBAC, and routing. A host’s volatile role is not a Coven. See Concepts. |
| Traits | Operator-set key→value labels on an incarnation: a scalar (namespace: dba-ns) or a list (owners: [alice, bob]). A separate axis alongside the flat Coven — organizational attributes (owner, product, namespace), not a collected host fact. Source of truth is incarnation.traits, projected into the member hosts’ souls.traits; in targeting — soulprint.self.traits.<key>. |
| Term | What it is |
|---|
| SID | Soul ID. The agent’s identifier, equal to the host’s FQDN — stable, human-readable, and gives automatic deduplication on reinstall. See Security → Identity. |
| SoulSeed | The agent’s mTLS identity artifact: a certificate + private key pair. Issued by Keeper and rotated regularly; the private key is generated on the host and never leaves it. See Security → Identity. |
| Archon | A Soul Stack operator — a person or a machine identity. The first one is issued by the keeper init command; the rest go through the Operator API with an RBAC check. See Operators → Archons. |
| AID | Archon ID. The operator’s identifier — an ASCII string matching the pattern ^[a-z0-9][a-z0-9._@-]{1,127}$ (for example archon-alice, alice@corp.com, uid-4815, ops-team). See Operators → Archons. |
| Synod | A group of operators that bundles a set of roles — simplifies granting the same access to a team. An operator’s effective roles = direct ∪ roles via all their Synods. See Operators → Synod and Purview. |
| Purview | The scope boundaries of node visibility for a role: which Souls and incarnations an operator sees and can touch. Fail-closed: an empty Purview → an empty list. See Operators → Synod and Purview. |
| mTLS | Mutual TLS authentication between an agent and Keeper over a gRPC bidirectional stream. The authority for an agent’s identity is the connection’s peer certificate. See Security → Transport. |
| Term | What it is |
|---|
| Service | The type: a git repository with scenarios, default parameters (Essence), and a state schema. Versioned by a git ref (a tag or a branch). See Concepts → Service and Incarnation. |
| Incarnation | A runtime instance of a service: a concrete application of the type to a set of hosts, with its own spec (what was ordered), state (what was reached), and status in PostgreSQL. See Concepts → Service and Incarnation. |
| scenario | An operation on an incarnation’s state (create / add_user / restart / …): a full set of Destiny tasks plus orchestration (on: / where: / serial: / apply:). The scenario↔destiny boundary is a recommendation. See DSL → Scenario. |
| Voyage | A unified batch run: apply a scenario to a set of incarnations (kind: scenario) or run a module on a set of hosts (kind: command). Batch parameters, concurrency, deferred start, on-failure behavior. See Guides → Orchestration. |
| Cadence | A schedule that spawns an ordinary Voyage on a timer: interval or cron, with an overlap policy (skip / queue / parallel). Outlives runs as a separate entity. See Configuration → keeper.yml. |
| core module | A built-in Destiny step of the form core.<module>.<state> (for example core.pkg.installed). Soul-side ones apply on the host, Keeper-side ones on the server. Catalog — Modules. |
| state_schema / migration | The incarnation.state structure is versioned by the state_schema_version field. When the shape of the state changes, the service author describes a migration — a pure function “old state → new state” executed on the Keeper side. See DSL → State migrations. |
| Term | What it is |
|---|
| pull | The agent-daemon mode: soul initiates a long-lived connection to Keeper over mTLS itself and waits for jobs. See Soul → Two modes. |
| push | One-shot application with no agent installed: Keeper delivers Destiny over SSH to the host (the keeper.push module). The same set of modules as in pull. See Soul → Two modes. |
| Reaper | A Keeper background task: cleans junk out of the registry (expired onboarding records, zombie records, old seeds, old audit entries). One worker in the cluster; the leader is elected via a Redis lease. See Configuration → keeper.yml. |
| Operator API | The operator’s primary interface — OpenAPI over HTTP (plus a built-in MCP). The soulctl CLI is a thin wrapper over it. The spec is served at the /docs route; the API root is /v1. See Components → soulctl. |