Core module catalog

A core module is the unit of work applied by a single Destiny or Scenario step. Core modules are compiled statically into the binaries (Soul-side into soul, Keeper-side into keeper): no separate installation, the module version equals the binary version. Custom modules plug in as separate plugin binaries over gRPC and are not covered here.

Name form

A step addresses a module and its state in the form core.<module>.<state>:

- name: Install nginx package
  module: core.pkg.installed
  params:
    name: nginx

• core.<module> — the module name in the registry (for example core.pkg, core.file).
• <state> — the desired state (installed / present / running) or a verb (run / shell / probe / fetched / extracted / read). Verb forms use the same machinery, just without the declarative “converge to a state” semantics — they do something or read a fact.

Idempotency

Every declarative state is idempotent: the module first checks the host’s current state and changes it only when it differs from the desired one. A step reports changed=true (state changed) or changed=false (already matched).

The changed status is a signal for dependencies between steps (for example, “restart the service only if the config changed” via onchanges:). More in the Destiny section.

Verb modules work differently:

• read-probe (core.http.probe, core.augur.fetch, core.vault.kv-read) — always changed=false by construction: a read never changes the host.
• command (core.exec.run, core.cmd.shell) — changed=true by default (the “execute” verb), lowered by the creates / unless / onlyif guard parameters.
• core.service.restarted — always changed=true on purpose: a restart is requested explicitly.

Execution side: Soul-side and Keeper-side

Side	Where it runs	How it’s addressed
Soul-side	On the managed host by the soul agent. Applied identically in pull (daemon) and push (oneshot).	on: omitted, or Coven labels.
Keeper-side	On the server in the keeper process. Work with the registries / cloud / Vault, not the host filesystem.	on: keeper (required — otherwise a validation error).

Soul-side core modules

Grouped by purpose:

Module	What it does	States / verbs
Packages and repositories
core.pkg	OS packages via the native package manager (apt / dnf / yum / apk).	installed · absent · latest
core.repo	OS package repository (with a GPG key for apt).	present · absent
Files
core.file	A file with content / from a template / a directory / deletion.	present · absent · rendered · directory
core.line	In-place line editing of a file (lineinfile).	present · absent
core.archive	Extracting archives (tar / tar.gz / tar.bz2 / zip).	extracted
Services and processes
core.service	OS service via systemd / openrc / sysv.	running · stopped · restarted · enabled
core.exec	A command directly via exec() — no shell.	run
core.cmd	A shell string via sh -c (pipes, redirects).	shell
core.cron	Cron jobs via /etc/cron.d/.	present · absent
Users and groups
core.user	Local OS users.	present · absent
core.group	Local OS groups.	present · absent
System
core.mount	Mount points and /etc/fstab.	present · absent · mounted · unmounted
core.sysctl	Kernel parameters (vm.* / kernel.* / net.*).	present · applied
core.firewall	A single firewall rule (ufw / firewalld).	present · absent
Network and external data
core.git	Cloning / updating a git repository.	cloned · pulled
core.url	Downloading a file by URL (checksum verification).	fetched
core.http	Read-probe HTTP (health check / readiness).	probe
core.augur	Read-probe of live access to an external system.	fetch
Utility
core.noop	No-op / barrier anchor: does nothing, always succeeds with no change. A join point for several preceding steps (via register.*), or a placeholder / carrier of an output: projection.	run

core.noop is changed=false by construction (like the read-probes): params: has no schema (anything is ignored). Its purpose is to be a barrier anchor (a task that references register.* of several predecessors gives a point where they all complete) and an empty step that carries output:.

Keeper-side core modules

Dispatched with on: keeper. They run on the server and work with the registries / cloud / Vault.

Module	What it does	States / verbs
core.soul.registered	Binding a host (SID) to the registry’s Coven labels.	registered
core.cloud (addressed as core.cloud.created / .destroyed / .resized)	Creating / deleting / resizing cloud instances via a provider driver.	created · destroyed · resized
core.choir.present	A host’s membership in an incarnation’s Choir.	present · absent
core.vault.kv-read	Reading a secret from Vault KV (v1/v2) with an audit event.	read

A note on core.cloud: the operator flow is available — Cloud-Provider and Cloud-Profile are registered through the Operator API (REST /v1/providers, /v1/profiles, MCP parity, web UI) under the provider.* / profile.* RBAC with an audit log. Still on the roadmap: ready-made soul-cloud-* drivers — they aren’t part of the base distribution yet, and a provider is served by its own CloudDriver plugin. More in core.cloud.

Secure defaults

Some modules are built on secure-by-default + explicit opt-out: safe behavior by default, with any loosening behind a separate explicit flag that the operator sees in the apply result (the warnings field).

• core.url / core.http — https:// only by default, an SSRF guard, TLS chain verification; lifted by the allow_http / allow_private / insecure_skip_verify flags.
• core.url — checksum verification before the file appears at the target path.
• core.repo — gpg_check is on by default; an http:// mirror and disabled verification both emit a mandatory warning.
• core.firewall — never touches the default policy and never enables the firewall as a whole (so it can’t cut off management of the host).
• core.archive — protection against zip-slip / zip-bomb, and masking of setuid/setgid during extraction.

Each per-module page has a Security section with the concrete invariants.

What’s next

• Destiny — how to assemble steps into the desired state of a single host.
• Scenario — orchestration across a cluster (on: / where:).
• Essence — where parameter values come from.