systemd services that get secrets from Crunu

What Crunu does with systemd

On a Linux server, the crunu agent runs as the systemd service crunu-agent. It signs in with the machine's own keys, checks the server every minute, keeps decrypted environments in memory only and hands them to crunu run through a local socket. Your service starts through crunu run and gets its variables from the agent, so nothing lands on disk.

This is also how Crunu keeps production out of CI: the production server fetches its own environment, and the pipeline only delivers code and restarts the service.

Enroll the machine

In Crunu, open Machines and choose New machine. Pick its environments and how to deliver them, then copy the install command from the Enroll machine dialog. It installs the agent, checks the binary's SHA-256 and enrolls the machine with a single-use code read from stdin:

printf '%s\n' 'crunu_enr_…' | sudo sh install.sh --version 6.0.0 --sha256 amd64=<sum> --sha256 arm64=<sum> --base-url https://releases.crunu.com/6.0.0 --server https://app.crunu.com --enroll -

The dialog fills in the enrollment code and the checksums for you. Agent releases are published at releases.crunu.com: version 6.0.0 has binaries for Linux and macOS, .deb packages, install.sh and a signed manifest. On a server you run yourself, the dialog shows the addresses that server is set up with. The code is valid for 15 minutes by default and is used up the first time it's presented. crunu enroll prints the machine's fingerprint; approve the machine in Machines after checking that the fingerprint matches.

The installer is tested with systemd on Ubuntu 24.04, Ubuntu 22.04 and Debian 12. A .deb package is also built for amd64 and arm64.

Start your service through crunu run

# /etc/systemd/system/payments-api.service
[Service]
User=payments
ExecStart=/usr/local/bin/crunu run --env payments-api/production --restart on-change -- /opt/payments-api/bin/server

The service's user must be in the crunu group, which owns the agent's socket. With --restart on-change, crunu run restarts your program after values change: it sends SIGTERM, then SIGKILL if the program hasn't stopped within the stop timeout, and starts it again with the new variables. Only the names of changed variables go to the log. Signals from systemd are forwarded to your program, and its exit code becomes crunu run's.

The program gets a clean environment: a short allowlist such as PATH, HOME and LANG, plus the environment's variables.

Or write a file for EnvironmentFile=

If a unit should read variables from a file, crunu pull can write them as one env file with 0600 permissions:

crunu pull --env payments-api/production --env-out /etc/payments-api/env

Point the unit's EnvironmentFile= at that path. The values are then on disk, readable by root and the file's owner, and Crunu doesn't remove the file later. Prefer crunu run when you can.

How the agent service is locked down

• The unit runs as the crunu user with no capabilities, ProtectSystem=strict, a read-only home, private /tmp and devices, and a SystemCallFilter limited to ordinary service calls.
• Core dumps are off, and on Linux the agent is shielded from other processes of the same user.
• State files are written atomically. The agent records the newest verified state before serving it, so after a restart the server can't quietly roll it back.

Operating it

sudo systemctl enable --now crunu-agent
sudo systemctl kill -s HUP crunu-agent
crunu status

The first command starts the agent once the machine is enrolled. SIGHUP makes it check the server now instead of at the next minute. crunu status shows the machine, its organization and fingerprints, the lease and each environment.

If the server can't be reached, the agent serves the last verified state until the lease ends, 24 hours by default. After the machine is revoked, it erases its environments from memory within minutes while it's online.

Related

• Machines in Crunu
• Install the agent
• Enroll a machine and run the service
• crunu run
• crunu pull
• Docker