Machines and leases

A machine is a server where the crunu agent runs as a service. It has its own keys, its own certificate and its own grants. It fetches the environments granted to it, decrypts them in memory and hands them to your application through crunu run or crunu pull. Production secrets reach production this way without passing through CI.

Example. Kiteline is a fictional company. api-prod-1 runs payments-api with payments-api / production delivered by environment key. staging-runner is enrolled and waiting for an admin to approve it.

Lifecycle

Creating and enrolling

1. On Machines, choose New machine. Give it a name, choose Environments and how to deliver them, the lease duration and, optionally, the networks it may connect from.
2. Create and get code shows a single-use enrollment code inside a ready install command. The code is valid for 15 minutes by default and at most 24 hours, and it can be limited to certain addresses. It's shown only once.
3. On the server, the command installs the agent and runs crunu enroll, which prints the machine's fingerprint.
4. In the web app the machine appears under Awaiting approval. Review and approve… shows its host, the agent version, where it enrolled from and its fingerprint. Compare the fingerprint with the output on the server, tick that it matches, and approve.

Step-by-step: Install the agent.

Delivery

Each environment granted to a machine has a delivery method:

• Environment key: the machine gets the environment key and always sees the latest version of all files. Removing it means rotating the environment key.
• Selected files: the machine gets a sealed copy of only the files you chose, rebuilt whenever they change. Removing it doesn't require a key rotation.

Choose Selected files when a machine needs one file out of many.

Leases

A lease is how long a machine may keep working without contacting the server. It defaults to 24 hours and can be up to 30 days. The agent renews it every 5 minutes. Every sign-in also extends it.

• Online, the service checks the server every minute by default and renews the lease every 5 minutes.
• Offline, it keeps serving the last verified state until the lease ends. After that, crunu run gets exit code 4.
• A shorter lease takes effect immediately: the current lease is cut to the new length.

Revocation

On Machines, choose the machine, then Revoke…. What happens:

• The server stops serving it at once. The next request is refused.
• The agent learns about it at its next check and wipes the decrypted environments from memory. With the default check interval of one minute, that's within minutes while the machine is online. An offline machine finds out when it reconnects, and stops serving on its own when its lease ends.
• Environment keys are rotated where the machine had the environment key. Your browser does it with your key. If you don't hold a key for some environment, its rotation waits for someone who does, and shows up in Pending actions.
• Running programs keep their variables until they restart.

Revocation can't be undone. To bring the machine back, create a new one and enroll it with a new code. A machine can also revoke itself with crunu revoke-self.

What protects a machine's data

• Its own keys. A machine key doesn't open other machines or other environments.
• Verification. The agent checks signatures, certificates and the revocation list, and rejects rollbacks. Any mismatch is logged as an alert, and crunu run exits with code 6.
• Memory only. Decrypted environments live in the service's memory and are served over a local socket to root and the crunu group. The service blocks memory dumps and runs in a systemd sandbox.
• Address limits. A machine can be limited to certain networks, and environments can have network rules with machine passes.
• Alerts for a machine signing in from a new address, a reused enrollment code, or an expired lease.

What a machine can see

A machine is a legitimate recipient. Root on that machine sees everything granted to it, so grant the minimum: only the environments, and if possible only the files, it needs. If a machine may have been compromised, follow the steps in Rotate environment keys and reissue the values it received at their providers. Its page shows which versions of which environments it received and when.

Supported systems

The service runs on Linux with systemd, on amd64 and arm64. Its installation is tested on Ubuntu 24.04, Ubuntu 22.04 and Debian 12. On macOS, crunu works as a command-line tool without a background service. There's no Windows build.