Installing from source

Building from Go sources — for development, contribution, custom builds and platforms without prebuilt artifacts. If you don’t need to modify the code, use the packages or the binary releases.

Requirements

Tool	Why
Go 1.26+	compiling all modules (the version is pinned in `go.work`)
`make`	build and check targets (`make build` / `make test`)
`git`	cloning the repository

The exact toolchain version is in the repository root’s go.work (the go directive). If your go version is lower, update Go, otherwise the build will fail on the toolchain check.

Repository layout

The code is organized as a Go workspace (go.work) of several modules. The binaries are built from:

keeper/cmd/keeper → keeper
soul/cmd/soul → soul
soulctl/cmd/soulctl → soulctl
soul-lint/cmd/soul-lint → soul-lint

The remaining modules (proto, proto/plugin, shared, sdk) are cross-cutting code and contracts that the binaries pull in; they don’t produce separate artifacts.

Building

Clone and build all binaries with a single command:

git clone <repo-url> soul-stack
cd soul-stack
make build

The result is binaries in the modules’ bin directories: keeper/bin/keeper, soul/bin/soul, soulctl/bin/soulctl, soul-lint/bin/soul-lint. The version is injected by the linker at build time (make build), so keeper version prints the real version rather than 0.0.0-dev.

Check the built binary’s version:

./keeper/bin/keeper version
./soul/bin/soul version
./soulctl/bin/soulctl --version

Tests

make test    # unit tests across all modules

The full local gate (formatting, vet, build, tests, checks of generated code and links) is make check.

Building deb/rpm packages

If you need packages for your own distribution, make pkg builds deb + rpm for keeper / soul / soul-lint (requires nfpm installed). soulctl isn’t packaged — it’s distributed as a binary.

Next — runtime

The built binaries need the same external infrastructure as a package install: the required stack is PostgreSQL + Redis + Vault (all three; Keeper checks each on startup and won’t start without any one of them). Provisioning, configs, bootstrapping the first operator and onboarding an agent are in From deb/rpm packages, starting from step 2.

For a quick local look without production provisioning, see Quick Start.