Troubleshoot the Linux Agent

Check registration, graphical readiness and media separately. Do not restart GDM, change login policy, kill workers or reinstall an occupied host to repair a stalled viewer.

Supported setup

Current x86_64 targets are Rocky 8/9 GNOME/GDM X11 and Fedora 43/44 GNOME/GDM Wayland. RHEL, AlmaLinux, CentOS Stream, Ubuntu, Fedora 42, KDE, LightDM and Rocky Wayland are not current targets.

Read Linux setup for release exceptions. Rocky 8's pre-existing VM blank-console-on-lock issue is not a passing lock-continuity result.

Offline computer

sudo systemctl status vdo-agent-broker.service
sudo journalctl -u vdo-agent-broker.service --since "10 minutes ago" --no-pager
curl -fsS https://api.vdostream.io/health

Confirm enrollment in the intended workspace. Keep codes and credentials private; do not erase them or repeatedly create machines.

Online but no picture

Check capture/input readiness, supported session type and a capturable display. Approve Fedora's normal GNOME picker when requested. From the user's own graphical session:

systemctl --user status vdo-agent-session.service
journalctl --user -u vdo-agent-session.service --since "10 minutes ago" --no-pager

A heartbeat is not decoded-video proof. Never enable automatic login, run a worker as root or restart the display manager to bypass consent. See Linux displays.

Picture but no input

Focus the view and check input readiness and normal consent. Test pointer, keyboard and harmless text. Tablet/device paths require physical qualification.

Arrange idle maintenance before service repair. A running-service refusal is not permission to interrupt its viewer.

Stutter or no first frame

Inspect carrier and required ports in Linux networking. HTTPS health can work while relay media is blocked. Reduce bitrate, frame rate or resolution for overload.

On an idle host, vdo-remote-agent --probe can show encoder implementations. It does not qualify every GPU or justify a live driver replacement. See GPU encoding.

No audible audio

systemctl --user status pipewire
systemctl --user status pulseaudio

Inspect the normal user's sound server and test playback. Do not install or enable replacements blindly. Audio-ready is not sound; the restricted greeter is not an ordinary audio session. Diagnostic gates need reviewed idle maintenance.

Installer refusal or failed cutover

Use the exact distro/version and normal Fedora consent. For a running service, disconnect viewers, verify idle state and explicitly stop the named service before retrying.

Failed cutover restores previous local payload/service/GDM state. Preserve credentials, logs and the previous matching installer. The new embedded-assets installer is not a universal downgrade to 0.18.10. See Installation and update.

Support information

Provide version, OS/desktop/session type, client version, relevant broker/user-worker logs, actual transport and symptom. Add GPU/display information only when relevant. Redact codes, credentials, tokens and private content before uploading logs to your support case.