Install Clavda on macOS: desktop app or command-line agent
Connect a Mac to Clavda with the desktop app, or run the command-line agent: clear the Gatekeeper quarantine and start it at login with a launchd agent.
Updated 2 min read
There are two ways to run Clavda on a Mac, and both use the same config file from the dashboard:
- The desktop app is the simplest: import the config file and connect.
- The command-line agent is a single binary, started at login by launchd.
What you need
- A device record in Clavda with the installation platform that matches the Mac: macOS arm64 for Apple silicon (M1 and later), macOS x64 for Intel. Not sure? Run
uname -m:arm64is Apple silicon,x86_64is Intel. - The device's config file: open the device, press Generate Setup Commands, then Download Config (.env). See Before you start.
Option A: the desktop app
Install the Clavda Desktop app, open it, import the .env file you downloaded, and connect. The device turns green under Devices within a few seconds.
The app keeps the config and the device's keys in ~/Library/Application Support/com.codegen.clavda-desktop-app/, so you can delete the downloaded file afterwards.
Option B: the command-line agent
Move the binary into its own folder
Download the binary with Download Binary: clavda-client-darwin-arm64 on Apple silicon, clavda-client-darwin-amd64 on Intel. Then:
mkdir -p ~/clavda
mv ~/Downloads/clavda-client-darwin-arm64 ~/clavda/clavda-client
chmod +x ~/clavda/clavda-client
Clear the Gatekeeper quarantine
macOS quarantines a binary downloaded through a browser and refuses to run it until the attribute is removed:
xattr -d com.apple.quarantine ~/clavda/clavda-client
Add the config file
Save the downloaded config next to the binary as ~/clavda/.env.
mv ~/Downloads/my-device.env ~/clavda/.env
chmod 600 ~/clavda/.env
Run it
cd ~/clavda && ./clavda-client
It loads the config and connects. The device turns green under Devices within a few seconds. Stop it with Ctrl+C before setting up autostart.
Start it at login with launchd
macOS uses launchd rather than systemd. Create a launch agent, replacing youruser with your account name:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.clavda.client</string>
<key>ProgramArguments</key>
<array>
<string>/Users/youruser/clavda/clavda-client</string>
</array>
<key>WorkingDirectory</key>
<string>/Users/youruser/clavda</string>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
</dict>
</plist>
Then load it:
launchctl load ~/Library/LaunchAgents/com.clavda.client.plist
WorkingDirectory matters: it is how the agent finds .env. RunAtLoad starts it when you log in, and KeepAlive restarts it if it ever exits.
Check that it worked
Open Devices in Clavda: the device is green while the agent is connected. If it stays grey, run ./clavda-client from Terminal and read its output, then see Troubleshooting.