Install the agent on a server

The crunu agent delivers secrets to a server. It runs as a systemd service, keeps the environments granted to the machine decrypted in memory, and starts your application with its variables. The pipeline that deploys your code never sees them.

You'll need a Linux server with systemd, amd64 or arm64, and root access. The installer is tested on Ubuntu 24.04, Ubuntu 22.04 and Debian 12. On macOS, crunu works only as a command-line tool, and there is no Windows build.

Example. Kiteline is a fictional company. Priya sets up api-prod-1, a Linux amd64 server, to run payments-api with payments-api / production.

1. Create the machine

Owners and admins create machines. An operator can create machines for environments where they have the Operator role.

On Machines, choose New machine:

• Name, such as api-prod-1.
• Environments and how to deliver them. Pick each environment and its delivery: Environment key for all files and always the latest version, or Selected files for a sealed copy of just the files you choose.
• Lease duration, 24 hours by default. The machine keeps working without the server for this long. The agent renews it every 5 minutes.
• Networks, optional: addresses the machine may connect from.

Choose Create and get code.

2. Run the install command

The Enroll machine window shows a single-use enrollment code built into one command. Pick how the server downloads, with curl or wget, and whether you're already root. The command looks like this:

curl -fsSL -o crunu-install.sh https://releases.crunu.com/6.0.0/install.sh \
  && echo "<sha256>  crunu-install.sh" | sha256sum -c - \
  && printf '%s\n' 'crunu_enr_…' | sudo sh crunu-install.sh --version 6.0.0 --base-url https://releases.crunu.com/6.0.0 \
       --sha256 amd64=<sha256> --sha256 arm64=<sha256> --server https://app.crunu.com --enroll - \
  && rm -f crunu-install.sh

Copy the exact command from the window. It contains the checksums of the install script and of the binaries from the signed release manifest, which the web app has verified.

What the command does:

1. Downloads the install script and checks its SHA-256 before running it.
2. Downloads crunu for the server's architecture, checks its checksum and that it starts, and installs it.
3. Creates the crunu user and group and the crunu-agent service.
4. Runs crunu enroll with the code from stdin. The code never appears as an argument, because arguments are visible to every user in the process list.
5. Prints the machine fingerprint.

The code is valid for 15 minutes by default and is shown only once. It's used up the first time it's presented, even if that attempt fails.

If the agent is already installed, for example from the .deb package, the window also offers a command that only enrolls.

3. Compare the fingerprint and approve

The machine now shows under Awaiting approval. Choose Review and approve…. The window shows the host, such as api-prod-1 · linux/amd64, the agent version, when and from which address it enrolled, a check that the enrollment proof matches the code, and the fingerprint.

Compare the fingerprint with the first line crunu enroll printed on the server. Tick The fingerprint matches the crunu enroll output on this machine, then Approve. Your app issues the machine's certificate and delivers its environment keys or file copies.

4. Check it on the server

crunu status

It shows the machine, the organization and its fingerprints, the lease, and each environment with its version. The service picks up its environments at its next check, within a minute.

5. Run your application

Run your application through the agent, for example as a systemd service:

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

Add the application's user to the crunu group so it can reach the agent's socket:

sudo usermod -aG crunu payments

crunu run passes the variables of files marked Load as environment variables (crunu run). With --restart on-change, it restarts the program when values change. If the program reads files from disk, use crunu pull instead. See crunu run and crunu pull.

Your deploy pipeline then only ships code and restarts the service. Production secrets never pass through CI.

Afterwards

• Updates: sudo crunu self-update, then sudo systemctl restart crunu-agent. See Update crunu with self-update.
• Taking a machine out of service: revoke it in the web app, or run sudo crunu revoke-self --yes on the server.
• If the server is compromised: revoke the machine, rotate the keys of its environments and reissue the values it received. See Machines and leases.

Next: Connect CI.