Before you install Clavda: add a device and get its setup files
Every Clavda install starts with a device record. Create one, pick the right platform, and download the binary and config file the machine needs.
Updated 3 min read
Clavda lets you open a terminal, move files and update firmware on a machine from your browser, even when that machine sits behind NAT, a firewall or a mobile network. Every device dials out to the Clavda relay over an encrypted connection, so nothing on it has to accept incoming connections and you never forward a port.
Before you install anything, the device needs a record in your Clavda account. Creating that record is what mints the credentials the device connects with. This takes about two minutes.
What runs on the device
What you install depends on the kind of device:
| Device | What you install | Tutorial |
|---|---|---|
| Linux server, VM or single-board computer | The Clavda agent, a single executable | Linux |
| Raspberry Pi | The same Linux agent, ARM build | Raspberry Pi |
| Windows PC or server | The desktop app, or the agent | Windows |
| Mac | The desktop app, or the agent | macOS |
| ESP32 board | The ClavdaOTA library, inside your own firmware | ESP32 |
The agent gives you the device's terminal, files and screen from the dashboard. On an ESP32, the library gives you over-the-air firmware updates, a remote Serial Monitor and a live dashboard.
Create the device record
Add the device
Sign in to Clavda (or create an account), open Devices and choose Add Device.
Pick the installation platform
Give the device a name, enter the SSH username and password the browser terminal should log in with, and choose the installation platform that matches the machine. The platform decides which binary you get, so the architecture matters: an ARM board must not be registered as x64. If you are not sure which one you have, the Linux tutorial shows how to check.
Generate the setup files
Save, reopen the device, and press Generate Setup Commands. For an ESP32, the button is Get Device File.
What the setup panel gives you
The setup panel is the source of everything the platform tutorials refer to:
- Install, Update and Uninstall commands: Linux only, since only Linux gets a generated install script.
- Download Binary: the agent for the platform you picked.
- Download Config: a
.envfile for Linux, Windows and macOS (the desktop app imports the same file), orclavda_device.hfor an ESP32.
These are the binaries for each platform:
| Platform | Binary |
|---|---|
| Linux x86-64 | clavda-client-linux-amd64 |
| Linux ARM64, including 64-bit Raspberry Pi OS | clavda-client-linux-arm64 |
| Linux ARMv7, including 32-bit Raspberry Pi OS | clavda-client-linux-arm |
| Windows x86-64 | clavda-client-windows-amd64.exe |
| macOS on Intel | clavda-client-darwin-amd64 |
| macOS on Apple silicon | clavda-client-darwin-arm64 |
Treat the config file like a password
It holds live credentials for that one device. Do not commit it to git or paste it into a chat, and once it is on the machine, make it readable only by the account that runs the agent.
Choose your tutorial
Linux
One command installs the agent and starts it on boot.
Raspberry Pi
Pick the right ARM build, then install like any Linux machine.
Windows
The desktop app, or the agent started by a scheduled task.
macOS
The desktop app, or the agent started by launchd.
ESP32
Add the ClavdaOTA library to your sketch and flash it once.
Troubleshooting
What to check when a device stays offline.