Como usar o Droid: guia passo a passo da CLI do Factory Droid

Para usar o Droid, o agente de código da Factory, você instala a CLI com curl -fsSL https://app.factory.ai/cli | sh, roda droid dentro de um projeto, faz login pelo navegador e descreve a tarefa. O Droid pergunta antes de editar um arquivo ou rodar um comando; para scripts e CI existe o droid exec, que é somente leitura até você aumentar a autonomia dele.

Este guia cobre a CLI do Droid em novembro de 2026 (versão 1.12): instalação, login, modelos, a sessão interativa, o droid exec e seus níveis de autonomia, AGENTS.md, servidores MCP, droids próprios e quanto custa.

O que é o Droid

O Droid é o agente de código para terminal da Factory. Ele lê o seu código, propõe mudanças e as aplica depois que você aprova. O mesmo agente também roda nos apps desktop e web da Factory, em integrações com IDEs e por meio de um SDK. A versão 1.0 saiu em 29 de outubro de 2026, e novas versões chegam várias vezes por semana.

O Droid não está preso a um único fornecedor de modelos. Ele oferece modelos da Anthropic, OpenAI, Google e xAI, além de modelos open-weight que a Factory agrupa como “Droid Core”, e você pode adicionar seus próprios endpoints.

Passo 1: instale a CLI

No macOS ou Linux:

curl -fsSL https://app.factory.ai/cli | sh

Outras opções:

brew install --cask droid      # Homebrew
npm install -g droid           # npm

No Windows PowerShell:

irm https://app.factory.ai/cli/windows | iex

No Linux, o login também precisa do xdg-utils (sudo apt-get install xdg-utils). Para atualizar depois, use droid update.

Passo 2: faça login

cd my-project
droid

A primeira execução abre o navegador para você entrar com uma conta da Factory. Para CI e outras máquinas sem navegador, crie uma chave de API nas configurações da Factory e exporte-a:

export FACTORY_API_KEY=fk-...

Passo 3: trabalhe em uma sessão

Descreva a tarefa com palavras simples. O Droid explica o que pretende fazer e depois pergunta antes de cada edição ou comando. Teclas e comandos úteis:

• Shift+Tab alterna entre o modo normal e o modo spec, em que o Droid escreve um plano antes de mudar o código.
• ! roda um comando de shell por conta própria; ? lista os atalhos.
• /model troca o modelo, /settings abre as configurações e /review pede uma revisão das mudanças.
• /compress encurta uma conversa longa; /sessions lista as anteriores.

Para voltar depois, rode droid --resume (ou droid --resume <id>). droid search "checkout bug" encontra uma sessão antiga pelo texto, e --fork <id> copia uma.

Passo 4: escolha um modelo

Troque de modelo com /model em uma sessão, -m na linha de comando ou uma chave model nas configurações. Nos planos pagos, cada modelo conta contra o seu uso com um multiplicador: em novembro de 2026, o Claude Opus 5.5 conta 1,6x, o Claude Sonnet 5.5 0,8x e o Claude Haiku 5.5 0,04x. Use um modelo pequeno para edições de rotina e um grande para design e depuração.

Para usar sua própria chave, adicione um modelo próprio ao ~/.factory/settings.json:

{
  "customModels": [
    {
      "model": "claude-sonnet-5-5",
      "displayName": "Sonnet (my key)",
      "baseUrl": "https://api.anthropic.com",
      "apiKey": "${ANTHROPIC_API_KEY}",
      "provider": "anthropic"
    }
  ]
}

provider pode ser anthropic, openai, generic-chat-completion-api ou bedrock-converse. As chaves ficam na sua máquina.

Passo 5: droid exec e níveis de autonomia

O droid exec roda uma única tarefa sem chat, que é o que você quer em scripts e CI:

droid exec "summarize the changes on this branch"
droid exec --auto low "fix the failing unit test in price.test.ts"
droid exec -f task.md -o json --auto medium

Por padrão ele é somente leitura. Você amplia o que ele pode fazer:

--skip-permissions-unsafe desliga todas as confirmações; deixe isso para contêineres descartáveis. Note que o código de saída 0 significa que o Droid terminou, não que a tarefa deu certo, então confira o resultado na CI. Para sessões interativas, você pode definir um nível padrão com sessionDefaultSettings.autonomyLevel e permissionRules mais finas (allow, ask, block) nas configurações.

Passo 6: AGENTS.md e configurações

O Droid lê o AGENTS.md como as instruções do repositório. Mantenha-o curto: a stack, como rodar os testes, o que não mexer e o que significa “pronto”. Nosso guia sobre CLAUDE.md e AGENTS.md mostra o que colocar nele.

As configurações ficam em ~/.factory/settings.json para você e em .factory/settings.json para o projeto, cada um com um settings.local.json para ajustes locais que você não commita.

Passo 7: servidores MCP e droids próprios

Adicione servidores MCP pela linha de comando:

droid mcp add docs https://example.com/mcp --type http
droid mcp add memory "npx -y @modelcontextprotocol/server-memory"

Eles são salvos em ~/.factory/mcp.json (ou .factory/mcp.json para o projeto) em mcpServers. Em uma sessão, /mcp gerencia esses servidores, incluindo logins OAuth.

Droids próprios são subagentes: um arquivo Markdown com um cabeçalho YAML (name, description, model, tools e mais) em .factory/droids/ ou ~/.factory/droids/. O Droid repassa trabalho a eles pela ferramenta Task, e /droids os gerencia. Um pequeno droid “escritor de testes” ou “revisor” num modelo barato é um bom primeiro droid.

Quanto custa o Droid (em novembro de 2026)

Confira a página de preços da Factory antes de decidir; os planos mudam com frequência.

Erros comuns

• Links antigos da documentação. A documentação mudou de docs.factory.ai para docs.factory.com; as URLs de instalação continuam usando app.factory.ai.
• Rodar o exec com autonomia alta cedo demais. Comece os jobs de CI com --auto low e aumente o nível só nas etapas que precisarem.
• Confiar no código de saída 0. Ele só quer dizer que a execução terminou. Confira os testes ou o diff depois.
• -r significa duas coisas. No droid, -r retoma uma sessão; no droid exec, define o esforço de raciocínio. Escreva --resume por extenso para evitar surpresas.

Rodando o Droid ao lado de outras CLIs no AgentVera

Se o Droid é o seu único agente, os próprios apps da Factory podem bastar. Fica mais difícil quando o Droid roda ao lado do Claude Code, do Codex ou do Gemini CLI no mesmo projeto. O AgentVera é um app desktop que roda essas CLIs lado a lado em terminais reais, com as suas próprias instalações e logins. O suporte ao Droid funciona assim:

• Uma sessão por agente. O AgentVera encontra a sessão que o Droid cria e a reabre com droid --resume <id> nas próximas execuções, então a conversa sobrevive a um reinício do app.
• Modelo, esforço e papel. O modelo e o esforço que você escolhe para o agente são passados por um arquivo de configurações, e o papel do agente com --append-system-prompt.
• Seu login ou suas chaves de API. O Droid mantém o seu login da Factory. Em Configurações → Contas você pode adicionar contas com FACTORY_API_KEY e dar a cada agente a sua.
• Painéis, worktrees e revisão. Rode o Droid na grade do workspace ao lado de outros agentes, cada um no seu próprio git worktree, e confira as mudanças com a revisão de código.

O plano gratuito inclui até 18 agentes, MCP, Git, Docker, SSH, revisão de código e economia de tokens. O Pro custa US$ 9,99 por mês; se você nunca teve um teste, seu primeiro login no app ativa o Pro por 7 dias sem cartão. Para experimentar, baixe o AgentVera.

Conclusão

Para começar com o Droid bastam dois comandos: o script de instalação e droid. O que importa depois é o controle: mantenha as sessões interativas com aprovação, comece o droid exec com --auto low, coloque as regras do projeto no AGENTS.md e escolha um modelo por tarefa de olho no multiplicador de uso.

Fontes: início rápido do Droid, referência da CLI, droid exec, modelos, MCP, changelog.