Install Clavda on Linux with one command
Connect a Linux server, VM or single-board computer to Clavda with the one-line installer, as root or without root, then keep the agent up to date.
Updated 4 min read
The quickest way to put a Linux machine on Clavda is a single command: it downloads the agent, writes its configuration and registers a systemd service so the agent starts again after every reboot. It works on x86-64 and ARM machines, including a Raspberry Pi.
Prefer to see every step, or the machine cannot reach the Clavda API? Follow the manual install with systemd instead. It ends in exactly the same place.
What you need
- A device record in Clavda with a Linux installation platform. See Before you start.
- A shell on the Linux machine, with
sudoif you want a system-wide install. - An SSH server running on the machine. The browser terminal logs in through it, with the SSH username and password saved on the device.
- Outbound HTTPS access from the machine. No inbound ports are needed.
Pick the right binary
The installation platform you chose for the device decides which binary the installer downloads. If you are not sure what the machine is, ask it:
uname -m
uname -m prints | Installation platform | Binary |
|---|---|---|
x86_64 | Linux x64 | clavda-client-linux-amd64 |
aarch64 | Linux ARM64 | clavda-client-linux-arm64 |
armv7l | Linux ARMv7 | clavda-client-linux-arm |
If the platform is wrong, edit the device and generate the setup commands again. A wrong binary fails with Exec format error.
Run the installer
Copy the install command
Open the device in Clavda, press Generate Setup Commands and open the Install tab. The command looks like this, with your own API host and code:
curl -fsSL "https://<api-host>/i/AbCd1234?m=root" | sudo sh
wget -qO- "https://<api-host>/i/AbCd1234?m=root" | sudo sh
busybox wget -qO- "https://<api-host>/i/AbCd1234?m=root" | sudo sh
All three do the same thing. Use wget or busybox on minimal images that ship without curl.
Choose root or non-root
The privilege selector above the tabs switches between two kinds of install, and the command changes with it:
| Option | Installs to | Service | Starts |
|---|---|---|---|
| Root (via sudo) | /opt/clavda | /etc/systemd/system/clavda.service | At boot |
| Non-root | ~/clavda | ~/.config/systemd/user/clavda.service | At login |
The non-root command ends in | sh instead of | sudo sh and never asks for root:
curl -fsSL "https://<api-host>/i/AbCd1234?m=user" | sh
Paste it into the machine's shell
The script downloads the binary, writes .env beside it with permissions 600, and enables and starts the clavda.service unit. It finishes by printing the service status.
The install link expires after 7 days
The short link in the command (/i/AbCd1234) holds the device's credentials on the server, so no
token ends up in your shell history. It stops working after 7 days. If it has expired, press
Generate Setup Commands again for a fresh one.
Check that the device is online
Open Devices in Clavda. The device turns green within a few seconds of the agent connecting. You can also check the service on the machine:
sudo systemctl status clavda.service
sudo journalctl -u clavda.service -f
For a non-root install, use systemctl --user status clavda.service and journalctl --user -u clavda.service -f. Still grey after a minute? See Troubleshooting.
Keep the agent running after logout (non-root only)
A per-user service only runs while you are logged in. On a server, where you want the agent up all the time, ask an administrator to enable lingering for your account:
sudo loginctl enable-linger $USER
Machines without systemd
On Alpine with OpenRC, or a busybox init, there is no systemctl. The installer still installs the binary and its .env, then prints how to start the agent instead of registering a service. Run it from whatever supervisor the system has, with the install directory as the working directory so the agent finds .env.
Advanced: install modes and a custom directory
The script reads two environment variables that override what the dashboard baked into the command:
| Variable | Values | Effect |
|---|---|---|
CLAVDA_MODE | root, sudo, user, auto | sudo runs as you and escalates only the steps that need it. auto uses root if it is root, otherwise sudo, otherwise a non-root install. |
CLAVDA_INSTALL_DIR | Any path | Installs somewhere other than /opt/clavda or ~/clavda. |
Set them on the shell that runs the script. For example, to install to /srv/clavda as your own user with sudo for the privileged steps:
curl -fsSL "https://<api-host>/i/AbCd1234?m=root" | CLAVDA_MODE=sudo CLAVDA_INSTALL_DIR=/srv/clavda sh
If you install to a custom directory, set the same CLAVDA_INSTALL_DIR when you run the update or uninstall command, so they find it.
Update the agent
The Update tab in the same panel gives a command that replaces the binary in place and restarts the service. It uses the same privilege selector:
curl -fsSL "https://<api-host>/s/update?f=clavda-client-linux-amd64&m=root" | sudo sh
The new build downloads beside the old one and is renamed over it only once the download is complete, so a failed download never leaves a broken agent. Unlike the install link, the update command carries no credentials and never expires, so it is safe to keep in a runbook.