Flintstack › Download › Install

Installing Flintstack

Two supported paths: the prebuilt static tarball, or make from a source checkout. Both end with the same two binaries and the same verification step.

From the tarball

Release artifacts are built on a clean machine and published together with a checksum file. Check it before unpacking; a build cache is exactly the kind of component nobody audits twice.

sha256sum -c flintstack-0.11.3.sha256
tar -tvf flintstack-0.11.3-linux-x86_64.tar.zst | head
sudo tar -xf flintstack-0.11.3-linux-x86_64.tar.zst -C /usr/local --no-same-owner

The archive contains bin/flintd, bin/flint, a sample configuration and the licence text. Nothing is written outside the prefix, and no post-install hook runs.

Target	libc	Notes
linux-x86_64	static, musl	the one most people want
linux-aarch64	static, musl	same features, slightly slower hashing
freebsd-x86_64	native	community-maintained since 0.9.1

From source

A source build needs a C compiler, make and about 90 seconds. There is no dependency manifest to resolve because there are no third-party dependencies in the tree.

git clone https://code.flintstack.dev/flint.git
cd flint && git checkout v0.11.3
make -j"$(nproc)" && make check
sudo make PREFIX=/usr/local install

make check runs the unit and round-trip tests, roughly 400 cases, and refuses to pass if the on-disk store format it writes cannot be read back by the compatibility reader for 0.10.x. That check is why the format has only broken once, between 0.6 and 0.7.

Store and permissions

The daemon wants one directory it fully owns, on a filesystem that is fast and, ideally, not the same device as the build tree. It never follows symlinks out of that root.

sudo install -d -m 0750 -o flint -g flint /var/lib/flint
sudo install -d -m 0755 -o flint -g flint /run/flint
sudo install -d -m 0755 /etc/flint

Everyone who runs builds needs write access to the socket, not to the store. The usual arrangement is a flint group: the daemon runs as its own user, the socket is group-writable, and CI users are members of the group. The store directory itself stays 0750 so that a build cannot reach in and rewrite an entry behind the daemon's back.

Do not put the store on a network filesystem. The daemon relies on atomic rename within a single filesystem and on advisory locks that actually lock. Both assumptions are routinely broken by network mounts, and the failure mode is a corrupted entry that passes its own digest check because it was written twice.

Running the daemon

flintd stays in the foreground, logs to standard error and exits non-zero on a fatal condition, so it runs under any supervisor without a wrapper script. Point your init system at the binary with the flags you need:

flintd \
  --config /etc/flint/flint.toml \
  --root /var/lib/flint \
  --socket /run/flint/flintd.sock \
  --listen 0.0.0.0:7914 \
  --token-file /etc/flint/token

Drop --listen and --token-file if the cache is local only - that is the common case on a single builder, and it removes the network surface entirely. Reloading the configuration is SIGHUP; a clean shutdown that finishes in-flight writes is SIGTERM. There is no SIGKILL-safe mode, but an interrupted write leaves a temporary file that is swept at the next start.

Verify the install

$ flint doctor
binary        0.11.3 (static, musl)
daemon        reachable on /run/flint/flintd.sock
store         /var/lib/flint  ext4  rw  atomic-rename ok
locks         advisory locks ok
clock         offset +0.4 s vs daemon
backends      fs ok, objs skipped (not configured), peer skipped
verdict       usable

Anything other than usable on the last line means the cache will either be bypassed or be unsafe; the lines above it say which. flint doctor exits 0 only on a clean verdict, which makes it a reasonable last step in a provisioning run.

Upgrades and rollback

Patch releases within a minor version never change the store format. Replace the binaries and restart; entries survive.
Minor upgrades may add key inputs. A new input means new keys, which means a one-time cold build - not an error, just a quiet morning of slow CI.
Rolling back from 0.11 to 0.10 is supported and leaves the store readable. Rolling back past 0.7 is not: that release changed the entry header, and the old reader will treat the store as empty.
Two daemons must never share one root. The second one will fail to take the root lock and exit with status 4 rather than corrupt anything.

Next: the command reference, or the configuration keys if you would rather write the file first.

Last updated: 2026-09-29