Skip to content
aos

Headless machines

Most of the surface needs no screen. On a server, in CI, or in a container, exec, file, pkg, network, system, power, battery, font, debug and serve work exactly as they do on a laptop.

What the machine says about itself

Section titled “What the machine says about itself”
Terminal window
$ aos headless status
platform     darwin
virtual      not available on this platform
note         desktop commands need a logged-in session here


display      yes — window, mouse, key, capture, and display commands will work

The desktop commands refuse, rather than fail deep

Section titled “The desktop commands refuse, rather than fail deep”
Terminal window
$ aos window list
aos: "window list" needs a display, and this machine has none
Start one with `aos headless start`, or check `aos headless status`.

On Linux, give it a display

Section titled “On Linux, give it a display”
Terminal window
aos headless start --size=1920x1080 --wm   # Xvfb + a lightweight WM
aos window list                            # the display is adopted automatically
aos headless stop

headless start waits for the window manager to claim the screen before it returns, so the next command works instead of losing a race with it. Later runs of aos adopt the managed display on their own — there is no export DISPLAY step. An environment that already names a display always wins, so this never redirects a real session.

macOS and Windows have no Xvfb equivalent. There, the desktop commands need a real logged-in session, and headless status says exactly that.

Knowing in advance what will work

Section titled “Knowing in advance what will work”
Terminal window
aos headless status       # is there a display, and where did it come from
aos commands              # screenless machines list only what will run
aos commands --all        # `g` marks a command waiting on a display
aos commands --json       # each entry carries "needs_display"
aos serve mcp --gui=off   # expose only the screenless tools

It is tested this way

Section titled “It is tested this way”

The end-to-end suite drives the built binaries on real machines, and on a machine configured hasDisplay: false it asserts the refusal — window list must exit 2 saying it needs a display — rather than skipping quietly.