Installation

Soul Stack ships as four binaries: keeper (the central server), soul (the on-host agent), soulctl (the operator’s client CLI) and soul-lint (an offline linter). Pick the installation method that fits your infrastructure.

External infrastructure is on you

Packages and releases carry only the binaries, systemd units and example configs. Soul Stack does not package PostgreSQL, Redis or Vault — these are external components that you stand up and operate yourself.

• PostgreSQL — the Keeper cluster’s only cold store: registries of agents and operators, the service catalog, logs.
• Redis — the heartbeat cache, leases on agent identifiers, coordination between Keeper instances.
• Vault — the PKI for issuing agents’ mTLS identity and secret storage (the PostgreSQL DSN, the Redis password, the operator-token signing key).

The required stack is PostgreSQL + Redis + Vault (all three; Keeper checks each on startup and won’t start without any one of them). All three must be reachable over the network from the host where Keeper runs. Version requirements, mandatory parameters and the modes of each component are in Infrastructure prerequisites; a demo scenario for standing them up is in Quick Start → What you’ll need.

Which method to choose

deb / rpm

The primary production method. Prebuilt packages for Debian/Ubuntu and the RHEL family. They install the binary, a systemd unit, an env file and an example config; upgrades don’t overwrite your working config.

When: a production install on Linux hosts with a package manager, managed through systemd.

Details: From deb/rpm packages.

Binary releases

A prebuilt static binary with no package manager. You create the systemd unit, the user and the directories by hand.

When: containers, immutable images, distributions without deb/rpm, manual control over the layout.

Details: From binary releases.

From source

Building from Go sources via go.work + make build.

When: development, contribution, custom builds, platforms without prebuilt artifacts.

Details: From source.

What each artifact carries

Binary	Where it lives	How it’s installed
keeper	central node (1+ instance)	soul-stack-keeper package / release / build
soul	every managed host	soul-stack-soul package / release / build
soul-lint	operator workstation, CI	soul-stack-soul-lint package / release / build
soulctl	operator workstation	release / build (not shipped as a separate deb/rpm package)

The soul-stack-keeper and soul-stack-soul packages carry the daemon + systemd unit + env file + example config. soul-stack-soul-lint is just the CLI, with no daemon or config. soulctl is the operator’s client tool, installed from the release binary or by building it.