Troubleshooting

Machine shows offline

systemctl --user status vdo-agent

If not running, start it. Check network access:

curl -s https://api.vdostream.io/health

Black screen

The agent needs an active desktop session. On headless machines, ensure auto-login is configured. Try restarting the display manager:

sudo systemctl restart gdm
systemctl --user restart vdo-agent

For headless machines without a dongle, see Configuration & Display.

No keyboard or mouse

Restart the agent:

systemctl --user restart vdo-agent

If that doesn't help, re-run the installer to reset permissions.

Poor quality or stuttering

Check your encoder -- hardware encoding gives the best results:

vdo-remote-agent --probe

If only CPU encoding is available, install GPU drivers. Try a lower quality preset (WAN or Speed) in the viewer toolbar.

Audio not working

Ensure PipeWire or PulseAudio is running:

systemctl --user status pipewire

Install if missing:

# Rocky / Fedora
sudo dnf install pipewire pipewire-pulseaudio
systemctl --user enable --now pipewire

# Ubuntu
sudo apt install pipewire pipewire-pulse
systemctl --user enable --now pipewire

Agent won't start after reboot

Check lingering is enabled:

loginctl show-user $(whoami) | grep Linger

If Linger=no:

sudo loginctl enable-linger $(whoami)

Display not detected

xrandr --listmonitors

No monitors listed: check cable, restart the display manager, or use a DisplayPort dongle for headless setups.

Forcing a specific encoder

[encode]
encoder = "x264"

Then systemctl --user restart vdo-agent.

Collecting logs for support

journalctl --user -u vdo-agent --since "1 hour ago" --no-pager > vdo-agent-logs.txt

Include: the log file, cat /etc/os-release, lspci | grep -i vga, and vdo-remote-agent --probe output.