Skip to main content
Glama

auto-linux-desk

CI version license Docker Pulls

A virtual Linux desktop in Docker that you drive over HTTP or MCP. One container runs Xvfb, the Openbox window manager, a noVNC viewer and an API that moves the real mouse with human motion, types with human rhythm, presses window manager shortcuts, arranges windows, starts programs, runs shell commands, reads and writes the clipboard, takes screenshots and records the screen.

Use it as it is for Linux desktop automation, or build your own image on it: a plugin adds actions for the software you install, such as a browser.

Quick start

docker run -d --name desk \
  -p 127.0.0.1:8080:8080 \
  -p 127.0.0.1:5900:5900 \
  psyb0t/auto-linux-desk

Open http://localhost:5900/ to watch the screen. Port 8080 serves the HTTP API and the MCP endpoint at /mcp/.

# Open a terminal with the window manager shortcut
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"action":"send_key","key":"ctrl+alt+t"}'

# Type into it with human keystrokes
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"action":"system_type","text":"uname -a\n"}'

# Or run a command directly
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"action":"run_command","command":"ls -la /userdata"}'

# Look at the screen
curl "http://localhost:8080/screenshot/desktop?whLargest=512" -o desk.png

run_command runs any command it is given and launch_app starts any program. With no AUTH_TOKEN, anyone who can reach port 8080 can run commands in the container. Set AUTH_TOKEN before exposing the port beyond loopback, or set DESK_EXEC_ENABLED=false to turn both off. See installation and security.

Related MCP server: linux-computer-mcp

What it can do

Area

Actions

Mouse

system_click, system_double_click, system_right_click, mouse_click, mouse_move, system_hover, system_mouse_down, system_mouse_up, system_drag, scroll, human_pause

Keyboard

paste_text, system_type, send_key

Keyboard shortcuts

desktop_keybindings lists the Openbox bindings: terminal, half-screen tiling, maximize, fullscreen, minimize, close, window switching

Windows

desktop_list_windows, desktop_focus_window, desktop_move_resize_window, desktop_set_window_state, desktop_close_window

Programs and shell

launch_app, list_launched, kill_launched, run_command

Screen

desktop_screenshot, get_resolution, start_recording, stop_recording, recording_status

Clipboard

set_clipboard, get_clipboard (text, HTML, PNG, file lists)

Events and handoff

get_events, wait_for_event, begin_handoff, handoff_status, end_handoff

Scripts and utility

run_script, list_actions, ping, sleep, close

Input coordinates are screen pixels. Input is sent through XTest, so every X client sees ordinary input events, with mouse paths, click timing and typing rhythm shaped like a person's.

MCP

claude mcp add --transport http desk http://localhost:8080/mcp/

Most actions have their own MCP tool, and desk_action runs any action by name. The server instructions tell agents to use window manager shortcuts from desktop_keybindings, to enter text with paste_text, and to keep system_type for a few characters.

Script mode

docker run --rm -i psyb0t/auto-linux-desk --script < script.yaml

The container runs the YAML steps, prints one JSON document on stdout and exits with 0 when every step succeeded, 1 otherwise.

Building on it

Derived images install their software and set AUTO_LINUX_DESK_PLUGINS to Python modules whose register(registry) adds or replaces actions, MCP tools, routes, screenshots, state, health checks and lifecycle hooks. See plugins and derived images.

Documentation

The full documentation is at psyb0t.github.io/docker-auto-linux-desk.

Page

Covers

Installation and security

Ports, environment variables, auth, users, volumes, hooks

Actions reference

Every endpoint, action and parameter

Keyboard shortcuts

The window manager bindings

MCP and agents

Client setup and tools

Script mode

YAML format and output

Plugins and derived images

The extension interface

Development

Make targets and tests

Development

make lint
make test-unit
make test

Everything runs in containers. make help lists all targets.

Sponsor

License

WTFPL. See the changelog for releases.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables full Linux desktop control including windows, mouse, keyboard, clipboard, audio, screenshots, OCR, accessibility, and system management through MCP-compatible AI agents.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to control a Linux/X11 desktop like a human: see the screen, move the mouse, click UI elements via the accessibility tree, type text, and manage windows.
      MIT