w waymux

Apache-2.0 · Linux GUI automation · CPU and GPU

Headless Linux GUI sessions you can
script, screenshot, and record.

waymux gives each session its own off-screen display, kept entirely separate from your real one. Launch a single app or a whole Linux desktop, drive it from your code or an AI agent, and capture it as screenshots or lossless video. With no GPU it runs entirely on the CPU, so it drops straight into CI. With a GPU it adds hardware-accelerated recording and live streaming.

CPU and GPU lossless recording code + AI agents KDE Plasma 6 runs X11 apps too
Get started View source 
# One binary. The first command starts the background service for you.
waymux new demo --size 1920x1080
waymux spawn demo -- foot           # launch an app into the session
waymux wait demo --app-id foot
waymux screenshot-desktop demo -o demo.png
waymux record start demo            # lossless video
waymux record stop demo
waymux rm demo

What you can do

Off-screen sessions

Each session is its own isolated display, in its own process, with nothing drawn to your real screen. Ever.

Run apps and desktops

Open a single app (a browser, a terminal, an editor) or a whole desktop. KDE Plasma 6 and other Wayland desktops run inside a session.

Drive it from code

Send keyboard, mouse, and touch input; wait for a window to appear. Every command speaks JSON, so it scripts cleanly.

Screenshot and record

Capture any window or the whole desktop. Record lossless FFV1 in software (~36 fps for a focused app, ~10 fps whole-desktop, no GPU) or with your GPU's hardware H.264 and HEVC encoders. See the benchmarks.

Test in CI, no GPU

It all runs in software, so you can launch real apps, click through them, and check what they drew on a stock CI runner. No GPU, no display.

Agent-ready

An MCP server lets AI agents drive a session through the same commands you use: spin up a desktop, run a task, and replay what happened.

Drops into CI, no GPU

The whole stack runs without a GPU, the way a virtual display lets you test desktop apps headlessly. Published Docker images bundle everything (the binaries, software rendering, and a couple of real apps), and waymux-run is the wrapper: it creates a session, runs your command against it, and saves a screenshot and a recording. 

# Run your test command in a fresh, off-screen session.
docker run --rm --entrypoint dbus-run-session ghcr.io/waymux/waymux-ci \
  -- waymux-run --record -- ./run-gui-tests.sh

There is a GitHub Action (uses: waymux/waymux@v1) and a GitLab CI template, and the demo pipeline even renders a full KDE Plasma 6 desktop on a free runner with no GPU. See the CI guide.

Runs on your machine

waymux runs entirely on your own computer. A small per-user background service does the work, reachable only by you. No account, no telemetry, no phone-home. The only network access is what you turn on yourself: the optional in-browser viewer, or a server you point it at.