Skip to content
AgentAtlas

Configure Factory Droid CLI: AGENTS.md, settings.json, autonomy, custom droids and MCP

How do I install and configure the Factory Droid CLI?

Install Droid with the official install script, Homebrew or npm, then run droid inside your project. Put project instructions in AGENTS.md, personal preferences in ~/.factory/settings.json, custom droids in .factory/droids, and MCP servers in mcp.json files. Use droid exec with --auto low, medium or high to control what headless runs may do without approval.

Compare: allow all commands in every AI coding agent →

Compare: settings file locations in every AI coding agent →

Install and start Droid

Factory lists four install methods. On Linux, make sure xdg-utils is installed. After installing, open your project folder and run droid, then sign in through your browser if prompted.

Install (pick one)

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

# Homebrew
brew install --cask droid

# Windows (PowerShell)
irm https://app.factory.ai/cli/windows | iex

# npm
npm install -g droid

# Start an interactive session
cd /path/to/your/project
droid

AGENTS.md and settings.json

Add an AGENTS.md file at the repository root with exact install, test, lint and build commands, conventions and safety rules, and commit it. Droid searches from the current directory up to the git root, checking each level and its .factory, .agents and .agent folders, plus personal folders such as ~/.factory. It also reads compatible names such as CLAUDE.md. Nested files refine the root file, and project files override personal defaults.

Personal settings live in ~/.factory/settings.json on macOS and Linux, or %USERPROFILE%\.factory\settings.json on Windows. The file is created with defaults the first time you run droid, and you can edit it interactively with the /settings command. A settings.local.json file next to settings.json, at user or project level, merges on top for machine specific overrides.

~/.factory/settings.json

{
  "model": "YOUR_MODEL_ID",
  "reasoningEffort": "medium",
  "sessionDefaultSettings": {
    "interactionMode": "auto",
    "autonomyLevel": "low"
  },
  "cloudSessionSync": true,
  "diffMode": "github",
  "includeCoAuthoredByDroid": true,
  "enableDroidShield": true
}

Autonomy levels and droid exec

Autonomy Level sets the highest risk work Droid can run without asking. The levels are Off, Low, Medium and High. In the interactive CLI, press Ctrl+L to cycle levels, or set sessionDefaultSettings.autonomyLevel as the default. Permission rules, safety checks and organization limits still apply at every level.

  • No flag: droid exec is read only, suited to analysis, planning and reviews.
  • --auto low: low risk file creation and edits, such as docs, formatting and comments.
  • --auto medium: adds local development work such as package installs, builds, tests, git commit, git checkout and git pull, but not git push.
  • --auto high: adds remote writes, deployments and migrations, subject to remaining hard safety checks.
  • --skip-permissions-unsafe skips all prompts, cannot be combined with --auto, and is meant only for disposable environments.

droid exec examples

droid exec "summarize the architecture of this repo"
droid exec --auto low "add JSDoc comments to all exported functions"
droid exec --auto medium "install deps, run tests, and fix failing checks"
droid exec --auto high "fix the bug, run tests, commit, and push the branch"

If a requested action is above the current level, droid exec stops with an error and a non zero exit code instead of making partial changes.

Custom droids and MCP servers

A custom droid is a Markdown file with YAML frontmatter that runs as a subagent in a fresh context window. Project droids go in .factory/droids in your repo and personal droids go in ~/.factory/droids. A project droid wins when names clash. You can also create one with the /droids menu.

.factory/droids/code-reviewer.md

---
name: code-reviewer
description: Focused reviewer that checks diffs for correctness risks
model: inherit
tools: read-only
---

You are the team's senior reviewer. Examine the diff the parent agent shares and
flag correctness, security, and migration risks.

Add MCP servers with droid mcp add, which always writes to your user config at ~/.factory/mcp.json, or open the /mcp manager inside Droid. A project level .factory/mcp.json can be committed for the team, but never put secrets in it. Droid reloads automatically when an mcp.json file changes.

Add MCP servers

# Remote HTTP server
droid mcp add linear https://mcp.linear.app/mcp --type http

# Local stdio server with an environment variable
droid mcp add airtable "npx -y airtable-mcp-server" --env AIRTABLE_API_KEY=YOUR_VALUE

# List and remove
droid mcp list
droid mcp remove YOUR_SERVER_NAME

.factory/mcp.json

{
  "mcpServers": {
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp",
      "disabled": false
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "disabled": false
    }
  }
}

Sources

More Factory Droid guides

Reviewed Oct 23, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →