Skip to Content
InstallationmacOS

Install on macOS

The easiest way to connect a Mac to your Rabtly network is the Rabtly menu bar app — a small icon that sits in your menu bar and lets you connect or disconnect with one click.

Option A — Menu bar app (recommended)

Add the Rabtly tap and install

brew tap rabtly/tap
brew install rabtly

Launch the app

rabtly

A gray circle appears in your menu bar.

Configure your server

Click the icon → Settings… — this opens ~/.rabtly/config.json in your editor.

Set control_url to your Rabtly server address:

{
  "control_url": "https://your-server:8080",
  "node_name": "my-mac",
  "network_id": "default",
  "enroll_token": ""
}

Save the file, then click Connect. macOS will ask for your password once to start the VPN — this is normal.

What the password dialog is for — Rabtly needs administrator privileges to create the WireGuard network interface (rabtly0). You are prompted once per session. The tray app itself runs without elevated privileges.

Menu itemWhat it does
● Connected — 100.64.x.xShows your assigned VPN IP
Connect / DisconnectStart or stop the VPN
Settings…Opens ~/.rabtly/config.json
Open DashboardOpens the web dashboard in your browser

Config file reference

FieldDescriptionDefault
control_urlURL of your Rabtly control planehttp://localhost:8080
node_nameName shown in the dashboardYour hostname
network_idTenant network to joindefault
enroll_tokenEnrollment secret (if your server requires one)(empty)
state_dirWhere keys and state are stored~/.rabtly/state
tokenDashboard JWT — enables IP and peer count in menu(empty)

Option B — Daemon only (headless / advanced)

Use this if you want the daemon to run as a background service without any GUI, for example on a Mac acting as a subnet router.

Install the daemon

# Homebrew (installs rabtlyd to /opt/homebrew/bin/)
brew tap rabtly/tap && brew install rabtly
 
# Or build from source
cd rabtly/backend && go build -o /usr/local/bin/rabtlyd ./cmd/daemon

Run manually

sudo RABTLY_CONTROL_URL=https://your-server:8080 \
     RABTLY_NODE_NAME=my-mac \
     RABTLY_STATE_DIR=/var/lib/rabtly \
     rabtlyd

Run as a launchd service (start on boot)

sudo tee /Library/LaunchDaemons/io.rabtly.daemon.plist > /dev/null <<'EOF'
<?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>io.rabtly.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/rabtlyd</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>RABTLY_CONTROL_URL</key> <string>https://your-server:8080</string>
    <key>RABTLY_NODE_NAME</key>   <string>my-mac</string>
    <key>RABTLY_STATE_DIR</key>   <string>/var/lib/rabtly</string>
  </dict>
  <key>RunAtLoad</key>  <true/>
  <key>KeepAlive</key>  <true/>
  <key>StandardOutPath</key> <string>/var/log/rabtly.log</string>
  <key>StandardErrorPath</key><string>/var/log/rabtly.log</string>
</dict>
</plist>
EOF
 
sudo launchctl load /Library/LaunchDaemons/io.rabtly.daemon.plist

Verify it’s connected

Open the dashboard → Nodes — your Mac should appear with an Online badge.

Daemon environment variables

VariableDescription
RABTLY_CONTROL_URLControl plane URL (required)
RABTLY_NODE_NAMENode name shown in dashboard
RABTLY_STATE_DIRDirectory for WireGuard keys and state
RABTLY_NETWORK_IDTenant network ID (default: default)
RABTLY_ENROLL_TOKENEnrollment token (if required by server)
RABTLY_RELAY_ADDRRelay server address (optional, e.g. relay.example.com:7777)
RABTLY_ADVERTISE_ROUTESComma-separated subnets to expose (e.g. 192.168.1.0/24)

Troubleshooting

“Failed to start daemon” Check ~/.rabtly/tray.log for the error output of the daemon.

Password dialog keeps appearing on every restart This is expected in the current version. A future release will install a launchd service that removes the need for a password prompt.

No menu bar icon Make sure Rabtly.app is running (check Activity Monitor). The app has no Dock icon by design.

rabtlyd not found The tray looks for rabtlyd next to itself first, then in $PATH. If you installed via Homebrew, it should be found automatically. Otherwise, add /usr/local/bin to your PATH.

OverviewLinux