Skip to main content
Glama
Wangxiaoxiaoa

linux-x11-sandbox

linux-x11-harness

Run Linux GUI apps in isolated X11 displays for AI agents.

CI License: MIT

English · 中文


What is this?

linux-x11-harness creates isolated X11 displays and lets AI agents control GUI applications. Each display gets its own X server, window manager, and application process group, so agents can click, type, capture screenshots, and read accessibility trees without touching the host desktop.

A live preview panel opens on your desktop while the agent works, so you can watch every click and screenshot in real time. Previews are read-only by default; double-click one to open an expanded interactive view where your mouse and keyboard directly control the sandboxed app.

Typical uses:

  • Let an agent operate a GUI app without taking over your real desktop.

  • Watch what the agent is doing live in a small preview window.

  • Run end-to-end tests that need real input, focus, and screenshots.

  • Capture accessibility trees or click UI elements programmatically.

  • Discover installed/running apps and launch them by name.

  • Invoke application menus by path and assert UI state after actions.

  • Test GUI installers, system settings, and multi-app workflows.

  • Verify accessibility compliance by auditing AT-SPI element metadata.

  • Read screen text with local OCR — works even without a vision model.

See the agent skill for concrete workflows and tool usage patterns.

Related MCP server: openowl

Quick start

Install and register with your agents in one step:

pip install linux-x11-harness
linux-x11-harness setup

After setup, open your agent and start asking it to use GUI apps. The agent will launch the harness automatically when needed.

Requirements: Python 3.10+, Rust toolchain, Linux with xvfb and openbox.

Supported agents

linux-x11-harness setup auto-configures both the MCP server and the agent skill where the agent supports them.

Agent

MCP server

Agent skill

Claude Code

✅

✅

Codex

✅

✅

Qwen

✅

—

OpenCode

✅

—

Kimi Code

—

✅

Pi

—

✅

Other MCP-compatible agents can connect manually with linux-x11-harness mcp.

Documentation

License

MIT

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    A desktop automation MCP server that enables AI agents to interact with Linux environments through screenshots, window inspection, and input simulation. It provides tools for mouse control, keyboard input, and screen capture using xdotool and XDG Desktop Portals.
    MIT
  • A
    license
    Not graded
    quality
    B
    maintenance
    An MCP server that gives any AI assistant eyes and hands on your desktop — screenshots, clicking, typing, OCR, window management, accessibility-tree queries, workflow recording.
    5
    Apache 2.0
  • F
    license
    A
    quality
    A
    maintenance
    Cross-platform desktop automation MCP server that lets AI agents capture screenshots, run OCR with UI-element classification, control mouse/keyboard, and launch programs on Linux, macOS, and Windows.
    20
    1
    -
  • 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