Remote GUI over SSH¶
What it is¶
With the SSH service a remote session
cannot open a window on the host's screen, so by default the GUI launchers
(jb ide, jb chrome, jb firefox, jb browser, jb apps run) are
host-only. With remote.ssh.rdp on, they instead draw on a shared RDP
display: a small jailbee-display container running the weston compositor
(RDP backend, software rendering). You tunnel its port over the existing SSH
connection and view it in a compatible RDP client.
There is one shared screen for all containers, not a separate screen per container. Apps from different containers appear side by side on it.
This page covers two ways to see the windows. The RDP display needs
remote.ssh.rdp: true and is off by default. Native windows over waypipe ssh
need no configuration: remote.ssh.waypipe is on by default (see
below).
Turn it on¶
On the Linux host, with the SSH service already installed and enabled:
- Set
remote.ssh.rdp: truein~/.config/jailbee/global.yaml(seeremote.ssh). - Run
jb display up. The first run downloads an image and installs the display packages, which can take a few minutes. Later runs reuse the container, starting it or completing provisioning if needed.
The flag is re-read for new SSH sessions and forwarded connections, so no
jb remote ssh restart is needed for new requests to see a change. Existing
sessions retain their GUI setting. Disabling the flag does not disconnect an
existing RDP connection, close apps, or remove an already attached display
mount. With RDP enabled, containers acquire the display mount at
their next start or first GUI launch; jb display up warns if rdp is off.
jb display up prints the connection recipe; jb display status prints it
when the display container and its service are running.
Connect¶
On your own computer, open a tunnel to JailBee's SSH service (replace the placeholders):
ssh -N -o ExitOnForwardFailure=yes \
-L 127.0.0.1:3389:127.0.0.1:13389 -p <ssh-port> jailbee@<host>
Keep this command running, then point an RDP client at 127.0.0.1:3389. If
local port 3389 is already in use, change the first port and use that port in
the client. The explicit loopback bind keeps the local tunnel off your LAN.
ExitOnForwardFailure catches failure to open the local listener; it does not
prove the RDP service at the far end is ready.
Use an RDP client that supports TLS without Network Level Authentication
(NLA), such as mstsc on Windows, Windows App (formerly Microsoft Remote
Desktop) on macOS, or xfreerdp / Remmina on Linux. Client settings or policy
that require NLA can prevent a connection. The display checks no credentials;
if the client asks for a login, use dummy values, not a real password (see
Security). It presents a self-signed certificate;
accept it only for the display you intended to reach through the SSH tunnel.
The SSH service listens on 127.0.0.1:8022 by default, so a remote machine
cannot reach it directly at <host>:8022. Use the host's own sshd as a jump
host rather than exposing a new listener just for this tunnel.
Using JailBee from a Mac has a ready
~/.ssh/config entry using ProxyJump; that SSH configuration also works on
Linux and Windows with OpenSSH. The Mac page includes the Windows App steps.
In an interactive OpenSSH session with a pseudo-terminal and
EnableEscapeCommandline yes enabled on the client, type ~C at the start of
a line, then -L 127.0.0.1:3389:127.0.0.1:13389. The escape command line is
disabled by default in current OpenSSH; otherwise open the separate tunnel
above. To request the forward whenever you connect through a particular
~/.ssh/config host entry, add
LocalForward 127.0.0.1:3389 127.0.0.1:13389 there. A second independent
connection cannot bind the same local port.
The server accepts this TCP forward from any authenticated SSH key while
remote.ssh.rdp is on, and only to 127.0.0.1:13389. Command permissions and
repository exclusions do not restrict access to the shared RDP screen. You
can connect before or after launching anything.
Launch¶
Run jb chrome, jb ide or jb apps run from an SSH session, or choose a
launch in the remote dashboard. To launch an arbitrary command, use
jb exec <name> -d --gui -- <cmd>; a plain jb exec -d never touches the
shared display, so detached builds and servers are unaffected. After preparing
the display, the launcher waits about two minutes for an RDP client, printing
the recipe if none is connected yet. It checks for an established TCP
connection and checks again after three seconds before launching. This is a
readiness heuristic, not verification that the RDP handshake or input seat is
ready. Display startup and polling can make the total wait longer. If the wait
fails, connect a client and run the launch again.
Autostart apps launched from an SSH session with rdp on target the shared
display too, but never move an already-running browser: it may receive the
request on its existing display. Use an explicit browser launch to move it.
If display preparation fails, the failure is reported and the remaining apps
in that autostart run are skipped. Foreground commands may wait for this;
background commands return first and report the result in the worker log.
GUI autostart does not guarantee that all deferred autostart stages have
finished.
Native windows with waypipe¶
On a Linux laptop with a Wayland session and
waypipe installed, a
waypipe ssh session carries the apps' windows to your own desktop as native
windows. They close with the session. A Mac can do the same with the
Cocoa-Way compositor; see
Using JailBee from a Mac.
Choose RDP instead on Windows, and for windows that must survive a disconnect.
On by default (remote.ssh.waypipe; a waypipe session is refused if you turn it
off), so it needs no configuration beyond a stock waypipe client. JailBee runs the server-side waypipe in jailbee-display,
not as a host-installed binary. Open the dashboard and launch from its menu:
waypipe ssh -o ControlPath=none -t -p <ssh-port> jailbee@<host> dashboard
The -t is needed for the dashboard. A launch from the dashboard that fails
shows only the exit-code notice, not the launcher's message. To run one app
directly:
waypipe ssh -o ControlPath=none -p <ssh-port> \
jailbee@<host> chrome <container> --repo <prefix>
The direct command waits until the app exits, and the session ends with it.
--repo <prefix> selects a registered repo explicitly. Without it, a single
visible repo is used automatically; several need -t for a picker (otherwise
exit 2 lists them).
- The direct form is for the GUI launchers (
chrome,firefox,browser,ide,apps run).exec --guidetaches, so its window closes as soon as the session ends; start it from the dashboard instead. - If Chrome hands the request to an existing instance rather than starting a
new one, the attached command returns at once and its new waypipe session
ends. An instance on another display normally triggers the move policy
below;
--no-moveleaves it on that other display. -
Use a separate SSH connection for each waypipe session. The server associates waypipe state with the SSH connection, so later sessions sharing a
ControlMaster/ControlPersistconnection can fail. The examples disable sharing with-o ControlPath=none;ControlMaster=noalone can still reuse an existing control socket. -
Window titles carry the full Incus name, for example
[myproject-feat-x], so windows from different repositories and containers can be told apart. - Each session runs one waypipe server per container, as a transient unit in
jailbee-display; stopping the session stops them, and with them every window. Each container reaches only its own servers (see Security). - The client's
--compressis honoured (waypipe --compress zstd ssh ...). The other waypipe options (--threads,--video,--no-gpu) are the laptop's own; the server does not use them. - Not supported:
--oneshot,--xwlsand--remote-bin. The error names the supported form. - An allowed waypipe session automatically prepares
jailbee-display, including installing waypipe if an older display lacks it. Provisioning can take a few minutes; a complete, running display is reused. No RDP client is needed.
The command parser accepts what waypipe 0.11 sends; 0.8 and 0.9 clients are untested.
An app already open on another display¶
Chrome and Firefox run once per profile: a second launch hands its URL to
the running browser, which can only draw where it started. When jb chrome
(or jb firefox, jb browser, jb apps run) finds the browser open on a
different display — the host, the shared RDP display, a waypipe session — it
closes it there and starts it again here, with the same profile. On an
interactive terminal it asks first; without interactive prompting (for example,
a waypipe ssh command without -t or a dashboard action) it moves by default.
--move requests the move without asking. --no-move leaves the browser on
its old display and sends the launch request there; it does not cancel the
launch. This browser-specific check does not apply to arbitrary exec --gui
commands, IDEs or custom apps.
When moving Chrome, JailBee adds --restore-last-session to request tab
restoration. Firefox relies on its own session settings, such as Open previous
windows and tabs (browser.startup.page = 3); restoration is browser behavior,
not a backup of unsaved work. JailBee sends SIGTERM and waits with a 15-second
budget for both the browser process and its profile lock to disappear. If
shutdown does not finish, it does not force-kill the browser and the new launch
fails; close it on the other display and retry.
What it does not do¶
- No RDP authentication. Any login is accepted; access is limited by network reachability and the SSH tunnel (see Security).
- On the RDP display, window titles do not name the container; two Chrome windows from two containers look alike. (Waypipe sessions prefix them.)
- No GPU. Rendering is in software.
- One RDP screen for all containers, and one shared clipboard. Neither SSH command permissions nor repository exclusions isolate its windows.
jb gui(the Qt dashboard) stays a host command.- When SSH repository exclusions are active (
remote.ssh.excluded_reposis non-empty), the GUI launchers (ide, the browsers,apps run) are refused over SSH even withrdporwaypipeon, because the scoped command allow-list does not include them.jb exec -d --guiis in that list and remains available for visible repositories if the command policy permitsexec. This command restriction does not prevent forwarding to the shared RDP screen.
Security¶
See Remote GUI in the security model.
Troubleshooting¶
jb display statusshows whether the container and its service are running.- On the host,
jb display up --recreatedeletes and rebuilds the shared display container. Save work first: this interrupts apps using either its RDP compositor or its waypipe servers, across containers and sessions. jb display downstops the display container and interrupts those display connections too. The SSH connection and local forwarding listener may stay open, but RDP connections cannot reach the stopped display. A later GUI launch can start it again whilerdporwaypiperemains enabled.- For a refused forward (
administratively prohibitedinssh -v), checkremote.ssh.rdpand the destination127.0.0.1:13389(localhostdoes not count). The server also refuses forwarding if it cannot reload the GUI setting; check the SSH service log for configuration errors. - "No seats available" from an app means the compositor's input seat was not ready. Connect an RDP client fully, then launch again; the TCP readiness check cannot prove that the seat exists.
- A container that was already running when the feature was enabled gets the display directory mounted at its next start, or on the first GUI launch.