Video Walkthrough - Factory Documentation

Installation & Setup

Get started by installing the Droid CLI in your terminal of choice.

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

Verify the installation:

which droid

Start the Droid CLI:

cd /path/to/your/project
droid

First-Time Authentication

On your first run, you’ll see an onboarding screen:

Choose to create an account or log in
Confirm the authentication code in your browser
Return to the terminal to start using droid

Interface & Shortcuts

Press Shift + ? to open the help menu, which shows:

How to send messages and create new lines
Available keyboard shortcuts
Basic navigation commands
Autonomy mode options

Terminal-specific key bindings: The default for new lines is \ + Enter, but you can configure this to Shift + Enter or other combinations based on your terminal’s key bindings. Check /terminal-setup in the CLI for configuration options.

Essential Keyboard Shortcuts

Shortcut	Action
`Enter`	Send message
`\` + `Enter` (or `Shift + Enter`)	New line in message
`Shift + ?`	Open help menu
`Shift + Tab`	Cycle through autonomy modes
`/`	Open command menu
`Cmd + Shift + H`	Show root directory
`Cmd + Shift + .`	Show hidden files/folders
`Ctrl + C` or `exit`	Exit droid
`Ctrl + V`	Paste image

The paste image shortcut works across all terminals, though the specific key binding may vary based on your terminal configuration.

Autonomy Modes

Cycle through different autonomy levels by pressing Shift + Tab: Learn more about Specification Mode →

Spec Mode (Research & Plan Only)

Droid will research and create a plan without making any changes. Perfect for understanding what will happen before execution.

No file edits
No command execution
Creates detailed specifications
Allows iteration on plans before proceeding

Low Mode (Read-Only + Safe Commands)

Allows reading files and executing low-risk, read-only commands.

File reading
Directory listing
Safe diagnostic commands
No modifications

Medium Mode (File Edits Allowed)

Enables file modifications and medium-risk commands that are easily reversible.

Create/edit/delete files
Run build commands
Execute tests
Reversible operations

High Mode (All Commands with Safeguards)

Allows all commands but still maintains safety through allow/deny lists.

Full command execution
File removal operations (with confirmation)
Git operations
Configurable via allow/deny lists

Even in High mode, certain dangerous operations (like removing files) will always require your approval unless you explicitly configure them in the allow list.

Configure autonomy settings →

Slash Commands

Press / to access the command menu with options for:

Account & Billing - Manage your Factory account
Model - Switch between AI models and set reasoning levels
Sessions - View and navigate previous sessions
Settings - Configure CLI preferences
Terminal Setup - Configure key bindings
Custom Commands - Access your custom slash commands
Droids - Manage custom sub-agents
MCP - Configure Model Context Protocol integrations

Switching Models

Access the model menu with /model:

View available models
Switch between models for different tasks
Set reasoning level where applicable

Different models excel at different tasks. Use reasoning models for complex planning and faster models for routine edits.

Learn about choosing your model →

Sessions Management

Access with /sessions:

View all previous sessions
Navigate to any past session
Open sessions in the web interface
Continue work from where you left off

Cloud sync must be enabled in settings for sessions to appear in the web interface.

Settings & Configuration

Access settings via /settings to customize your experience: Full settings documentation →

Core Settings

Model & Reasoning

Choose your default model and reasoning level for new sessions

Diff Mode

Configure how code changes are displayed

GitHub Completion

Enable/disable GitHub Copilot-style completions

Cloud Sync

Sync sessions to Factory web platform

Advanced Settings

Droid Co-Author on PRs

When enabled, droid will be added as a co-author on pull requests it helps create. You can disable this if you prefer to be the sole author.

Droid Shield

Protects environment variables and secrets in your code. Prevents accidental commits of sensitive information like API keys, passwords, and tokens.

Keep this enabled to protect against security vulnerabilities.

Learn more about Droid Shield →

Save Spec as Markdown

Automatically saves specifications generated in Spec Mode as markdown files on your machine for reference and documentation.Learn more about Specification Mode →

Allow List & Deny List

Configure which commands require approval even in High autonomy mode. Even on High, file removal operations require confirmation by default.Learn more about auto-run settings →

IDE Integration

Install the droid extension for VS Code, Cursor, and other IDEs directly from the settings menu. Learn more about IDE integration →

Configuration Files

Access your configuration directory by pressing Cmd + Shift + H to show your root directory, then Cmd + Shift + . to reveal hidden files. Navigate to the ~/.factory/ folder.

Directory Structure

~/.factory/
├── config.json          # Model configuration and BYOK
├── settings.json        # CLI settings and allow/deny lists
├── mcp.json            # MCP integrations
├── droids/             # Custom sub-agents
├── commands/           # Custom slash commands
├── logs/               # Session logs
└── bug-reports/        # Crash reports

Learn more: Settings | Custom Slash Commands | Custom Droids | MCP Configuration

config.json - Bring Your Own Key

Configure custom models using your own API keys:

{
  "models": [
    {
      "provider": "openrouter",
      "name": "anthropic/claude-3.5-sonnet",
      "apiKey": "your-api-key-here",
      "displayName": "Claude 3.5 Sonnet (OpenRouter)"
    }
  ]
}

Find Provider Documentation

Visit Bring Your Own Key documentation and select your provider (OpenRouter, Fireworks, etc.)

Copy Configuration Template

Copy the JSON configuration for your chosen provider

Add to config.json

Paste the configuration into ~/.factory/config.json and add your API key

Select Model

Use /model in the CLI to select your newly added model

See all BYOK providers →

settings.json - Allow & Deny Lists

Configure which commands require approval in High autonomy mode:

{
  "autoModeAllow": [],
  "autoModeDeny": [
    "git push",
    "rm -rf",
    "npm publish"
  ]
}

Even in High mode, commands in the autoModeDeny list will always require your explicit approval before execution.

mcp.json - MCP Integrations

Enable or disable MCP tools individually:

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-api-key"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-playwright"],
      "disabled": true
    }
  }
}

Set "disabled": true to temporarily disable an MCP without removing its configuration. Learn more about MCP configuration →

Custom Droids (Sub-Agents)

Custom droids are specialized AI agents that handle specific tasks. Access the droids menu with /droids:

Managing Droids

Import (i) - Import pre-built droids from other agents
Create (c) - Create a new custom droid
Edit - Modify existing droid configurations
Enable/Disable - Toggle droids on or off

Creating a Custom Droid

Learn more about custom droids →

Choose Scope

Decide if the droid should be project-level (specific repository) or personal (available across all projects)

Generation Method

Choose to create manually or generate with droid’s help:

I want a code review droid that checks for security issues and coding standards

Droid will generate an appropriate description and configuration

Configure Model

Inherit: Use the same model as the parent session
Specific Model: Choose a dedicated model for this droid (e.g., use a reasoning model for complex analysis)

Enable Tools

Select which tools and capabilities the droid should have access to

Save & Edit

Confirm the configuration and optionally edit the details

Example Use Cases

Code Review Droid - Automated code reviews for pull requests
Documentation Droid - Generates and maintains documentation
Test Generation Droid - Creates comprehensive test suites
Security Audit Droid - Scans for vulnerabilities and security issues

MCP Integrations

Model Context Protocol (MCP) allows droid to integrate with external tools and data sources.

Adding MCPs via CLI

Use the /mcp add command:

/mcp add

Then provide the MCP details:

Name: Identifier for the MCP
Command: Executable command (e.g., npx, python)
Args: Command arguments
Environment Variables: API keys and configuration

Listing Configured MCPs

/mcp list

This shows all configured MCPs and their enabled/disabled status.

After adding or modifying MCPs, you may need to restart the CLI for changes to take effect.

Adding MCPs via Configuration File

You can also directly edit ~/.factory/mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Popular MCP Integrations

Brave Search - Web search capabilities
Playwright - Browser automation
GitHub - Repository and issue management
Filesystem - Extended file system access
Postgres - Database queries
Slack - Team communication

Browse all MCP servers →

Example Workflow: Spec Mode to Implementation

Here’s a complete workflow demonstrating droid’s capabilities:

Start in Spec Mode

Press Shift + Tab until you’re in Spec mode

Create an authentication system with GitHub and Google OAuth

Review the Plan

Droid generates a detailed specification:

Architecture decisions
Files to create/modify
Dependencies needed
Implementation steps

Iterate on the Spec

Refine the plan before implementation:

Change the plan to only include Github auth and not Google auth

Droid updates the specification accordingly

Approve and Proceed

Once satisfied with the plan, proceed with High mode to implement

Review Changes

Droid shows exactly what will change and waits for your approval

Spec mode is especially powerful for complex features. It allows you to validate the approach before any code is written.

Read the full Specification Mode guide → Learn about implementing large features →

Summary

You’ve learned how to:

Install and authenticate with the Droid CLI
Navigate the interface and use keyboard shortcuts
Understand and switch between autonomy modes
Configure settings and preferences
Add custom models with BYOK
Create and manage custom droids (sub-agents)
Integrate external tools via MCP
Use spec mode for planning before implementation

Next Steps

How to Talk to a Droid

Learn best practices for communicating with droid

Common Use Cases

Explore real-world workflows and scenarios

Become a Power User

Advanced techniques and productivity tips

AGENTS.md Guide

Document project-specific conventions

Getting Started

User Guides

Configuration

Droid Exec (Headless)

Account

​Installation & Setup

​First-Time Authentication

​Interface & Shortcuts

​Help Menu

​Essential Keyboard Shortcuts

​Autonomy Modes

​Slash Commands

​Switching Models

​Sessions Management

​Settings & Configuration

​Core Settings

Model & Reasoning

Diff Mode

GitHub Completion

Cloud Sync

​Advanced Settings

​IDE Integration

​Configuration Files

​Directory Structure

​config.json - Bring Your Own Key

​settings.json - Allow & Deny Lists

​mcp.json - MCP Integrations

​Custom Droids (Sub-Agents)

​Managing Droids

​Creating a Custom Droid

​Example Use Cases

​MCP Integrations

​Adding MCPs via CLI

​Listing Configured MCPs

​Adding MCPs via Configuration File

​Popular MCP Integrations

​Example Workflow: Spec Mode to Implementation

​Summary

​Next Steps

How to Talk to a Droid

Common Use Cases

Become a Power User

AGENTS.md Guide

Installation & Setup

First-Time Authentication

Interface & Shortcuts

Help Menu

Essential Keyboard Shortcuts

Autonomy Modes

Slash Commands

Switching Models

Sessions Management

Settings & Configuration

Core Settings

Advanced Settings

IDE Integration

Configuration Files

Directory Structure

config.json - Bring Your Own Key

settings.json - Allow & Deny Lists

mcp.json - MCP Integrations

Custom Droids (Sub-Agents)

Managing Droids

Creating a Custom Droid

Example Use Cases

MCP Integrations

Adding MCPs via CLI

Listing Configured MCPs

Adding MCPs via Configuration File

Popular MCP Integrations

Example Workflow: Spec Mode to Implementation

Summary

Next Steps