Featherweight Linux desktops for any agent, over MCP, function calling, HTTP, a CLI, Python or TypeScript. Agents read the screen as text with stable @ids, act in batches or in code, and use any program or website.
An agent on a research desktop, step by step, as Minion's built-in flight recorder saw it.
@1Install
Up and running in a minute.
One command installs Minion and runs minion setup, which checks Docker, prepares a desktop and connects your AI apps. Or add Minion to your app directly.
macOS and Linux
Install the minion command. No admin rights needed, and it brings uv and Python with it.
curl -fsSL https://raw.githubusercontent.com/apophisss/minion/main/install.sh | sh
It finishes with minion setup, which checks Docker, prepares a desktop and connects your AI apps. Run it again any time.
minion setup
Connect another app any time with minion connect: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf/Devin, Gemini CLI, Codex, LM Studio and more. Read the install guide
Windows
Install the minion command from PowerShell. No admin rights needed, and it brings uv and Python with it.
It finishes with minion setup, which checks Docker, prepares a desktop and connects your AI apps. Run it again any time.
minion setup
Connect another app any time with minion connect: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf/Devin, Gemini CLI, Codex, LM Studio and more. Read the install guide
Claude Code
Add the MCP server
claude mcp add minion -- uvx minion-desktop mcp
Or install the plugin: the same tools, plus a skill that teaches efficient use.
claude plugin marketplace add apophisss/minion && claude plugin install minion@minion
Add --scope user to use it in every project. For the smallest context, add --compact: one computer tool, about 230 tokens of definitions instead of 2,100. Agents & MCP guide
Cursor
Add to CursorOpens Cursor and asks you to confirm. Needs uv.
Or add this to ~/.cursor/mcp.json, or .cursor/mcp.json in a project:
Or run minion connect after installing. Integrations
ChatGPT and Claude.ai
Web apps can't start programs on your computer. minion share starts Minion's server with a fresh token, opens a tunnel to it and prints an HTTPS MCP URL.
Share Minion from your machine
minion share
Paste the URL into the app's connector settings. Ctrl+C stops sharing.
Install the package. It is pure standard library, so nothing else comes with it.
pip install minion-desktop
Drive a desktop from code
from minion import Desktop
desk = Desktop.create("office")
desk.open("writer")
print(desk.see()) # the screen as text, with @ids
desk.type("Hello!\n")
desk.screenshot("hello.png")
desk.remove()
see turns any window into a compact list of controls with stable @ids, taken from the accessibility tree with OCR as a fallback. Spreadsheets come out as A1: value. The text is exact, and every id is clickable.
What you seescreenshot · ~1,365 tokens
What the agent readssee~920 tokens
Screen 1280x800 · 1 window [1] "Untitled 1 — LibreOffice Writer" — libreoffice-writer (focused) at 0,0 1280x770UI of "Untitled 1 — LibreOffice Writer"(click/fill with @id; (x,y) is the element center):@1menu"File"(22,38)@2menu"Edit"(62,38)…@12document text"Untitled 1 - LibreOffice Document"[editable](603,424)@13heading"Q3 Market Brief"(603,247)@14paragraph"Prepared by an AI agent on a Minion desktop. No human touched the keyboard."(603,282)
After typing a sentencesee(changes=true)~60 tokens
✓ typed 30 chars→ screen changed <1% (region 404,226 236x20)Changes since your last look 1.0s ago (81 elements unchanged; their @ids still work):+@84paragraph"Quarterly numbers look strong."[focused](603,234)~@80label"4 words, 30 characters"(281,730)
Stable ids. The same control keeps its @id across looks, so the agent doesn't have to re-read the screen to act.
Act and report. Every action waits for the UI to settle, then says what changed: windows opened or closed, focus, the changed region.
Text from anything. GTK, Qt, Firefox, Chromium and LibreOffice expose their controls. OCR covers canvases and Wine apps.
When pixels matter, screenshot(marks=true) draws the ids.
@3Efficiency, measured
Built to save tokens.
Screenshots are the most expensive thing an agent can look at, and the model still has to guess coordinates. Minion sends text first, diffs instead of re-reads, and pixels only when they matter.
One job, three apps, 12 tool calls. An agent researches Lisbon on Wikipedia, makes a budget with a chart in a spreadsheet and exports the plan as a PDF. It read 2,372 tokens of text; the same steps with screenshots would cost about 36,855. Recorded live, with the calls made by a script as an agent would make them.
Tokens, measured
Lower is better. Every bar uses the same scale.
What the model receives
Tokens
One look at the screen
Screenshot, 1280×800the baseline
~1,365
see of a LibreOffice windowexact text plus clickable ids
~920
screenshot(detail="low")half size
~341
act(observe="crop")only the changed region
~200
see(changes=true)after typing a sentence: the diff only
~60
Tool definitions, sent with every request
9 tools
~2,100
Compact modeone computer tool with CLI syntax
~230
Entering 5 rows in a spreadsheet
Code mode needs no model round trip per step.
Approach
Tool calls
act, one call per row
5 calls
script, one loop
1 call
Teach once, replay forever
0model calls
Export a finished session with desktop(action="macro"): a Python script that replays it with no model at all.
Measured on a 2-vCPU VM. Reproduce the numbers with python scripts/bench.py. A terminal costs about 50–90 tokens with see. Whole tasks: five real ones cost 4,356 tokens with Minion and 50,505 with screenshots (the benchmark).
@4Featherweight
Small enough to run many.
One small container per desktop: Xvfb, a two-process window manager and taskbar, and a small agent. No VNC and no desktop environment.
Ready in
~1.5s1.2–1.8 s for every profile
Idle RAM per desktop
54–105MBFirefox and LibreOffice add their own when open
CPU when frozen
0%Idle desktops freeze and wake in ~0.2 s
3 desktops in parallel
3.0sStart one per worker with create count=N
Shared layers
Every profile extends another, so ten desktops share one copy of the base image on disk and in the page cache.
Idle freezing
A desktop nobody uses or watches is paused with the cgroup freezer. An optional idle stop frees its RAM and keeps its files.
Nothing runs unless asked
The accessibility library loads on the first look, and the live view streams frames only while someone watches.
Calm pixels
Animations, smooth scrolling and caret blinking are off. That saves CPU and makes “the screen settled” exact.
Measured on a 2-vCPU VM with python scripts/bench.py.
@5Features
A real computer, built for agents.
Every desktop is a real Linux computer, tuned to skip first-run wizards, pop-ups and cookie banners, with everything an agent needs around it.
Any program or website
Browsers, LibreOffice, IDEs, terminals, file dialogs and installers, plus Windows programs through Wine. Anything missing is one command away.
minion-install gimp
apt
.deb
.AppImage
pip:
npm:
Code mode
script runs Python inside the desktop with click, write, key, see and cells. A 50-step GUI loop is one call, and only what the code prints comes back.
for item, price in [("Coffee", 3.5), ("Bagel", 2.25), ("Juice", 4)]:
write(f"{item}\t{price}\n") # Tab moves right, Return goes down
write("Total\t=SUM(B1:B3)\n")
print(cells()["B4"]) # only this comes back: 9.75
Parallel desktops and fork
create count=8 starts a desktop per worker, fork clones one before a risky step, and sessions keep agents apart. Log in once, snapshot, then fork the logged-in desktop for each task.
Human hand-off and live view
Watch any desktop live in your browser and click Take control to use your own mouse and keyboard. An agent can ask you to “Please sign in”, wait until you press Done, then carry on.
Replay and macros
Every action is recorded. Export an HTML timeline or a GIF, or turn the session into a Python script that replays it with no model at all.
minion replay -o run.html
Native computer use
A ready environment for Claude, OpenAI and Gemini computer-use models, with screenshot scaling and coordinate mapping handled for you.
Yes, with Docker Desktop (or OrbStack, Colima or Podman). Desktops are Linux containers and the minion command is pure Python. Images are published for amd64 and arm64, so Apple Silicon runs them natively. The exception is the windows profile, which is amd64 only because Wine runs x86 programs only on x86‑64.
Do I need Docker?
On Linux, no: MINION_BACKEND=local runs desktops as native Xvfb sessions with the apps installed on the host. They start faster but are not isolated from your user account. On macOS and Windows, desktops run in Docker or Podman.
How is this different from a VM or a VNC desktop image?
Minion is built for agents rather than people. It gives them a text view of the screen with clickable ids, actions that wait for the UI to settle and report what changed, desktops tuned to avoid pop-ups, snapshots and forks, idle freezing, and MCP, SDK and HTTP interfaces. There is no VNC server and no desktop environment, so each desktop is ready in about 1.5 s and stays small.
How is it different from browser automation like Playwright or browser-use?
Those drive a browser through the DOM. Minion drives a whole computer: browsers, office apps, terminals, IDEs, file dialogs, downloads, and anything you apt-get install. The two combine well: run your Playwright script inside a dev desktop and watch the same browser in the live view.
Which models and agents work?
Any model with tool use. see and act are text, so text-only models work too, and vision models can also take screenshots. Small and local models do best with the compact computer tool. Models trained for computer use (Claude, OpenAI, Gemini) can drive desktops natively.
How many desktops can I run at once?
As many as memory allows. An idle desktop uses 54–105 MB, and apps add their usual footprint: Firefox and LibreOffice need a few hundred MB each while open. Frozen desktops use no CPU. Cap each one with --memory and --cpus, and start several at once with minion up -c 8.
Is it safe to let an agent use a desktop?
It is safer than letting it use your computer. Each desktop is an isolated, unprivileged container. Treat what's on screen as untrusted input, keep secrets out, hand off to a human for sign-ins, and use --offline for untrusted files. Read the security model.
Give your agent a computer.
Free and open source under the MIT license. Install it in a minute, connect any agent and watch it work.
