Capabilities

A capability is a versioned token, such as service.systemd.v1, saying a host can run a particular resource implementation. rivet facts probes for the tools each implementation needs and lists only the capabilities that are available:

rivet facts --local | jq '.target.capabilities'

A compiled catalog records the capabilities it actually uses. Compilation fails if the facts don’t advertise them. Before applying, the runner checks again against freshly probed host facts. So a host missing systemd or apt is caught before any change is made, not halfway through a run.

Capability versions are exact: a host advertising xyz.v2 does not satisfy a catalog that needs xyz.v1.

Built-in capabilities

Capability	Needed for
`file.native.v1`	File: regular files and directories.
`file.complete.v1`	File: ownership, symlinks, `create_parents`, `replace_type`, and `backup`.
`file.ownership.nss.v1`	File: `owner` or `group` given as a name rather than a number.
`file.validate.v1`	File: `validate` commands.
`exec.process.v1`	Exec.
`service.systemd.v1`	Service with the systemd backend.
`refresh.journal.v1`	Systemd daemon reloads: services with `daemon_reload = "auto"`, timers, and mounts that are persistent or absent.
`package.apt.v1`	Package with the apt provider.
`package.dpkg.v1`	Package with the dpkg provider.
`user.shadow.v1`	User.
`group.shadow.v1`	Group.
`group_membership.shadow.v1`	Group membership.
`timer.systemd.v1`	Timer.
`ssh_key.native.v1`	SSH authorized key.
`mount.util_linux.v1`	Mount.

Plugins declare their own capabilities, which appear in the same list when the plugin is installed on the host.

Compiling without a host

rivet validate without --facts uses a fixed Ubuntu 24.04 baseline that advertises every built-in capability. The repository’s examples/*/target.json files are similar, but list only the capabilities their example needs. Both are useful for checking configuration on a laptop, but neither is bound to a real host. Compile against facts collected from the host before applying.