Install Clavda manually on Linux with a systemd service
Install the Clavda agent by hand: put the binary and its .env in place, test it in the foreground, then start it on boot with a system or per-user systemd unit.
Updated 3 min read
The one-line installer is the quickest route, but every step it takes can be done by hand. Do that when you want to see exactly what goes on the machine, when you would rather not pipe a script into a shell, or when the machine cannot download from the Clavda API. The result is the same install, file for file.
What you need
- A device record with a Linux installation platform that matches the machine's architecture. See Pick the right binary.
- From the device's Generate Setup Commands panel: the binary (Download Binary) and the config file (Download Config (.env)). Copy both onto the machine, for example with
scp.
Install the agent
Choose an install directory
Use /opt/clavda for a system-wide install, or ~/clavda if you have no root. The rest of this tutorial uses the system path. For a non-root install, swap in ~/clavda and drop sudo.
sudo mkdir -p /opt/clavda
Put the binary in place
Move the binary in and make it executable. It must be named clavda-client, because the service unit below refers to it by that name.
sudo mv ~/Downloads/clavda-client-linux-amd64 /opt/clavda/clavda-client
sudo chmod +x /opt/clavda/clavda-client
Add the configuration
Save the downloaded config as .env beside the binary, readable only by root. These are the same bytes the one-line installer writes, so this step is equivalent to running it.
sudo mv ~/Downloads/my-device.env /opt/clavda/.env
sudo chmod 600 /opt/clavda/.env
Run it once in the foreground
Before making it a service, check that it starts. It should log [Config] Loaded .env from: … and connect. Stop it with Ctrl+C.
sudo /opt/clavda/clavda-client
Start it on boot
Create the unit file. This is the same unit the installer writes:
[Unit]
Description=Clavda Client Service
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=root
Group=root
WorkingDirectory=/opt/clavda
ExecStart=/opt/clavda/clavda-client
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=clavda
EnvironmentFile=/opt/clavda/.env
NoNewPrivileges=true
[Install]
WantedBy=multi-user.target
Then enable and start it:
sudo systemctl daemon-reload
sudo systemctl enable clavda.service
sudo systemctl start clavda.service
sudo systemctl status clavda.service --no-pager
The device turns green under Devices within a few seconds. Restart=always brings the agent back if it ever exits, and After=network-online.target holds it until the network is up at boot.
The config file, line by line
If you would rather type the file than download it, it is six lines:
WEB_CLIENT_ID=<account owner id>
ENCRYPTION_KEY=<device encryption key>
WEBSOCKET_URL=<relay url>
DEVICE_ID=<device id>
DEVICE_JWT_TOKEN=<device jwt>
DEVICE_BOOTSTRAP_TOKEN=<bootstrap token>
DEVICE_ID, WEB_CLIENT_ID and ENCRYPTION_KEY are shown in the device sheet. The two tokens only ever appear in the downloaded config, so downloading it is the practical route.
The agent also understands these optional settings:
| Variable | Purpose |
|---|---|
LOG_LEVEL | error, warn, info, debug, verbose or none |
SHELL | The shell for terminal sessions. Defaults to bash |
ALLOWED_FILE_PATHS | Comma-separated list of the only paths file operations may touch |
ALLOW_ALL_PATHS | true for unrestricted file access, the default |
DEVICE_KEY_PASSPHRASE | A passphrase that encrypts the device's private key at rest |
Restart the service after changing .env: sudo systemctl restart clavda.service.
Run it without root: a per-user service
Without root, the unit goes in your own home directory. Replace /home/youruser with your home path:
[Unit]
Description=Clavda Client Service
After=network-online.target
[Service]
Type=simple
WorkingDirectory=/home/youruser/clavda
ExecStart=/home/youruser/clavda/clavda-client
Restart=always
RestartSec=10
EnvironmentFile=/home/youruser/clavda/.env
[Install]
WantedBy=default.target
systemctl --user daemon-reload
systemctl --user enable clavda.service
systemctl --user start clavda.service
A user service only runs while you are logged in. To keep it running after logout, which is what you want on a server, an administrator has to enable lingering for your account:
sudo loginctl enable-linger $USER
Without systemd
On Alpine with OpenRC, or a busybox init, there is no systemctl. Run the binary from whatever supervisor the system has, with /opt/clavda as the working directory. The agent looks for .env in its working directory and next to the executable.