Browse the docs
Command line
The crunu command-line tool
One static binary for Linux and macOS that runs as a machine service, with a CI service token, or signed in as a person, and decrypts only in its own process.
Last updated
On this page
crunu is the Crunu agent and command-line tool. It's a single static binary written in Go and built for Linux and macOS on amd64 and arm64. It uses only the Go standard library. There is no Windows build, and the background service ships only as a systemd unit for Linux. On macOS you use the command line: sign in as a person or run with a service token.
Everything crunu gets from the server is ciphertext. Values are decrypted only inside the crunu process. Before it uses anything, crunu checks signatures and certificates against your organization's signing key. It learns the fingerprint of that key from the enrollment code, the service token or the pin stored in your account, never from the server alone. Each environment head is checked against the chain crunu has already seen, and each version and file copy against its author's signature and rights. A lower number than one already seen is treated as a rollback, and that data is rejected.
Three ways to run it
| Mode | Who uses it | How it signs in | What it can read |
|---|---|---|---|
| Machine | the crunu-agent service on a server | the machine key created at enrollment | environments granted to this machine |
| Service token | CI jobs and short-lived environments | CRUNU_TOKEN, plus the CI provider's OIDC token when the token has a CI binding | environments granted to the token |
| Person | a developer in a terminal | crunu login with email, password, Secret Key and a second factor | environments where the person has their own key or their own file copy |
The machine mode is covered in Enroll a machine and run the service, the service token mode in Any CI with a service token, and the person mode in Sign in from the terminal.
Commands
| Command | What it does |
|---|---|
crunu enroll | Enrolls a machine with a single-use enrollment code and prints the machine fingerprint. |
crunu daemon | The machine service. Keeps granted environments in memory and serves them over a local socket. systemd starts it. |
crunu run | Runs a program with the variables of one or more environments. |
crunu pull | Writes environment files and variables to disk with mode 0600. |
crunu status | Shows who you are, the organization and its fingerprints, the lease and the environments. |
crunu renew | Renews the lease of this machine or token now. |
crunu revoke-self | Revokes this machine or token for good and deletes the local keys. |
crunu login | Signs in as a person. |
crunu unlock | Keeps your keys in memory for a limited time so run and pull can use them. |
crunu lock | Forgets your keys early. |
crunu logout | Signs out, removes this computer from your account and deletes local sign-in data. |
crunu self-update | Replaces crunu with a version from a signed release. |
crunu version | Prints the version, OS, architecture and Go version. |
crunu help | Lists commands. crunu help run shows the flags of one command. |
Installing
The web app shows the install command for your server, with the exact SHA-256 checksums from the signed release manifest. The installer checks the checksum of the binary before it puts it in place. It has two modes:
- Service mode on Linux with systemd, as root. It installs
crunu, creates thecrunuuser and group and thecrunu-agentservice, and can enroll the machine in the same step. - User install with
--user-install, without root and without systemd. Use it in CI, in containers and on Linux or macOS workstations.
There are also .deb packages for amd64 and arm64. A crunu installed from the package is updated with apt or dpkg, not with crunu self-update.
To remove the service, run the installer with --uninstall. The enrollment and data stay in /var/lib/crunu and /etc/crunu unless you add --purge, which also removes them and the crunu user. A package install is removed with apt remove crunu-agent, or apt purge crunu-agent to remove the data as well.
sudo sh install.sh --uninstall --purgeStep-by-step setup for a server is in Install the agent.
The server address
The server address is both where requests go and the audience of every sign-in signature, so a signature made for one server is useless on another. Cloud accounts use https://app.crunu.com. A self-hosted server has its own address, such as https://vault.company.example.
crunu writes the address in one canonical form: https://host, with an optional port. A missing scheme means https://. The scheme and host are lowercased, the default port is dropped, and the path can only be /. Hosts outside ASCII must be written in punycode. Plain http:// is accepted only for localhost, *.localhost, 127.0.0.1 and [::1]. crunu never follows redirects.
crunu checks the server certificate with the system's root certificates. A minimal container without the ca-certificates package has none, and crunu will tell you to install the package or point SSL_CERT_FILE at a bundle. An unverified certificate counts as no connection to the server.
Files it keeps
On a machine, the service keeps its enrollment, keys and rollback-protection state in /var/lib/crunu with mode 0600, and optional settings in /etc/crunu/agent.json. It listens on /run/crunu/agent.sock, which only root and members of the crunu group can open. For a person, sign-in data lives in ~/.config/crunu/ (or $XDG_CONFIG_HOME/crunu), with mode 0700 for the directory and 0600 for files.
All state files are written atomically. crunu refuses to read a key file that other users can read and asks you to run chmod 600. Decrypted values are never written to disk, except the files you ask crunu pull to write. The service and the person's key holder block memory dumps of their own process.