Minion

Give every AI agent its own computer.

Featherweight Linux desktops (office, dev, research, browser, data, Windows apps) that any agent can use:

Claude, ChatGPT, Gemini, Cursor, VS Code, LangChain, your own code, or a model running on your laptop.

Agents read the screen as text, act in batches or in code, and use any program or website.

English · 简体中文 · 繁體中文 · 한국어 · 日本語 · עברית

Get started

All you need is Docker (or OrbStack or Podman). Then pick one:

1. One click in your AI app:

Claude Code: claude plugin marketplace add apophisss/minion && claude plugin install minion@minion. Any other MCP client: uvx minion-desktop mcp, or npx -y minion-desktop mcp. The buttons, uvx and npx start Minion with uv (npx can use pipx instead); the Claude Desktop extension needs nothing else.

2. One line that installs Minion and connects every AI app on your computer (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf/Devin, Gemini CLI, Codex, LM Studio, Cline, Kiro):

curl -fsSL https://raw.githubusercontent.com/apophisss/minion/main/install.sh | sh        # macOS, Linux

irm https://raw.githubusercontent.com/apophisss/minion/main/install.ps1 | iex             # Windows

It ends with minion setup, which checks Docker, prepares a desktop and runs minion connect. Run either one again any time.

3. From ChatGPT, Claude.ai or Le Chat in the browser: run minion share and paste the URL it prints into the app's connector settings (how).

Then just ask: *"Create an office desktop, write a one-page brief about our Q3 numbers in Writer and save it as brief.docx."* Every way to install is in docs/install.md.

▶ Watch the one-minute demo : an agent researches a trip on Wikipedia, makes a budget with a chart and writes the plan as a PDF. 12 tool calls and 2,372 tokens of text; the same steps with screenshots would cost about 36,855. Recorded live with python scripts/demo_video.py , which makes the calls an agent would make.

---

Why Minion

• 🖥️ Any program, any website. Every desktop is a real Linux computer: browsers, LibreOffice, IDEs, terminals, file dialogs and installers, plus Windows programs through the windows (Wine) profile. Open any app by name and it is installed the first time (open gimp, open vscode, open dbeaver, any Debian package), web apps open in the browser (open gmail), and the first open answers with a few tips for the app. 130+ apps by name.
• 🧭 Shortcuts through every app. see --menus lists every menu command with its keyboard shortcut, and menu "File > Export as PDF" runs one without opening a menu. path ~/out.pdf fills any Open/Save dialog. Right-click menus show up in see, button:Save picks one kind of control, and a button below the fold is scrolled into view. Any document reads as text (read report.docx, xlsx with formulas, pptx, pdf) and converts in one call (convert report.docx pdf).
• 🧠 Agents read the screen as text. see turns any window into a list of controls with stable `@ids`, taken from the accessibility tree with OCR as a fallback: @12 button "Save" (210,62). Web pages, editors (with line numbers), terminals, dropdowns with their options, and spreadsheets (row by row: row 2: A2 North · B2 120) all come out as exact text. When pixels matter, screenshots can draw the @ids for you.
• 🎯 Honest actions. Every action waits for the screen to settle (for web pages to load, and while an app says "Loading…") and reports what happened: windows, a page's alert or prompt, files saved or downloaded, a pop-up that took the click. Text targets must really be on screen: a miss fails with the closest candidates instead of clicking something else. Tested on 93 everyday tasks done by AI agents.
• 🪙 Built to save tokens. You get diffs instead of re-reads (see(changes=true): about 80 tokens instead of about 900). Code mode runs a 50-step GUI loop in one call, crops and half-size screenshots cut image cost, a compact mode shrinks the tool definitions from about 3,300 tokens to 450, and the Agent Skill costs about 100 tokens until it is used.
• 🪶 Featherweight. One small container per desktop (Xvfb, a 2-process window manager and taskbar, a small agent), with no VNC and no desktop environment. Desktops are ready in about 1.5 s and use about 60 MB when idle. Idle desktops are frozen automatically (0% CPU) and wake in about 0.2 s.
• 🔌 Works with every agent. One toolset everywhere: MCP (local or remote), function calling for OpenAI, Anthropic, Gemini and local models, HTTP with OpenAPI, a CLI and an Agent Skill for shell agents, Python and TypeScript SDKs, and native adapters for Claude, OpenAI and Gemini computer use.
• ⚡ Parallel by design. create count=8 starts a desktop per worker, fork clones one before a risky step, and sessions keep agents apart.
• 🙋 Humans in the loop. A live view in the browser offers one-click *take control*, moves files both ways (drop them on the screen) and shares the clipboard. Agents can hand off ("please sign in") and wait for *Done*, and a sign-in saved once by hand starts new desktops signed in.
• 🎞️ Teach once, replay forever. Every action is recorded. Export an HTML timeline or GIF, or turn the session into a Python script that replays it with no model at all.
• 📦 Zero dependencies. The host side is pure Python standard library. Desktops run in Docker or Podman (macOS, Windows, Linux), or natively on Linux.

A quick tour from the shell

Any agent with a terminal (Claude Code, Codex CLI, Aider, Open Interpreter, Goose) can use the CLI directly, and minion skill --install teaches it how:

minion up research

minion open en.wikipedia.org # waits until the page has loaded minion fill "Search Wikipedia" "Ada Lovelace" && minion key Return minion wait-for "Analytical Engine" # says where it saw the text minion see --full # read the article as text minion select @14 "Title" # pick a dropdown option minion shot -o page.png --marks # a screenshot with @ids drawn on it minion read ~/Downloads/paper.pdf # any document as text: pdf, docx, xlsx, pptx, epub... minion open gimp # any app by name: installed the first time minion menu "File > Export As > Export as PDF..." # any menu command minion path ~/Documents/report.pdf # fill the open Save/Open dialog minion cp :~/Documents/notes.md . # copy files out (and in)

Menus, file dialogs and apps by name: menu "File > Export As > Export Directly as PDF" , path ~/Documents/report.pdf , then open gimp , which installed GIMP in 16 s. Recorded by the flight recorder.

Works with every agent

A complete agent with any OpenAI-compatible model ("anthropic", "gemini" and "openai-responses" work the same way):

from openai import OpenAI

from minion.tools import Toolkit

tk = Toolkit() client = OpenAI() # or OpenAI(base_url="http://localhost:11434/v1", api_key="ollama") for a