codex-computer-use-linux

Codex Computer Use for Linux is an open-source Linux computer-use MCP server and Codex skill for controlled desktop GUI automation. It gives Codex a deliberately small tool surface for working with visible native applications while keeping sensitive workflows out of scope.

OpenAI's current Computer Use plugin supports macOS and Windows, while Codex can connect to local STDIO MCP servers. This project fills the Linux integration gap with an MCP action layer and a skill that teaches Codex the safe observe → act → verify loop. See the official Computer Use and MCP documentation for the product boundaries.

Why MCP plus a skill?

A skill alone cannot reliably provide live screenshots or controlled input. An MCP server alone does not teach the model a safe visual workflow. The hybrid plugin follows OpenAI's documented plugin architecture.

Related MCP server: desk-mcp

What it does

• Linux-only runtime guard; no silent macOS or Windows fallback.

• Wayland input through ydotool; X11 input through xdotool with ydotool fallback.

• Screenshots through grim, gnome-screenshot, scrot, or ImageMagick import.

• Typed MCP tools for status, screenshot, pointer movement, click, drag, text, keys, and scroll.

• No arbitrary shell tool, application launcher, clipboard reader, or secret store access.

• Best-effort blocking of terminals, ChatGPT, and Codex when the active window is discoverable.

• Structured Doctor output and in-memory MCP contract tests.

• Installable Codex plugin plus direct MCP-server setup.

Quick start

Requirements

• Linux with an active graphical session.

• Python 3.11 or newer.

• One screenshot backend.

• One input backend.

Install only the packages relevant to your desktop. Typical package names are:

# Debian / Ubuntu
sudo apt install python3 python3-venv xdotool gnome-screenshot ydotool grim

# Fedora
sudo dnf install python3 xdotool gnome-screenshot ydotool grim

# Arch Linux
sudo pacman -S python xdotool gnome-screenshot ydotool grim

Package availability differs by distribution and desktop environment. On Wayland, configure and start ydotoold according to your distribution. The upstream ydotool documentation explains its /dev/uinput permission model; do not run Codex itself as root.

Install

Install the server CLI with one of these isolated Python tool managers:

uv tool install git+https://github.com/maxionice/codex-computer-use-linux.git

or:

pipx install git+https://github.com/maxionice/codex-computer-use-linux.git

Run the Doctor before connecting Codex:

codex-computer-use-linux --doctor

Option A: install the Codex plugin

codex plugin marketplace add maxionice/codex-computer-use-linux
codex plugin add codex-computer-use-linux@maxionice-linux-tools

Start a new Codex thread after installing so the skill and MCP tools are loaded.

Option B: add only the MCP server

codex mcp add linux-desktop -- codex-computer-use-linux
codex mcp list

For approval on input-producing tools, configure default_tools_approval_mode = "writes" for the server in ~/.codex/config.toml.

Example prompts

Use $use-linux-desktop to open the app's settings and verify that dark mode works.

Inspect the visible calculator app, enter 125 * 8, and report the displayed result.

Reproduce the onboarding bug in the already-open Linux app. Stop before any login prompt.

MCP tools

The server never accepts a command string or invokes a shell. Every native command is constructed from validated typed arguments.

Safety model

Desktop automation can act with your logged-in user's permissions and screenshots may contain sensitive data. Keep the target app visible, close unrelated sensitive apps, and review every approval prompt.

The bundled skill refuses terminal, ChatGPT, Codex, credential, administrator, security, payment, and privacy-setting flows. Active-window blocking is best effort because some Wayland compositors do not expose the focused application. Read the complete safety model before use.

Development

git clone https://github.com/maxionice/codex-computer-use-linux.git
cd codex-computer-use-linux
python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
python -m ruff format --check .
python -m ruff check .
python -m mypy src
python -m pytest

The project uses the stable MCP Python SDK 2.x, which supports the 2026-07-28 MCP specification. See the official MCP Python SDK.

Uninstall and rollback

codex plugin remove codex-computer-use-linux
codex plugin marketplace remove maxionice-linux-tools
codex mcp remove linux-desktop
uv tool uninstall codex-computer-use-linux

If you installed with pipx, replace the final command with pipx uninstall codex-computer-use-linux. Removing the plugin or MCP entry stops Codex from launching the server; removing the tool installation deletes the local executable. System packages such as ydotool are not removed automatically.

Trademark and affiliation

This is an independent open-source project and is not affiliated with or endorsed by OpenAI. OpenAI, Codex, ChatGPT, and related marks belong to their respective owners.

License

Apache-2.0. See LICENSE.