Skip to content

fix(desktop): honest start, supervised processes and install progress for the Virtual Desktop - #37

Merged
skalvinnathan merged 7 commits into
mainfrom
feat/desktop-gui-reliability
Nov 19, 2026
Merged

skalvinnathan merged 7 commits into
mainfrom
feat/desktop-gui-reliability

Conversation

@skalvinnathan

Copy link
Copy Markdown
Member

Summary

This PR comes from an end-to-end review of the Linux desktop: the guest launcher, the VM API, the Kotlin bridge and the Flutter screens. The main problem was that "Start" could report success while the desktop was not usable, and nothing told the user why. That matches #26.

After this PR:

  • Start returns only when every part of the desktop is up.
  • If a part fails, the app says which one, shows its last log lines, and has a View desktop log button.
  • A supervisor restarts parts that crash.
  • Install shows apk's real progress and its real errors.

Refs #26. It is not marked as fixed because the reporter's underlying failure can't be confirmed without a device. After this PR the app shows the reason instead of a false success. See "Relation to #26" below.

What was wrong or incomplete

Guest launcher (android/app/src/main/assets/bootstrap/linxr-desktop.sh)

  1. Start reported success too early.
    • is_running returned true if any recorded pid was alive.
    • cmd_start waited only for that and for port 6080.
    • x11vnc (port 5900) and the window manager were never checked.
    • websockify listens on 6080 even when x11vnc is dead. So the API returned 200, and noVNC then showed "Failed to connect to server".
    • _get_desktop_status in api_server.py used the same weak rule: the X socket plus port 6080, or any pid alive.
  2. Nothing supervised the processes. Components were started with & and never checked again. A crashed x11vnc, websockify, Openbox or tint2 stayed down while the status still said "running".
  3. eval "$APP". Any app id that was not one of the known four was passed to eval as root (/desktop/app). The app's Calculator button sent calc, which matched none of the cases, so it went to eval calc and did nothing. No calculator was installed either.
  4. Install was unsafe and reported success anyway.
    • It ran killall -9 apk; rm -f /lib/apk/db/lock, which kills the boot-time bootstrap's apk add (podman and others) mid-transaction.
    • apk update errors were thrown away.
    • The install ran synchronously under a 600 s API timeout. An XFCE install under TCG can take longer: the API then returned an error while apk kept running as an orphan.
    • The app's _installDesktop showed "installed successfully" whatever the reply said.
  5. Mixed apk branches. On main, init_bootstrap.sh writes v3.20 repositories into Alpine 3.24 images, so the desktop install can mix branches and fail to resolve dependencies. fix: code review fixes for disk resize, dockerd, k3s, recipes, API and VM lifecycle #34 fixes the bootstrap, and this PR adds a guard in the installer.
  6. Settings lost on reboot. Resolution and environment were kept in /tmp, which is tmpfs. After a VM reboot the desktop came back at the defaults.
  7. User changes overwritten. The configuration files were rewritten on every start, so any change to the XFCE panel or the GTK theme was lost. xfwm4.xml was written twice.
  8. D-Bus. Openbox had no session bus for its GTK apps (pcmanfm, mousepad). XFCE used eval $(dbus-launch), and its daemon was never stopped.
  9. Unescaped JSON. The status JSON was built from unescaped strings, and the API parsed it with rfind("{").

VM API (api_server.py)

  • /desktop/start errors were unreadable in the app. Failures did return 500, but the Kotlin client threw the raw JSON body cut to 300 characters (VmApiClient.kt), so the app showed PlatformException(..., {"detail": ....
  • No install progress and no log endpoint.
  • No input validation. Resolution, environment and app id were not validated.

App

  • Home screen Start used the defaults (lib/main.dart, _VirtualDesktopCard). It always started 1280×720 Openbox. If the user had set up XFCE only, the old launcher silently started installing Openbox inside the start call. This is a likely path for [bug] Virtual Desktop (GUI)  #26.
  • Start trusted the call, not the state. VmState.startDesktop treated status == 'started' as running.
  • The viewer opened without checking.
    • It opened even when the desktop was down.
    • The URL used localhost, but the QEMU forward listens on IPv4 127.0.0.1 only.
    • There was no reconnect_delay.
    • The touch tips described gestures noVNC doesn't use (one-finger pan does not scroll).
  • Resolutions: fixed presets only. The dropdown would assert if the guest reported any other value.
  • Port forwards: 6080 and 5900 are always in the built-in list. But (custom + builtin).distinctBy { it.host } let a custom forward on the same host port silently replace them. The same applied to SSH 2222 and the API 7081.
  • Errors appeared only in a snackbar, with no way to see the log.

Performance under TCG (reviewed)

  • Openbox stays the default, which is right for TCG. XFCE keeps xfwm4 --compositor=off.

  • x11vnc:

    • -noxdamage -wait 50 -defer 50 are kept from c5bed9e.
    • Added -noncache: noVNC cannot use x11vnc's client-side cache.
    • Added -noxrecord -nowf -noscr: these skip the XRECORD scroll detection and wireframing, which cost CPU.
    • Added -xkb: symbols typed on the phone keyboard map to the right keys.
    • Added -nobell.
  • websockify race: c5bed9e made start wait for port 6080. What was left:

    • Start did not wait for 5900.
    • A port taken by another process was not detected.
    • A websockify that died later stayed dead.

    All three are now handled. The numpy and Python 3.14 unix_listen patches are kept unchanged. On Alpine 3.24 (websockify 0.13.0) import numpy sits inside try, so the numpy patch is safe.

What changed

linxr-desktop.sh (rewritten, same commands and ports):

  • One supervisor owns the desktop. A _supervise process owns Xvfb :1, D-Bus, the WM, the panel, xfdesktop/xfsettingsd, x11vnc :5900 and websockify :6080.

    • It restarts any of them that exits, at most 5 times in 10 minutes.
    • If Xvfb dies, it ends the session cleanly.
    • Process state, pids and the last error are kept in /run/linxr-desktop, and logs in /var/log/linxr-desktop/. Both are tmpfs.
    • Settings are kept in /etc/linxr/desktop.conf, which survives reboots.
  • start checks every part before it returns. It returns only when:

    • Xvfb has opened :1;
    • the WM is alive;
    • x11vnc listens on 5900;
    • websockify listens on 6080.

    Otherwise it fails, names the component and includes its last log lines. Nothing is left half-running.

    • It is idempotent: if the desktop already runs with the same settings, it returns at once.
    • stop and restart can be repeated. Exit codes: 2 bad argument, 3 not installed, 4 not running, 75 busy.
  • app only takes terminal, files, editor or calculator. Nothing from the request is executed.

  • install:

    • logs apk's progress;
    • waits for the apk lock (apk --wait 600) instead of killing apk;
    • points the repositories at the image's own Alpine branch;
    • checks free disk space;
    • reports apk's real error, for example "Could not reach the Alpine package mirror…".
  • Packages added: galculator, dbus/dbus-x11 and xsetroot for Openbox. Fonts (font-dejavu, plus font-noto for XFCE) and a terminal (xterm, xfce4-terminal) were already there.

  • Config files:

    • They carry a linxr-desktop:managed marker and are only rewritten while the marker is still there. A file the user edited, or that xfconfd rewrote, is left alone.
    • The tint2 panel gains file manager and editor launchers. Calculator is in the Openbox menu.

api_server.py:

  • /desktop/start:
    • It validates its inputs and allows one start at a time.
    • It returns 200 only when the status says running.
    • Otherwise it returns the guest's error with the status fields: 409 for not installed or busy, 500 for a failed component, 504 for a hung script.
  • /desktop/install runs in the background and returns 202. /desktop/status adds install_state, install_progress (37/199), install_step and install_error.
  • /desktop/status reads the supervisor's files. It also returns state (running, degraded, starting, failed or stopped), a flag per component, the two port checks, error and failed_component.
  • GET /desktop/log?name=all|<component>&lines=N is new. It needs the token.
  • /desktop/app rejects ids that are not on the allow-list.

Kotlin:

  • Desktop calls surface the API's detail message.
  • /desktop/start gets a 330 s read timeout.
  • New getDesktopLog channel method.
  • Host ports 2222, 7081, 6080 and 5900 are reserved:
    • a custom forward on one of them is ignored;
    • addPortForward refuses them.

Flutter:

  • Error card. The Desktop screen shows an error card with View desktop log (Copy and Refresh) for:
    • start failures;
    • install failures;
    • failures the guest recorded while the app was in the background.
  • Install shows a progress bar and the current package.
  • Opening the viewer first checks that the desktop is running. The status is refreshed when the app returns to the foreground.
  • Viewer URL: http://127.0.0.1:<web_port>/vnc.html?autoconnect=true&resize=scale&reconnect=true&reconnect_delay=2000&show_dot=true&path=websockify
  • "Fit this screen" resolution, worked out from the device's aspect ratio at 720 px high. For example 1600×720 on a 20:9 phone, 1152×720 on a 16:10 tablet. The width is a multiple of 8.
  • Remembered settings. The resolution and environment of the last session are pre-selected.
  • Home card: Start uses the saved settings and shows the reason when it fails, with a Details action.
  • Calculator button fixed: it sent calc.
  • Touch tips now match noVNC 1.6's gestures and keyboard button.
  • CHANGELOG.md: Unreleased entry.

Mobile usability: what is and isn't covered

  • Scaling: resize=scale. resize=remote would do nothing, because x11vnc cannot resize the Xvfb screen.
  • Reconnect: reconnect=true with a 2 s delay.
  • Right click and scroll: noVNC's two-finger tap, long press and two-finger drag, now documented in the tips.
  • On-screen keyboard: noVNC has no URL parameter that opens it. It is the keyboard button in noVNC's left-edge control bar, and the tips now say so. A floating keyboard button would need our own WebView viewer with injected JS. That is not in this PR.

Relation to #34

Based on main, as requested. #34 changes init_bootstrap.sh, _build_rootfs.sh, api_server.py and the VM lifecycle. This PR keeps out of those hunks:

Relation to #26

#26 says: tapping Start, or Install & Start, shows a success message but no desktop starts, and there is no reason. After this PR:

  • a start can't report success unless all four components are up;
  • an install can't report success unless apk succeeded;
  • every failure shows its component and log.

Likely causes this PR removes:

  • The Home button started Openbox when only XFCE was installed, and silently began installing it.
  • The installer killed a running apk.
  • An XFCE install hit the 600 s timeout.
  • The viewer opened localhost while the forward is IPv4 only.

I can't confirm which of these the reporter hit without a device, so this says Refs #26. Close #26 after the device test below passes.

Checks run

  • shellcheck (koalaman/shellcheck:stable -s sh):
    • linxr-desktop.sh: 0 findings (main: 10: SC2046 ×2, SC2013 ×2, SC2235 ×5, SC2034 ×1).
    • init_bootstrap.sh is not touched.
  • Guest functional test in an arm64 alpine:3.24 container: Alpine 3.24.4, the image's branch. Python 3.14.10, websockify 0.13.0, noVNC 1.6.0, x11vnc 0.9.17, tint2 17.1.3. It ran natively, not under TCG.
    • End to end, Openbox and XFCE: vnc.html returns 200, the WebSocket upgrade on /websockify returns 101, and x11vnc's banner RFB 003.008 arrives through websockify.
    • Repeated start and stop: start/stop/restart 3 times via the CLI and 3 times via the API, each followed by the RFB handshake.
    • Idempotent start: 0.08 s when the desktop already runs. A resolution change restarts Xvfb at the new size.
    • Crashes:
      • kill -9 x11vnc or websockify: restarted within 5 s, and the handshake works again.
      • kill -9 Xvfb: state failed, error "Xvfb exited unexpectedly…".
    • Busy ports: with 5900 or 6080 already taken, start fails with "Port 6080 is already in use by another process" (API: 500 with detail).
    • Simulated VM reboot (processes killed, /run and /var/log state cleared): status stopped, and Start brings XFCE back with the saved settings.
    • Apps: xterm; touch /tmp/p is rejected (exit 2, API 400) and nothing runs. Starting an app while the desktop is stopped returns exit 4 (API 409). terminal, files and calculator open.
    • Install:
      • progress is parsed;
      • an unreachable mirror gives install_state=failed with "Could not reach the Alpine package mirror… galculator (no such package)";
      • v3.20 repositories on a 3.24 image are rewritten to v3.24;
      • the API returns 202 and then ok.
    • Found and fixed during testing: tint2 17.1.3 segfaults when the xterm and galculator launchers share the panel (the config is in the script comment).
  • api_server.py:
  • Flutter 3.44.0 (ghcr.io/cirruslabs/flutter:stable):
    • flutter analyze: 0 errors and the same 6 warnings as main; 124 issues in total against 122 on main. The 2 extra are withOpacity deprecation infos in the new error card. That is the file's existing style: the builder is pinned to Flutter 3.22 (CHANGELOG NEW-1).
    • flutter test: 20 passed (11 on main). The new tests cover:
      • the viewer URL;
      • "Fit this screen";
      • the resolution options and their validation;
      • install progress parsing;
      • waitForInstall with failures and a missed poll;
      • a failed start rethrowing the guest error and not reporting running;
      • a reply without running=true not counting as success;
      • getDesktopLog arguments.
  • Kotlin: not compiled. I tried ./gradlew :app:compileDebugKotlin twice in the Flutter container, once with -Xmx1536m. Both times the Gradle daemon was killed ("daemon disappeared unexpectedly") in the 4 GB Colima VM, before Kotlin compilation started. The Kotlin changes are small and were reviewed by hand. They need a compile in CI or locally.
  • Not run: APK build, a device or emulator, and timing under real QEMU TCG.

Device test checklist

Use a fresh install of this build on an arm64 phone. Keep "LAN access" off unless a step says otherwise.

  1. Install from scratch. Start the VM and open Home > Virtual Desktop > Configure.
    • Choose Openbox and tap Install & Start Desktop.
    • The progress bar moves and the current package is shown.
    • When it ends, the desktop starts and the status says "Virtual Desktop Active".
  2. Open the viewer. Tap Launch Virtual Desktop (In-App).
    • noVNC connects without a "Failed to connect" page, the tint2 panel is visible, and an xterm is open.
  3. Touch.
    • Tap clicks.
    • Two-finger tap on the background opens the Openbox menu.
    • Long press right-clicks.
    • Two-finger drag scrolls in xterm or pcmanfm.
    • One-finger drag moves a window.
  4. Keyboard. Open noVNC's left-edge tab and tap the keyboard icon.
    • Type echo |<>~ in xterm and check that the symbols come out right (-xkb).
  5. Background and reconnect.
    • Switch to another app for 2 minutes, then come back: noVNC reconnects by itself.
    • Back in Linxr, the Desktop screen shows the right state.
  6. Quick apps.
    • Terminal, File Manager, Text Editor and Calculator each open a window.
  7. Start, stop, restart.
    • Stop and Start 3 times in a row: each start ends in "Active" or a clear error.
    • Change the resolution to Fit this screen and start: the desktop fills the Custom Tab in landscape, with no black bars.
  8. Honest errors.
    • In the Terminal tab, run kill -9 $(cat /run/linxr-desktop/xvfb.pid). Within about 10 s the Desktop screen shows "The desktop stopped: Xvfb exited unexpectedly…".
    • View desktop log shows the logs.
    • Start works again.
  9. Supervision.
    • Run kill -9 $(cat /run/linxr-desktop/x11vnc.pid). The viewer reconnects within about 10 s.
    • linxr-desktop log desktop shows "x11vnc exited; restarting (1/5)".
  10. Install failure.
    • Turn off Wi-Fi and mobile data, choose XFCE, and tap Install. The screen shows "Install failed: … Could not reach the Alpine package mirror …", not success.
  11. XFCE.
    • Turn data back on, install and start XFCE. The panel, desktop icons and xfce4-terminal work.
    • Note the start time under TCG: it must stay under 180 s.
    • Note the idle CPU in top with the viewer open.
  12. Home card.
    • With XFCE as the last session, stop the desktop and use Start Desktop on the Home card. XFCE starts, not Openbox.
  13. VM reboot.
    • Stop and start the VM. The Desktop screen shows "Desktop Stopped" with the last resolution and environment selected.
    • Start works.
  14. Reserved ports.
    • In Containers > port forwards, adding host port 6080 is refused with "reserved by Linxr".
  15. Performance.
    • Compare top CPU of x11vnc idle and while dragging a window, before and after this build. The new flags are meant to lower it.

…n start

linxr-desktop start used to report success once websockify listened on
6080 and any recorded pid was alive, so it could return success with
x11vnc or the window manager dead, and the viewer then failed with no
reason given (#26).

- One supervisor owns Xvfb, D-Bus, the window manager, panel, x11vnc and
  websockify, restarts any of them that exits (5 times in 10 minutes) and
  ends the session cleanly when Xvfb dies. State and pids live in
  /run/linxr-desktop, logs in /var/log/linxr-desktop.
- start waits until Xvfb has opened :1, the WM runs, x11vnc listens on
  5900 and websockify on 6080, or fails naming the component with its
  last log lines. start, stop and restart are idempotent; settings are
  saved in /etc/linxr/desktop.conf so Start works after a VM reboot.
- app launches only allow-listed apps (no eval); JSON output is escaped.
- install logs apk progress, waits for the apk lock instead of killing
  apk, fixes a repository branch that does not match the image, checks
  free space, and adds galculator, dbus-x11 and xsetroot.
- x11vnc: -noncache -noxrecord -nowf -noscr -xkb.
- /desktop/start validates the resolution and environment, serialises
  starts, and returns 200 only when every component is up; otherwise it
  returns the guest's error (409 for not installed or busy, 500 for a
  failed component, 504 on a hung script) with the status fields.
- /desktop/install starts the install in the background and returns 202;
  /desktop/status reports install_state, install_progress, install_step
  and install_error, so a long XFCE install no longer hits the 600 s
  timeout and failures are not reported as success.
- /desktop/status reads the supervisor's state files: running means the
  processes are alive (not zombies) and ports 5900 and 6080 listen.
- New GET /desktop/log (token required) returns one component log or a
  combined summary.
- /desktop/app rejects anything outside the allow-list.
- The Desktop screen shows why a start or install failed, with a
  "View desktop log" dialog, and also shows failures recorded by the
  guest (for example Xvfb exited while the app was in the background).
- Installing shows apk's progress and a progress bar by polling the
  status; the start only reports success when the guest says running.
- The viewer opens 127.0.0.1 (the port forward is IPv4 only) with
  reconnect_delay, after checking the desktop is up; status is refreshed
  when the app returns to the foreground.
- "Fit this screen" resolution from the device aspect ratio.
- Calculator button sent "calc"; it now sends "calculator".
- Touch tips describe noVNC's real gestures and the on-screen keyboard.
- Kotlin: desktop calls surface the API's "detail" message, start uses a
  330 s read timeout, new getDesktopLog channel method, and custom port
  forwards can no longer take host ports 2222, 7081, 6080 or 5900.
The Home screen's Start Desktop button always started 1280x720 Openbox,
even when the user had set up XFCE only; the old launcher then silently
began installing Openbox. It now uses the resolution and environment of
the last session and shows the guest's reason, with a Details action
that opens the Desktop screen, when the start fails.
@skalvinnathan
skalvinnathan merged commit 02d4744 into main Nov 19, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[bug] Virtual Desktop (GUI)

1 participant