Install the Compute Node agent on Linux

Step 1 — Pick a package format

Zyra ships three Linux packages, all generated by electron-builder per desktop/package.json:

For headless servers, skip the GUI packages and use the zyra-install.sh script described in Step 4.

Step 2 — Install runtime dependencies

The Electron-based agent statically bundles its Node runtime, but it still needs a few system libraries that nearly every desktop distro already has and many minimal server installs do not:

# Debian / Ubuntu
sudo apt install -y libnss3 libatk-bridge2.0-0 libgtk-3-0 libxss1 \
    libasound2 libdrm2 libgbm1 libxcomposite1 libxdamage1

# Fedora / Rocky
sudo dnf install -y nss atk at-spi2-atk gtk3 libXScrnSaver \
    alsa-lib libdrm libgbm libXcomposite libXdamage

If you want to run Docker-based Virtual Servers on the same machine (the common pattern), also install Docker Engine. The agent talks to Docker via /var/run/docker.sock; the user running the agent must be in the docker group.

Step 3 — Generate an enrollment key

Same flow as the other platforms: Settings → Compute Nodes → Enrollment keys → Create key. Copy the token. For Linux fleets you'll often want uses_remaining capped at the number of machines you're rolling out to — the key auto-decrements per enrollment.

Step 4 — Install (GUI path)

Download the matching package from app.getzyra.io/devices/add (Linux tab) and run the install command from Step 1. The agent appears in your application launcher as Zyra Agent. Launch it, pick Pair with enrollment key, paste the key, validate. The Compute Node appears in the dashboard.

Step 5 — Install (headless server path)

This is the path most IT teams will use. On the server:

curl -fsSL "https://app.getzyra.io/api/v1/devices/agent/download?os=Linux&key=$ENROLLMENT_KEY" \
  | sudo bash

Behind the scenes the script:

1. Downloads the agent binary into ~/.zyra/zyra-agent.
2. Writes ~/.zyra/config.ini with server= and enrollment_key= lines.
3. Starts the agent with nohup ... > ~/.zyra/agent.log 2>&1 &.
4. On first run the agent reads config.ini, auto-enrolls against /api/v1/devices/enroll, and persists the resulting device ID.

This is the actual logic in backend/app/routers/devices/agent_download/installers/linux.py — no daemon registration today.

Optional — register as a systemd service

To survive reboots cleanly, drop a unit file at /etc/systemd/system/zyra-agent.service:

[Unit]
Description=Zyra Compute Node Agent
After=network-online.target docker.service
Wants=network-online.target

[Service]
Type=simple
User=zyra
ExecStart=/home/zyra/.zyra/zyra-agent --config /home/zyra/.zyra/config.ini
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Then sudo systemctl daemon-reload && sudo systemctl enable --now zyra-agent. (There is no first-party systemd-unit installer today; this unit file is a recommended pattern, not a shipped artifact.)

Step 6 — Confirm pairing

sudo systemctl status zyra-agent (or ps aux | grep zyra-agent if you skipped systemd) should show the process running. Then check the dashboard: the new Compute Node appears within 60 seconds with the hostname-derived name.

What just happened

The agent runs as your service user, holds an organization-scoped device ID, and heartbeats every 30 seconds. On headless servers, it's running entirely without a display server — no DISPLAY, no X11, no Wayland.

Troubleshooting

• AppImage refuses to run with "FUSE not installed". Install libfuse2 (Ubuntu/Debian) or fuse-libs (Fedora). AppImages need FUSE.
• SELinux blocks the agent. Set the binary's context: chcon -t bin_t ~/.zyra/zyra-agent. For permanent fixes, write a small SELinux policy module.
• AppArmor denies Docker socket access. Add the agent's profile to /etc/apparmor.d/local/ allowing /var/run/docker.sock rw,.
• "libgbm.so.1 not found" on minimal Ubuntu Server. Re-run Step 2's apt install list — minimal Server omits the desktop libraries the Electron runtime needs.
• config.ini lost across reboots. Make sure the install location is under the service user's home, not /tmp.