vmlab app

vmlab app puts one guest program's windows on the host desktop, beside the host's own windows, with no VNC console in between. It has one subcommand, run. The windows travel over the vmlab agent's virtio-serial channel in the guest family's own window protocol, so a shared app works on a machine with no guest network. A VM and a container answer the same request. Shared apps explains which protocol is used and what each side needs installed.

vmlab app run

vmlab app run [OPTIONS] <MACHINE> [-- <CMD>...]

The command reads the guest family from the machine's effective profile in the lab file: a profile whose name starts with windows is a Windows guest, and every other machine, containers included, is a Linux guest. It reads the host session from its own environment. WAYLAND_DISPLAY set means Wayland. Otherwise DISPLAY set means X11. With neither, it refuses before it sends any request.

The fall back from waypipe to x11 is the only automatic one. The command prints the reason on standard error, then the words `falling back to X11 through Xwayland`:

this host has no `waypipe` on PATH (or `waypipe` in config.wcl); falling back to X11 through Xwayland

--via picks the protocol outright and never falls back. A protocol the guest family cannot serve is refused by name.

The program runs as the machine's default login, following Logins, and --user and --password behave as they do for vmlab exec. The first word after -- is the program and the rest are its arguments. Nothing passes through a guest shell. For a Windows guest, FreeRDP names the program in its /app option, and --cwd becomes its working directory there. An argument holding an apostrophe, or another character FreeRDP's option parser would change, is refused rather than passed on altered.

The command stays in the foreground until the session ends. A waypipe or X11 session ends when the program exits, and Ctrl-C closes the session, which kills the guest program. An RDP session ends when FreeRDP exits. Ctrl-C there disconnects the Windows session and leaves the program running in it, and its windows return with the account's next shared app on that machine.

--detach makes the same protocol choice, re-runs the command as a background helper in its own session, prints this line and returns:

sharing `<cmd>` from <machine> in the background (it ends when the program does)

The helper has no terminal, so a refusal from the lab daemon is not printed anywhere. Run the command once without --detach to see one.

vmlab app run nix01 -- foot
vmlab app run --via x11 nix01 -- xterm
vmlab app run --detach dev01 -- foot
vmlab app run --user admin win01 -- notepad.exe
vmlab app run --cwd 'C:\Users\dev' win01 -- notepad.exe notes.txt

Refusals

Each refusal below is quoted from the source. The parts in braces are filled in, and a message holding backticks of its own is shown as plain text. Troubleshooting gives the cause and fix for the common ones.

Exit status is the guest program's exit code for a waypipe or X11 session, and FreeRDP's for an RDP session. Ctrl-C exits 130 and SIGTERM 143. A refusal from the lab daemon exits with its protocol error code: invalid_argument (2) for an RDP session with no account, and unsupported (6) for a guest with no waypipe or an agent that predates shared apps. failed (1) covers a refusal the command makes itself, a machine that is not running, a login that cannot be minted, a Windows edition with no RDP host, and a host client that exits mid-session.