Minion
Desktops Linux leves para agentes de IA: leia a tela como texto, clique, digite, execute qualquer aplicativo.
Documentação
Dê a cada agente de IA seu próprio computador.
Desktops Linux leves (escritório, desenvolvimento, pesquisa, navegador, dados, aplicativos Windows) que qualquer agente pode usar:
Claude, ChatGPT, Gemini, Cursor, VS Code, LangChain, seu próprio código ou um modelo rodando no seu laptop.
Agentes leem a tela como texto, agem em lotes ou em código e usam qualquer programa ou site.
Inglês · 简体中文 · 繁體中文 · 한국어 · 日本語 · עברית
Comece agora
Tudo o que você precisa é Docker (ou OrbStack ou Podman). Depois escolha uma opção:
1. Um clique no seu aplicativo de IA:
Claude Code: claude plugin marketplace add apophisss/minion && claude plugin install minion@minion. Qualquer outro cliente MCP:
uvx minion-desktop mcp, ou npx -y minion-desktop mcp. Os botões, uvx e npx iniciam o Minion com
uv (npx pode usar pipx em vez disso); a extensão do Claude Desktop não precisa de mais nada.
2. Uma linha que instala o Minion e conecta todos os aplicativos de IA do seu computador (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
Termina com minion setup, que verifica o Docker, prepara um desktop e executa minion connect. Execute qualquer um deles novamente
a qualquer momento.
3. Do ChatGPT, Claude.ai ou Le Chat no navegador: execute minion share e cole a URL que ele imprimir nas
configurações do conector do aplicativo (como).
Depois é só pedir: "Crie um desktop de escritório, escreva um resumo de uma página sobre nossos números do 3º trimestre no Writer e salve-o como brief.docx." Todas as formas de instalação estão em docs/install.md.
▶ Assista à demonstração de um minuto: um agente pesquisa uma viagem na Wikipedia, faz um orçamento com um gráfico e escreve o plano como PDF. 12 chamadas de ferramenta e 2.372 tokens de texto; os mesmos passos com capturas de tela custariam cerca de 36.855. Gravado ao vivo com python scripts/demo_video.py, que faz as chamadas que um agente faria.
Por que o Minion
- 🖥️ Qualquer programa, qualquer site. Cada desktop é um computador Linux real: navegadores, LibreOffice, IDEs, terminais,
diálogos de arquivo e instaladores, além de programas Windows por meio do perfil
windows(Wine). Abra qualquer aplicativo pelo nome e ele será instalado na primeira vez (open gimp,open vscode,open dbeaver, qualquer pacote Debian), aplicativos web abrem no navegador (open gmail), e a primeira abertura responde com algumas dicas para o aplicativo. 130+ aplicativos pelo nome. - 🧭 Atalhos por todos os aplicativos.
see --menuslista todos os comandos de menu com seus atalhos de teclado, emenu "File > Export as PDF"executa um sem abrir um menu.path ~/out.pdfpreenche qualquer diálogo Abrir/Salvar. Menus de contexto aparecem emsee,button:Saveescolhe um tipo de controle, e um botão abaixo da dobra é rolado para a visualização. Qualquer documento é lido como texto (read report.docx, xlsx com fórmulas, pptx, pdf) e converte em uma chamada (convert report.docx pdf). - 🧠 Agentes leem a tela como texto.
seetransforma qualquer janela em uma lista de controles com@idsestável, obtida da árvore de acessibilidade com OCR como fallback:@12 button "Save" (210,62). Páginas web, editores (com números de linha), terminais, menus suspensos com suas opções e planilhas (linha por linha:row 2: A2 North · B2 120) saem todos como texto exato. Quando pixels importam, capturas de tela podem desenhar o@idspara você. - 🎯 Ações honestas. Cada ação espera a tela estabilizar (para páginas web carregarem e enquanto um aplicativo mostra "Carregando…") e relata o que aconteceu: janelas, alertas ou prompts de uma página, arquivos salvos ou baixados, um pop-up que capturou o clique. Alvos de texto devem realmente estar na tela: uma falha retorna com os candidatos mais próximos em vez de clicar em outra coisa. Testado em 93 tarefas cotidianas feitas por agentes de IA.
- 🪙 Feito para economizar tokens. Você recebe diffs em vez de releituras (
see(changes=true): cerca de 80 tokens em vez de cerca de 900). Modo código executa um loop de GUI de 50 passos em uma chamada, recortes e capturas de tela em meia resolução reduzem o custo de imagem, um modo compacto reduz as definições de ferramenta de cerca de 3.300 tokens para 450, e a Habilidade de Agente custa cerca de 100 tokens até ser usada. - 🪶 Leve. Um contêiner pequeno por desktop (Xvfb, um gerenciador de janelas de 2 processos e barra de tarefas, um agente pequeno), sem VNC e sem ambiente de desktop. Os desktops ficam prontos em cerca de 1,5 s e usam cerca de 60 MB em repouso. Desktops ociosos são congelados automaticamente (0% de CPU) e acordam em cerca de 0,2 s.
- 🔌 Funciona com todos os agentes. Um conjunto de ferramentas em todos os lugares: MCP (local ou remoto), chamada de função para OpenAI, Anthropic, Gemini e modelos locais, HTTP com OpenAPI, uma CLI e uma Habilidade de Agente para agentes de shell, SDKs Python e TypeScript, e adaptadores nativos para uso de computador Claude, OpenAI e Gemini.
- ⚡ Paralelo por design.
create count=8inicia um desktop por worker,forkclona um antes de um passo arriscado, e sessões mantêm agentes separados. - 🙋 Humanos no circuito. Uma visualização ao vivo no navegador oferece assumir controle com um clique, move arquivos nos dois sentidos (solte-os na tela) e compartilha a área de transferência. Agentes podem transferir ("por favor, faça login") e aguardar Concluído, e um login salvo uma vez manualmente inicia novos desktops já conectados.
- 🎞️ Ensine uma vez, reproduza para sempre. Cada ação é registrada. Exporte uma linha do tempo HTML ou GIF, ou transforme a sessão em um script Python que a reproduz sem nenhum modelo.
- 📦 Zero dependências. O lado do host é biblioteca padrão pura de Python. Os desktops rodam em Docker ou Podman (macOS, Windows, Linux) ou nativamente no Linux.
Um tour rápido pelo shell
Qualquer agente com um terminal (Claude Code, Codex CLI, Aider, Open Interpreter, Goose) pode usar a CLI diretamente, e
minion skill --install ensina como:
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, diálogos de arquivo e aplicativos pelo nome: menu "File > Export As > Export Directly as PDF", path ~/Documents/report.pdf, depois open gimp, que instalou o GIMP em 16 s. Gravado pelo gravador de voo.
Funciona com todos os agentes
| Seu agente | Conecte com |
|---|---|
| Claude Desktop/Code, Cursor, VS Code, Codex, Gemini CLI, opencode, OpenClaw, Windsurf/Devin, LM Studio, Kiro, Goose | um clique, minion connect, ou uvx minion-desktop mcp (instalação) |
| Frameworks de agentes: OpenAI Agents SDK, LangChain/LangGraph, LlamaIndex, CrewAI, smolagents, Pydantic AI, Google ADK, AutoGen | o mesmo servidor MCP (receitas verificadas) |
| ChatGPT, Claude.ai, Le Chat (aplicativos web) | minion share: MCP remoto via HTTPS (docs) |
| Qualquer modelo com chamada de função (OpenAI, Anthropic, Gemini, Mistral, modelos locais via Ollama/vLLM) | Toolkit().definitions("openai" | "anthropic" | "gemini") + Toolkit().run_calls() (docs) |
| Qualquer coisa que fale HTTP (n8n, Dify, GPT Actions, qualquer linguagem) | minion serve → /api/tools/*, /mcp e /openapi.json (docs) |
| Agentes de shell | a CLI minion (docs) e sua Habilidade de Agente (minion skill --install) |
| Código Python / TypeScript | from minion import Desktop (docs) · clients/typescript |
| Modelos nativos de uso de computador | Conjunto de ferramentas Claude (docs) · uso de computador OpenAI e Gemini (docs) |
Um agente completo com qualquer modelo compatível com OpenAI ("anthropic", "gemini" e "openai-responses" funcionam
da mesma forma):
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 local model
messages = [{"role": "user", "content": "On a research desktop, find the population of Iceland on Wikipedia."}]
while True:
msg = (
client.chat.completions.create(model="YOUR-MODEL", messages=messages, tools=tk.definitions("openai"))
.choices[0]
.message
)
messages.append(msg)
if not msg.tool_calls:
break
messages += tk.run_calls(msg.tool_calls) # runs every call, returns the messages to send back
print(msg.content)
Python e modo código
from minion import Desktop
with Desktop.create("office", keep=False) as desk: # removed when the block ends
desk.open("calc")
result = desk.script("""
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"]) # visible cells as {"A1": ...}
""")
print(result.stdout) # 9.75
desk.key("ctrl+s")
desk.fill("Name", "q3.xlsx")
desk.key("Return")
desk.wait_for("q3.xlsx")
desk.download("~/Documents/q3.xlsx", ".")
script executa Python dentro do desktop com click · write · key · scroll · fill · see · elements · cells · wait_for · launch · run. Loops cost one call, and only what the code prints comes back. The Desktop API também
tem screenshot · see · act · open · run · upload · download · clipboard · windows · freeze · fork · snapshot · restore · recording · create_many. Veja docs/python.md.
Uso de computador nativo (Claude, OpenAI, Gemini)
O Minion é um ambiente pronto para o modelo de uso de computador de cada fornecedor, com dimensionamento de capturas de tela e mapeamento de coordenadas tratados para você:
import anthropic
from minion import Desktop
from minion.integrations.anthropic import MinionComputer, allow_all
desk = Desktop.create("office")
with MinionComputer(desk, confirm=allow_all) as computer: # the desktop is the sandbox
runner = anthropic.Anthropic().beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=16000,
tools=[computer],
messages=[{"role": "user", "content": "Make a 3-slide deck about otters in Impress."}],
)
for message in runner:
print(message)
O computer_toolset_20260801 do Claude (todas as 17 ações) e o computer_20251124 anterior são cobertos em
docs/computer-use.md. O uso de computador OpenAI e Gemini é coberto em
docs/computer-use-openai-gemini.md.
Perfis
| Perfil | O que contém | Download | RAM em repouso |
|---|---|---|---|
🌐 browser | Firefox com uBlock Origin (anúncios, rastreadores, banners de cookies, pop-ups de newsletter), downloads diretos para ~/Downloads, um terminal que see pode ler | 363 MB | ~55–100 MB |
📄 office | LibreOffice Writer, Calc, Impress + editor de texto + gerenciador de arquivos + Firefox + ferramentas de PDF. Salva formatos Microsoft por padrão e digita exatamente o que o agente envia (sem AutoCorreção) | 526 MB | ~85 MB |
🛠️ dev | git, Python, Node.js, ferramentas de build, IDE Geany, um terminal real (legível por see), Firefox + Chromium | 714 MB | ~55 MB |
🔎 research | Firefox + pdftotext, pandoc, um editor de notas, Python com requests e BeautifulSoup | 422 MB | ~55 MB |
📊 data | office + pandas, NumPy, SciPy, matplotlib, seaborn, openpyxl, SQLite | 674 MB | ~105 MB |
🪟 windows | Wine 10 para programas Windows .exe/.msi de 64 e 32 bits, além de Firefox para baixá-los. Hosts x86-64 (docs) | 717 MB | ~56 MB (~270 MB com um programa aberto) |
🧩 base | Servidor X, gerenciador de janelas, terminal e o agente. A base para construir | 199 MB | ~65 MB |
Seu próprio perfil é um arquivo TOML de 5 linhas em ~/.config/minion/profiles/. Ele é construído automaticamente na primeira vez que você o usa:
# ~/.config/minion/profiles/designer.toml
extends = "browser"
description = "Firefox plus GIMP and Inkscape."
packages = ["gimp", "inkscape"]
apps = [{ name = "GIMP", command = "gimp" }, { name = "Inkscape", command = "inkscape" }]
Ou adicione software em tempo de execução: minion run "minion-install gimp https://example.com/tool.AppImage pip:yt-dlp".
Veja docs/profiles.md.
Como os agentes veem a tela
see é o principal sentido do agente. Aqui está em uma janela do LibreOffice:
Screen 1280x800 · 1 window
[1] "Untitled 1 — LibreOffice Writer" — libreoffice-writer (focused) at 0,0 1280x770
UI of "Untitled 1 — LibreOffice Writer" (click/fill with @id; (x,y) is the element center):
@1 menu "File" (22,38)
@2 menu "Edit" (62,38)
…
@12 document text "Untitled 1 - LibreOffice Document" [editable] (603,424)
@13 heading "Q3 Market Brief" (603,247)
@14 paragraph "Prepared by an AI agent on a Minion desktop. No human touched the keyboard." (603,282)
Após uma ação, observe="changes" (ou see(changes=true)) retorna apenas a diferença:
✓ 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):
+ @84 paragraph "Quarterly numbers look strong." [focused] (603,234)
~ @80 label "4 words, 30 characters" (281,730)
Texto que a acessibilidade não expõe (uma apresentação de slides, um aplicativo de canvas, uma imagem de texto, uma tela remota, um programa
sem árvore de acessibilidade) é lido com OCR, apenas onde está faltando e no idioma da própria tela: os scripts
nos títulos e rótulos das janelas o escolhem. Hebraico, árabe, russo, chinês, japonês, coreano e hindi são integrados,
e outros idiomas são instalados no primeiro uso. Texto grande e texto claro sobre cor têm passagens próprias, e uma imagem
que não mudou nunca é lida duas vezes. Em 24 slides hebraicos fotografados, see lê 94% das palavras. Aqui está em
uma página web que mostra um slide como imagem:
@2 heading "Board meeting, October 15" (640,131)
@3 paragraph "The slides from the quarterly review:" (640,186)
Text in the picture at 0,117 800x480 (OCR: accessibility doesn't have it):
@4 "Q3 review" (146,254)
@5 "Revenue grew 12% to $4.1M" (218,348)
@6 "1,240 new customers, churn down to 2.1%" (291,404)
@7 "Next: launch in Japan and Brazil" (239,460)
@8 "| Goal: $5M in Q4" (163,555)
Quando pixels importam, screenshot --marks rotula cada controle com seu @id:
Eficiência, medida
Cinco tarefas reais (um relatório em PDF, uma planilha, uma consulta na Wikipedia, um formulário web, leitura de um documento) custam a um agente
8.668 tokens com Minion e 50.505 com capturas de tela: 5,8× menos. A tabela completa e o método estão em
docs/benchmarks.md; reproduza com python scripts/bench_tasks.py.
| Tokens | ||
|---|---|---|
| Captura de tela 1280×800 | ~1.365 | a linha de base |
screenshot(detail="low") | ~341 | metade do tamanho |
act(observe="crop"), apenas a região alterada | ~200 | |
see de uma janela do LibreOffice | ~920 | texto exato mais ids clicáveis |
see(changes=true) após digitar uma frase | ~80 | ids estáveis, apenas diff |
see de um terminal | ~50–90 | |
Definições de ferramentas: 9 ferramentas / computer compacto | ~3.300 / ~450 | enviadas a cada requisição |
5 linhas de entrada em planilha: act ×5 / script ×1 | 5 chamadas / 1 chamada | sem ida e volta do modelo por etapa |
| Recursos | |
|---|---|
| Pronto em | 1,2–1,8 s (todos os perfis) |
| RAM ociosa | 54–105 MB por desktop (Firefox/LibreOffice adicionam a própria quando abertos) |
| Congelado | 0,00% de CPU, descongelado em ~0,2 s na próxima chamada |
| 3 desktops em paralelo | 3,0 s |
Estes foram medidos em uma VM de 2 vCPUs. Reproduza-os com python scripts/bench.py.
Observe, assuma, entregue
minion view (ou a ferramenta view) abre uma visualização ao vivo de qualquer desktop no seu navegador. Clique em Assumir controle para usar
seu próprio mouse e teclado. Um agente pode chamar view(message="Please sign in to your Google account"): você recebe um
aviso, faz login, pressiona Concluído, e o agente continua. Arquivos baixa do desktop e envia para ele
(ou arraste arquivos para a tela), Copiar traz a área de transferência do desktop para a sua, e Teclas envia as que
seu navegador mantém (Ctrl+W, Alt+Tab).
Faça login uma vez e inicie desktops já autenticados: minion login github https://github.com/login abre um desktop lá
na visualização ao vivo, você faz login e pressiona Concluído, e a partir daí minion up --login github (ou
desktop(action="create", login="github")) inicia desktops já autenticados. O login permanece no
Docker do seu computador (detalhes). minion serve adiciona um painel com miniaturas ao vivo:
Como funciona
flowchart LR
subgraph host["Your machine"]
A["Any agent<br/>(MCP, function calling, HTTP, CLI, SDK)"] --> T["minion tools<br/>(pure-stdlib Python)"]
T --> V["Live view and dashboard<br/>(minion serve)"]
end
subgraph desk["Desktop (one container each)"]
S["minion agent<br/>RPC over docker exec"] --> X["Xvfb + JWM"]
S --> AT["AT-SPI<br/>accessibility tree"]
S --> O["Tesseract OCR"]
S --> C["code mode<br/>(Python inside)"]
X --> Apps["Firefox · LibreOffice · Terminal · Wine · …"]
end
T -->|"docker exec (no open ports)"| S
Leia docs/design.md para o raciocínio por trás de cada escolha, e docs/architecture.md para os detalhes internos.
Segurança
Cada desktop é um contêiner sem privilégios, sem montagens do host por padrão. Use --offline para cortar o acesso à rede,
ou limite recursos com --memory e --cpus. O servidor HTTP vincula-se a 127.0.0.1, exige um token aleatório e recusa
solicitações de cross-site e DNS-rebinding. Transferências de arquivos de e para seu computador permanecem em uma única pasta, e minion share URLs carry a fresh token and stop working when you stop sharing. The desktop user has passwordless sudo dentro do contêiner, para que agentes
possam instalar software. Trate tudo em uma tela como entrada não confiável (injeção de prompt) e mantenha credenciais
fora dos desktops, a menos que um humano faça a entrega. Leia SECURITY.md.
Documentação
Site · Instalação · Conecte seus aplicativos · MCP remoto · Design · Agentes e MCP · Integrações · CLI · Python · API HTTP · Uso de computador no Claude · Uso de computador no OpenAI e Gemini · Perfis · Aplicativos por nome · Aplicativos Windows · Arquitetura · FAQ
Contribuindo
Perguntas e ideias são bem-vindas em Discussões, e bugs em issues. Para ajudar a construir o Minion, escolha uma primeira issue boa (traduções, aplicativos, aplicativos de agente, tarefas de benchmark), leia CONTRIBUTING.md e veja para onde está indo no roadmap.
Licença
MIT. Os desktops contêm software de código aberto sob suas próprias licenças (Debian, Firefox, LibreOffice, Wine, …).