Wazza OS on a server
Wazza OS is a desktop app, but it does not need a screen: on a server, a cloud machine or over SSH it brings its own virtual screen, and you drive it with the command line. Its VM, apps and Chats work exactly as on a desktop.
wazza --virtual-screen=… and wazza --gui …What the server needs#
| Need | Why | How |
|---|---|---|
Hardware virtualization (KVM): /dev/kvm readable and writable | The VM runs on it | Bare metal, or a cloud machine with nested virtualization; your user in the kvm group |
| A systemd user session | Each VM runs in a memory-capped scope of it | Log in over SSH (a session
that starts it), or keep it running without a login: loginctl enable-linger "$USER" |
| The virtual-screen tools: Xvfb, xauth, openbox, dbus, ffmpeg, Python 3 | The virtual screen, its window manager, recordings | Every package installs them (the tarball's installer checks them) |
| A graphics card (optional) | 3D apps draw on it | Without one, the VM uses software graphics |
wazza --check tells what is missing, with the commands that fix it
(Check this computer). Install Wazza OS as on a desktop
(Install).
Start, set up, use, stop#
Check the machine:
$ wazza --checkStart Wazza OS in the background, with its own screen:
$ nohup wazza --virtual-screen=always >/dev/null 2>&1 &Wait until it answers:
$ until wazza --gui status >/dev/null 2>&1; do sleep 2; doneSet it up without clicks: account, logins, keys, apps (the setup file):
$ wazza --gui setup run --file ~/wazza-setup.jsonUse it: every command of the command line, and pictures of its screen:
$ wazza --gui vm list $ wazza --gui screenshot ~/wazza.pngStop it:
$ wazza --gui quit
A login that opens a browser (a plan login such as Claude or ChatGPT) prints its link in the terminal instead: open it on any computer, sign in, and paste the code it gives back into the terminal. API keys need no browser.
The virtual screen#
--virtual-screen=auto|always|never (default auto) decides where the window goes:
| Value | Wazza OS… |
|---|---|
auto (default) | uses your display when there is one, and starts its own screen when there is none |
always | always starts its own screen, even on a desktop (it then runs out of sight) |
never | never starts one: without a display, the start fails |
Its own screen is private to your user (1280 × 800, with a simple window manager) and stops when Wazza OS stops.
It is the only screen Wazza OS captures: --gui screenshot FILE.png, --gui record start FILE.mp4
and --gui record stop ID work with it, and refuse on a normal desktop (Wazza OS never captures your own
desktop). To see what a tab of the VM shows, on any screen, use Drive:
$ wazza --gui invoke modules_call drive look '{"vmId":"vm-1","tabId":"t3"}' --image-out ./t3--gui host-app launch chromium (or vlc, xmessage) opens that app of the server
on Wazza OS's own screen, and only there; host-app list and host-app stop ID follow and close
it.
Over SSH, and for other agents#
- The commands work over SSH, as the user who started Wazza OS. The SSH session must have that user's runtime
folder (
XDG_RUNTIME_DIR), as a normal login does. - An agent on another machine can use the same commands through SSH; an agent on the server itself runs them in its shell (Connect an agent from outside).
- One Wazza OS runs per user: a second start for the same user goes to the one already running.
On your own computer#
Start Wazza OS from your desktop as usual, then use wazza --gui … from any terminal of your user: the
commands work in the background and change what you see only when you ask (--focus). A tab a command
opens appears in the background, with a badge.