Skip to content

vnc-linux.md

Latest commit

 

History

History
202 lines (158 loc) · 8.18 KB

vnc-linux.md

File metadata and controls

202 lines (158 loc) · 8.18 KB
Raw

Linux VNC

Read when:

  • using --desktop on a managed Linux lease (Hetzner, AWS, or Azure);
  • choosing a desktop environment with --desktop-env (xfce, wayland, gnome);
  • debugging TigerVNC, the window-manager session, WayVNC, or screenshots on a Linux lease;
  • preparing a static (BYO) Linux host to serve a Crabbox VNC desktop.

Linux is the simplest managed desktop path. A managed Linux lease bootstraps a lightweight desktop, runs it on DISPLAY=:99, binds a VNC server to loopback, and lets the CLI tunnel into it over SSH.

Managed Linux

crabbox warmup --desktop --browser
crabbox run --id swift-crab --desktop --browser -- google-chrome --version
crabbox desktop doctor --id swift-crab
crabbox webvnc --id swift-crab --open
crabbox vnc --id swift-crab --open
crabbox screenshot --id swift-crab --output linux.png

The default desktop environment is XFCE. Request a different one at warm time:

crabbox warmup --desktop --desktop-env wayland
crabbox warmup --desktop --desktop-env gnome

A managed Linux desktop lease provides:

  • resize-capable TigerVNC on :99 (XFCE) or a Wayland compositor (wayland/gnome);
  • a window-manager / desktop session (xfce4-session with xfwm4, xfce4-panel, and xfce4-terminal for XFCE);
  • TigerVNC (XFCE) or WayVNC (wayland/gnome) bound to 127.0.0.1:5900;
  • screenshot and video capture tools (scrot and ffmpeg);
  • input helpers (xdotool, wmctrl) and clipboard tools (xclip/xsel);
  • a generated per-lease VNC password at /var/lib/crabbox/vnc.password;
  • the resolved desktop environment recorded in /var/lib/crabbox/desktop.env (CRABBOX_DESKTOP_ENV, DISPLAY, and Wayland variables where applicable);
  • optional Chrome stable (Chromium fallback) with first-run suppression and a managed policy when --browser is requested;
  • readiness checks that verify the desktop services when the lease carries desktop=true.

Reusing a lease requires matching capability labels: a lease warmed without --desktop (or with a different --desktop-env) cannot gain the desktop after creation.

Window sizing

Linux portal viewers default to Match window. The connected controller requests a desktop resolution matching the available browser area, including fullscreen changes. Observers never request a resize. Fit desktop scales the current desktop without changing its resolution. Both modes keep the desktop visible while the server handles a request; selecting Match does not prove the server accepted it.

New XFCE local-container desktops and the public Linux desktop installer use TigerVNC, like managed cloud XFCE desktops. Existing Xvfb/x11vnc containers remain usable at their fixed resolution; recreate those leases for resizing. The installer keeps CRABBOX_DESKTOP_GEOMETRY=1920x1080x24 as its initial size and depth, not a permanent size limit. Depths 16, 24, and 32 use TigerVNC. The 8-bit input still selects the fixed-size Xvfb/x11vnc backend because TigerVNC cannot start at depth 8; the installer never silently changes the requested depth. The installer selects an 8-bit TrueColor default visual so XFCE clients render instead of leaving blank client areas with Xvfb's default PseudoColor visual, as reported in issue 2218. Use the default 24-bit geometry when a resize-capable desktop is needed.

The wayland and gnome profiles need a resize-capable WayVNC and a headless compositor output. Actual Ubuntu 26.04 packages include WayVNC 0.9.1; Ubuntu 24.04's WayVNC 0.7.2 does not support client-requested resizing. Check the guest's actual wayvnc --version and /etc/os-release: the OS selector alone is not proof. In particular, Hetzner's ubuntu:26.04 selector currently maps to an Ubuntu 24.04 image.

WayVNC gives layout ownership to the first client that requests a resize, until that client disconnects. Changing to Fit, becoming an observer, or transferring Crabbox input control does not release that ownership. With a compatible coordinator, managed Wayland portal bridges automatically retire the previous controller's exact remote client and wait for WayVNC's acknowledgement before enabling the new controller's resize requests. This disconnects the previous viewer, which may reconnect as an observer. If the control socket is unavailable, another unmanaged client is present, or retirement cannot be verified within the deadline, the portal retains the manual reminder: close the previous sizing viewer, then reconnect the new controller. Older coordinators and ordinary SSH/native viewers retain this manual behavior. See WayVNC handoff for the identity and acknowledgement contract. GNOME applications use Xwayland inside labwc, not a full GNOME Shell session.

Direct Linux SSH viewers keep noVNC's Local scaling default so fixed-size desktops still fit the browser. For a supported server, select Settings > Scaling mode > Remote resizing; return to Local scaling if the server cannot resize. Generic local handoff viewers, macOS, and Windows keep Fit desktop as the default; their Match window option also requires server support.

Injected environment

crabbox run --desktop resolves the recorded desktop environment, then:

  • always sets CRABBOX_DESKTOP=1;
  • for XFCE, sets DISPLAY=:99;
  • for wayland/gnome, sources /var/lib/crabbox/desktop.env and forwards XDG_RUNTIME_DIR, WAYLAND_DISPLAY, and related variables.

crabbox run --browser probes the target, then sets CRABBOX_BROWSER=1 plus BROWSER and CHROME_BIN (pointing at the resolved Chrome/Chromium wrapper).

Static Linux

Static Linux (provider: ssh) is host-managed. Crabbox does not install packages or start a desktop service on a preexisting machine. The host must already serve a VNC server reachable from SSH loopback:

provider: ssh
target: linux
static:
  host: linux-box.tailnet-name.ts.net
  user: crabbox
  port: "22"
  workRoot: /home/crabbox/work
crabbox vnc --provider ssh --target linux --static-host linux-box.tailnet-name.ts.net

Keep x11vnc (or another VNC server) bound to 127.0.0.1:5900. A direct host:5900 connection is accepted only when reachable and should be limited to a trusted LAN or tailnet.

Troubleshooting

lease ... was not created with desktop=true

Warm a new lease with --desktop; existing leases do not gain the capability after creation.

lease ... was not created with desktopEnv=<env>

The lease was warmed with a different desktop environment. Warm a fresh lease with the matching --desktop-env.

target=linux does not expose a loopback X11 VNC desktop

For managed leases, inspect the crabbox-xvfb.service TigerVNC unit and desktop session logs or warm a fresh box. For static hosts, start Xvfb/x11vnc on 127.0.0.1:5900, or warm with --desktop-env wayland or --desktop-env gnome for a configured Wayland target.

target=linux does not expose a Crabbox Wayland desktop

Create /var/lib/crabbox/desktop.env with CRABBOX_DESKTOP_ENV=wayland (or gnome), XDG_RUNTIME_DIR, and WAYLAND_DISPLAY, then start the compositor and WayVNC on 127.0.0.1:5900.

Black screen

Confirm the app launched into the desktop session. For detached browser work, use:

crabbox desktop launch --id swift-crab --browser --url https://example.com

Run crabbox desktop doctor --id swift-crab to separate session problems from WebVNC/browser-portal problems; it reports a specific repair line per missing component (window manager, panel, VNC server, clipboard tools, browser, ffmpeg, screen size, or screenshot capture).

Input symbols are wrong

Use Crabbox's desktop helpers instead of raw xdotool type:

crabbox desktop paste --id swift-crab --text "alice+qa@example.com"
crabbox desktop type --id swift-crab --text "alice+qa@example.com"

desktop type uses clipboard paste for symbol-heavy text, so @, +, password-like values, and URLs do not depend on the target X keyboard layout.

Related docs: