Linux VNC

Read when:

using --desktop on Hetzner or AWS Linux;
debugging Xvfb, XFCE/Openbox, x11vnc, or screenshots on a Linux lease;
preparing a static Linux host for Crabbox VNC.

Linux is the simplest managed desktop path. Hetzner and AWS Linux leases use the same bootstrap shape: install a lightweight desktop, run it on DISPLAY=:99, bind x11vnc to loopback, and let the CLI create an SSH tunnel.

Managed Linux

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

Managed Linux desktop leases include:

Xvfb on :99;
a lightweight desktop/window-manager session;
x11vnc bound to 127.0.0.1:5900;
screenshot and video capture tools (scrot and ffmpeg);
input helpers (xdotool) and clipboard paste tools (xclip/xsel);
a generated per-lease VNC password at /var/lib/crabbox/vnc.password;
optional Chrome stable or Chromium fallback, first-run suppression, and native addon build helpers when --browser is requested;
readiness checks that verify desktop services when desktop=true.

crabbox run --desktop injects CRABBOX_DESKTOP=1 and DISPLAY=:99. crabbox run --browser injects CRABBOX_BROWSER=1, BROWSER, and CHROME_BIN after probing the target.

Static Linux

Static Linux is host-managed. Crabbox does not install packages or start a desktop service on an existing machine. The host must already provide a VNC service 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

For static Linux, keep x11vnc or another VNC server bound to 127.0.0.1:5900. Direct host:5900 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.

target=linux does not expose a loopback VNC desktop

For managed leases, inspect cloud-init and service logs or warm a fresh box. For static hosts, start Xvfb/desktop services and x11vnc on 127.0.0.1:5900.

Black screen

Check that the app was launched into DISPLAY=:99. For detached browser work, use:

crabbox desktop launch --id blue-lobster --browser --url https://example.com

Run crabbox desktop doctor --id blue-lobster to separate session problems from WebVNC/browser-portal problems. Missing xfwm4, xfce4-panel, x11vnc, clipboard tools, browser, ffmpeg, screen size, or screenshot capture each get a specific repair line.

Input symbols are wrong

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

crabbox desktop paste --id blue-lobster --text "peter+qa@example.com"
crabbox desktop type --id blue-lobster --text "peter+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:

3.5 KiB Raw Permalink Blame History

Linux VNC

Managed Linux

Static Linux

Troubleshooting

3.5 KiB

Raw Permalink Blame History