Installation

In most cases, auto-detection works correctly and you do not need --distro.

What the Installer Does

1. Downloads the agent binary matching your system
2. Installs runtime dependencies (display, encoding, and input libraries)
3. Installs the KMS grab helper when the release includes one
4. Creates the service at ~/.config/systemd/user/vdo-agent.service
5. Sets up device permissions so the agent can capture the screen and inject input
6. Enables lingering so the service runs even when you are not logged in via SSH
7. Registers the machine with your VDO account using the token
8. Starts the agent immediately

Privileged KMS Helper

KMS framebuffer capture uses a small privileged helper instead of running the whole agent as root. When the helper is bundled with the release or downloadable by the installer, it is installed at:

/usr/local/libexec/vdo-kmsgrab-helper

It should have cap_sys_admin+ep:

getcap /usr/local/libexec/vdo-kmsgrab-helper

Expected output:

/usr/local/libexec/vdo-kmsgrab-helper cap_sys_admin=ep

If the helper is missing or lacks the capability, re-run the installer. Without it, KMS capture may fail or require running the agent as root.

Updating to a Newer Version

Run the same install command again. The installer detects the existing installation and performs an in-place upgrade:

curl -fsSL https://api.vdostream.io/api/v1/remote/install.sh | sudo bash -s -- --token YOUR_TOKEN

The agent service is restarted automatically after the update.

Installing a Specific Version

Use the --version flag to pin a particular release:

curl -fsSL https://api.vdostream.io/api/v1/remote/install.sh | sudo bash -s -- --token YOUR_TOKEN --version 0.2.0

This also works for downgrading if a newer version causes issues.

Disabling Auto-Login

By default, the installer configures auto-login so the agent can access the desktop immediately after a reboot. If you prefer to manage login yourself:

curl -fsSL https://api.vdostream.io/api/v1/remote/install.sh | sudo bash -s -- --token YOUR_TOKEN --no-autologin

Note: without auto-login, the agent cannot capture the desktop until a user session is active.

Uninstalling

To remove the agent:

systemctl --user stop vdo-agent
systemctl --user disable vdo-agent
rm ~/.config/systemd/user/vdo-agent.service
systemctl --user daemon-reload
sudo rm -f /usr/local/bin/vdo-remote-agent
sudo rm -f /usr/local/libexec/vdo-kmsgrab-helper
rm -rf ~/.config/vdo

The machine will show as offline in your dashboard. You can delete it from the dashboard as well.