# Welcome to Factory Install Droid, delegate your first task, and scale from a single session to an automated SDLC. ## Choose a path Start with a coding task, automate a workflow, or research the platform. Pick the outcome that aligns with your goals. Delegate a task, review the diff, and merge from the App or your terminal. Put code review, QA, and documentation on autopilot across your repos. Deploy, secure, govern, and observe Droid across your organization. ## Start with a surface Droid runs the same everywhere. Pick a surface, install it, and start your first session. Download the desktop app, sign in, and connect it to your codebase. - [Mac (Apple Silicon)](https://app.factory.ai/api/desktop?platform=darwin&architecture=arm64): Download for M-series Macs - [Mac (Intel)](https://app.factory.ai/api/desktop?platform=darwin&architecture=x64): Download for Intel Macs - [Windows (x64)](https://app.factory.ai/api/desktop?platform=win32&architecture=x64): Download for Intel and AMD PCs - [Windows (ARM64)](https://app.factory.ai/api/desktop?platform=win32&architecture=arm64): Download for Snapdragon and ARM PCs - [Linux (x64 and ARM64)](https://docs.factory.com/factory-app/linux): Install with a script or a .deb package Follow the [Factory App quickstart](/factory-app/quickstart) to install the app, connect a repository, and run your first reviewable session. Run one command, then start `droid` in any repository. **macOS/Linux:** `curl -fsSL https://app.factory.ai/cli | sh` **Homebrew:** `brew install --cask droid` **Windows:** `irm https://app.factory.ai/cli/windows | iex` **npm:** `npm install -g droid` Follow the [Droid CLI quickstart](/droid-cli/quickstart) to install the CLI, authenticate, and delegate your first task from the terminal. Nothing to install: [cloud session sync](/droid-cli/settings#cloud-session-sync) and [Droid Computers](/droid-computers/overview) make your sessions available from any browser at app.factory.ai. The [Factory App quickstart](/factory-app/quickstart) covers the same session flow across desktop, web, and mobile. ## Explore the docs - [Product Surfaces](/factory-app/overview): run Droid in the Factory App, the CLI, headless exec, and cloud computers. - [Automations](/automations/overview): automate triage, code review, QA, docs, and incident response. - [Workstreams](/workstreams/overview): hand a large project to an orchestrator that runs a team of agents in parallel. - [Platform Capabilities](/missions/overview): Missions, model independence, autonomy controls, and harness customization. - [Factory Enterprise](/enterprise): deployment patterns, security, identity, and telemetry for a managed fleet. - [API Reference](/api-reference): drive sessions, computers, wikis, and analytics programmatically. - [Changelog](/changelog/release-notes): release notes and feature maturity. # Individual Plans Compare Factory Free, Pro, Plus, and Max plans for individual developers. ## Individual plan tiers {/* sweep-allow: term-bullets */} - **Free:** bring your own inference. Sign in with ChatGPT, GitHub Copilot, or OpenRouter, or connect your own API keys/custom endpoint. - **Pro, Plus, and Max:** Factory Managed Inference, with usage governed by rolling Rate Limits. See current plans and prices on the pricing page. ## How individual usage works {/* sweep-allow: term-bullets */} - **Rate Limits:** three rolling windows, 5-hour, 7-day, and 30-day. Each runs independently. - **Standard Usage:** consumed first on Individual plans. - **Droid Core:** free open-weight model pool with separate Rate Limits after Standard Usage runs out. - **Extra Usage:** prepaid credits, $10 minimum, no expiration. The toggle stays on until you turn it off or run out. - **Monitor usage:** open **Settings > Usage** or run `/limits` in Droid. ## Missions - **Missions** use the same rolling Rate Limits as regular sessions and require Extra Usage to be enabled. If a Mission hits a Rate Limit, it pauses. Run Missions on Droid Core when possible. Core models often deliver comparable results and stretch your plan further. ## FAQ Droid sessions consume Factory Standard Credits based on model usage, along with compute usage for cloud environments. Yes. Hitting the 5-hour cap does not eat into weekly or monthly any faster, and vice versa. You need headroom in all three to send a request. All three are rolling: 5-hour, 7-day, and 30-day. Each starts ticking when you first use Droid and resets after the window elapses. No. Standard Usage does not roll over month to month. Extra Usage that you purchase does roll over. A set of models Factory has designated as Core, typically smaller, cheaper models that handle most coding tasks well. You can see the current list in **Settings > Models**. The list changes as new models ship. No. It uses the same Standard Usage billing, restricted to the Core model pool so you can keep working after premium-model Rate Limits are exhausted. Extra Usage is prepaid, USD-denominated credit. Buy a dollar amount and it is drawn down as your sessions use models. The current request finishes, then subsequent requests receive a Rate Limit error in the CLI or Factory App. Run `/limits` to toggle Droid Core or Extra Usage and retry immediately. Compare Teams, Business, and Enterprise plans. Browse the model catalog and multipliers that drive usage costs. # Organization Plans Compare Factory Teams, Business, and Enterprise plans for shared usage, governance, security, and support. Business and Enterprise plans are for teams and companies that need shared usage, administrative controls, onboarding, security terms, and support. Business and Enterprise use custom limits and contract terms rather than the Individual rolling Rate Limit model. Teams includes everything in Pro for your whole team, with up to 10 seats and centralized billing. Its price is listed with the other self-serve plans on [Individual Plans](/pricing/individuals). ### Business For growing teams that need tailored plans. Tailored for your team - Custom usage limits - Dedicated onboarding and support - Single Sign-On (SSO) integration - SAML/SCIM provisioning - Zero Data Retention (ZDR) - Audit logging and activity trails - Basic admin controls (model selection, autonomy level, model access controls, org-level deny lists, network policy) [Contact sales](https://factory.com/contact) ### Enterprise Every feature prior, and: Enterprise scale - Unlimited team members - Dedicated compute with partitioned inference pool Enterprise features - Agent-readiness Improvement Program - Enterprise-specific automation cookbook - On-premise deployment options - Sub-organizations - Full admin controls - Data residency Premium support - Dedicated Account Manager and Customer Engineer - Priority support with SLAs - Custom onboarding program [Contact sales](https://factory.com/contact) ## What organization plans add | Capability | Teams | Business | Enterprise | | :--------- | :---- | :------- | :--------- | | Seats | Up to 10 | Custom | Unlimited | | Shared usage limits | — | Custom limits for team usage | Custom limits for enterprise usage | | Identity and provisioning | — | SSO, SAML/SCIM provisioning | SSO, SAML/SCIM provisioning | | Governance | — | Admin controls for models, autonomy, access, deny lists, and network policy | Full admin controls, sub-organizations, plus custom policy and deployment terms | | Data controls | — | ZDR, audit logging and activity trails | ZDR, audit logging, data residency | | Deployment | — | Factory-hosted and managed compute options | Dedicated compute, partitioned inference, and on-premise options | | Support | — | Dedicated onboarding and support | Dedicated Account Manager, Customer Engineer, and priority SLAs | ## Usage and billing On Teams plans, each seat includes Pro Rate Limits. Billing is centralized and paid month-to-month. On Business and Enterprise plans, usage is shared across the workspace and governed by contract terms. It is not governed by the Individual plan Rate Limit model. ## Enterprise Controls Business and Enterprise add controls for platform teams: - [Identity and Access](/enterprise/identity-and-access) for roles, SSO, and provisioning. - [Hierarchical Settings and Org Control](/enterprise/hierarchical-settings-and-org-control) for inherited settings and org-managed policy. - [Network and Deployment](/enterprise/network-and-deployment) for deployment choices and network boundaries. - [Telemetry & Analytics](/enterprise/telemetry) for usage, adoption, and cost reporting. ## FAQ On the Teams plan, each seat has its own individual Pro Rate Limits. Business and Enterprise plans have custom workspace-level terms. Limits, seats, support, and deployment options are scoped to the organization contract. Choose Enterprise when you need unlimited seats, dedicated compute, partitioned inference, on-premise deployment, sub-organizations, data residency, or priority support commitments. Discuss Business or Enterprise. Security, deployment, governance, and observability features for Enterprise. # Available Models Models offered natively in the Factory platform. The **Reasoning** column lists the values each model accepts for `reasoningEffort` in [settings](/droid-cli/settings#reasoning-effort) and for `--reasoning-effort` on the command line. The model selector labels them differently, so `xhigh` appears there as **Extra High**. ## Anthropic logoAnthropic | Model | Model ID | Multiplier | Reasoning | | --- | --- | --- | --- | | Claude Fable 5.2\* | `claude-fable-5.2` | 3.2× | `low`, `medium`, `high` (default), `xhigh`, `max` | | Claude Fable 5.1\* | `claude-fable-5.1` | 4× | `off`, `low`, `medium`, `high` (default), `xhigh`, `max` | | Claude Fable 5\* | `claude-fable-5` | 4× | `off`, `low`, `medium`, `high` (default), `xhigh`, `max` | | Claude Opus 5.5 | `claude-opus-5-5` | 1.6× | `low`, `medium` (default), `high`, `xhigh`, `max` | | Claude Opus 5.5 Fast | `claude-opus-5-5-fast` | 3.2× | `low`, `medium` (default), `high`, `xhigh`, `max` | | Claude Opus 5 | `claude-opus-5` | 2× | `off`, `low`, `medium`, `high` (default), `xhigh`, `max` | | Claude Opus 5 Fast | `claude-opus-5-fast` | 4× | `off`, `low`, `medium`, `high` (default), `xhigh`, `max` | | Claude Opus 4.8 | `claude-opus-4-8` | 2× | `off`, `low`, `medium`, `high` (default), `xhigh`, `max` | | Claude Opus 4.8 Fast | `claude-opus-4-8-fast` | 4× | `off`, `low`, `medium`, `high` (default), `xhigh`, `max` | | Claude Opus 4.7 | `claude-opus-4-7` | 2× | `off`, `low`, `medium`, `high` (default), `xhigh`, `max` | | Claude Opus 4.6 | `claude-opus-4-6` | 2× | `off`, `low`, `medium`, `high` (default), `max` | | Claude Opus 4.5 | `claude-opus-4-5-20251101` | 2× | `off` (default), `low`, `medium`, `high` | | Claude Sonnet 5.5 | `claude-sonnet-5-5` | 0.8× | `off`, `low`, `medium`, `high` (default), `xhigh`, `max` | | Claude Sonnet 5 | `claude-sonnet-5` | 0.8× | `off`, `low`, `medium`, `high` (default), `xhigh`, `max` | | Claude Sonnet 4.6 | `claude-sonnet-4-6` | 1.2× | `off`, `low`, `medium`, `high` (default), `max` | | Claude Sonnet 4.5 | `claude-sonnet-4-5-20250929` | 1.2× | `off` (default), `low`, `medium`, `high` | | Claude Haiku 5.5 | `claude-haiku-5-5` | 0.04× | `off`, `low`, `medium` (default), `high`, `xhigh`, `max` | | Claude Haiku 4.5 | `claude-haiku-4-5-20251001` | 0.4× | `off` (default), `low`, `medium`, `high` | \* Anthropic requires all Mythos-class models comply with 30 day data retention for trust and safety, please see Anthropic's [data retention practices for Mythos-class models](https://support.claude.com/en/articles/15425996-data-retention-practices-for-mythos-class-models). Organization admins opt in to the Anthropic Data Retention Policy in model access settings. ## OpenAI logoOpenAI | Model | Model ID | Multiplier | Reasoning | | --- | --- | --- | --- | | GPT-6.2 Astra | `gpt-6.2-astra` | 3.2× | `low`, `medium` (default), `high`, `xhigh`, `max` | | GPT-6.2 Astra Fast | `gpt-6.2-astra-fast` | 6.4× | `low`, `medium` (default), `high`, `xhigh`, `max` | | GPT-6.2 Astra Ultra Fast | `gpt-6.2-astra-ultrafast` | 9.6× | `low`, `medium` (default), `high`, `xhigh`, `max` | | GPT-6 Astra | `gpt-6-astra` | 4× | `low`, `medium` (default), `high`, `xhigh`, `max` | | GPT-6.2 Sol | `gpt-6.2-sol` | 0.8× | `low`, `medium` (default), `high`, `xhigh`, `max` | | GPT-6.2 Sol Fast | `gpt-6.2-sol-fast` | 1.6× | `low`, `medium` (default), `high`, `xhigh`, `max` | | GPT-6.2 Sol Ultra Fast | `gpt-6.2-sol-ultrafast` | 2.4× | `low`, `medium` (default), `high`, `xhigh`, `max` | | GPT-6.1 Sol | `gpt-6.1-sol` | 0.8× | `low`, `medium` (default), `high`, `xhigh`, `max` | | GPT-6.1 Sol Ultra Fast | `gpt-6.1-sol-ultrafast` | 4.8× | `low`, `medium` (default), `high`, `xhigh`, `max` | | GPT-6 Sol | `gpt-6-sol` | 0.8× | `none`, `low`, `medium` (default), `high`, `xhigh`, `max` | | GPT-6 Sol Fast | `gpt-6-sol-fast` | 1.6× | `none`, `low`, `medium` (default), `high`, `xhigh`, `max` | | GPT-5.6 Sol† | `gpt-5.6-sol` | 1.6× | `none`, `low`, `medium` (default), `high`, `xhigh`, `max` | | GPT-5.6 Sol Fast† | `gpt-5.6-sol-fast` | 3.2× | `none`, `low`, `medium` (default), `high`, `xhigh`, `max` | | GPT-6 Luna | `gpt-6-luna` | 0.04× | `none`, `low`, `medium` (default), `high`, `xhigh`, `max` | | GPT-6 Luna Fast | `gpt-6-luna-fast` | 0.08× | `none`, `low`, `medium` (default), `high`, `xhigh`, `max` | | GPT-5.6 Luna | `gpt-5.6-luna` | 0.08× | `none`, `low`, `medium` (default), `high`, `xhigh`, `max` | | GPT-6.1 Terra | `gpt-6.1-terra` | 0.4× | `none`, `low`, `medium` (default), `high`, `xhigh`, `max` | | GPT-5.6 Terra | `gpt-5.6-terra` | 0.8× | `none`, `low`, `medium` (default), `high`, `xhigh`, `max` | | GPT-5.5 | `gpt-5.5` | 2× | `low`, `medium` (default), `high`, `xhigh` | | GPT-5.5 Fast | `gpt-5.5-fast` | 5× | `low`, `medium` (default), `high`, `xhigh` | | GPT-5.5 Pro | `gpt-5.5-pro` | 12× | `medium` (default), `high`, `xhigh` | | GPT-5.4 | `gpt-5.4` | 1× | `low`, `medium` (default), `high`, `xhigh` | | GPT-5.4 Fast | `gpt-5.4-fast` | 2× | `low`, `medium` (default), `high`, `xhigh` | | GPT-5.4 Mini | `gpt-5.4-mini` | 0.3× | `low`, `medium`, `high` (default), `xhigh` | | GPT-5.4 Mini Fast | `gpt-5.4-mini-fast` | 0.6× | `low`, `medium`, `high` (default), `xhigh` | | GPT-5.3-Codex | `gpt-5.3-codex` | 0.7× | `low`, `medium` (default), `high`, `xhigh` | | GPT-5.3-Codex Fast | `gpt-5.3-codex-fast` | 1.4× | `low`, `medium` (default), `high`, `xhigh` | | GPT-5.2 | `gpt-5.2` | 0.7× | `off`, `low` (default), `medium`, `high`, `xhigh` | † Promotional pricing. GPT-5.6 Sol bills at 1.6× through November 22, 2026, then returns to 2×. † Promotional pricing. GPT-5.6 Sol Fast bills at 3.2× through November 22, 2026, then returns to 4×. ## Google logoGoogle | Model | Model ID | Multiplier | Reasoning | | --- | --- | --- | --- | | Gemini 4 Neon | `gemini-4-neon` | 1.2× | `low`, `medium`, `high` (default), `xhigh` | | Gemini 4 Hydrogen | `gemini-4-hydrogen` | 0.6× | `low`, `medium`, `high` (default), `xhigh` | | Gemini 4 Carbon† | `gemini-4-carbon` | 0.8× | `low`, `medium` (default), `high` | | Gemini 4 Argon† | `gemini-4-argon` | 0.8× | `low`, `medium` (default), `high` | | Gemini 3.1 Pro | `gemini-3.1-pro-preview` | 0.8× | `low`, `medium`, `high` (default) | | Gemini 3.8 Flash† | `gemini-3.8-flash` | 0.3× | `low`, `medium`, `high` (default) | | Gemini 3.7 Flash† | `gemini-3.7-flash` | 0.3× | `low`, `medium`, `high` (default) | | Gemini 3.6 Flash | `gemini-3.6-flash` | 0.6× | `low`, `medium`, `high` (default) | | Gemini 3.5 Flash | `gemini-3.5-flash` | 0.6× | `minimal`, `low`, `medium`, `high` (default) | | Gemini 3 Flash | `gemini-3-flash-preview` | 0.2× | `minimal`, `low`, `medium`, `high` (default) | † Promotional pricing. Gemini 4 Carbon bills at 0.8× through December 1, 2026, then returns to 1.6×. † Promotional pricing. Gemini 4 Argon bills at 0.8× through December 1, 2026, then returns to 1.6×. † Promotional pricing. Gemini 3.8 Flash bills at 0.3× through January 1, 2027, then returns to 0.6×. † Promotional pricing. Gemini 3.7 Flash bills at 0.3× through January 1, 2027, then returns to 0.6×. ## xAI logoxAI | Model | Model ID | Multiplier | Reasoning | | --- | --- | --- | --- | | Grok 4.7 | `grok-4.7` | 0.8× | `low`, `medium`, `high` (default), `xhigh` | | Grok 4.6 | `grok-4.6` | 0.8× | `low`, `medium`, `high` (default), `xhigh` | | Grok 4.5 | `grok-4.5` | 0.8× | `low`, `medium`, `high` (default) | ## Factory logoDroid Core (Open Models) | Model | Model ID | Multiplier | Reasoning | | --- | --- | --- | --- | | Inkling | `inkling` | 0.4× | `off`, `minimal`, `low`, `medium`, `high` (default), `xhigh`, `max` | | Mistral Large 4 | `mistral-large-4` | 0.544× | `off`, `high` (default) | | Mistral Medium 3.5 | `mistral-medium-3.5` | 0.6× | `off`, `high` (default) | | GLM-5.3-Flash | `glm-5.3-flash` | 0.06× | `low`, `high` (default), `max` | | GLM-5.3 | `glm-5.3` | 0.56× | `low`, `high`, `max` (default) | | GLM-5.2 | `glm-5.2` | 0.56× | `off`, `high` (default), `max` | | GLM-5.2 Fast | `glm-5.2-fast` | 0.84× | `off`, `high` (default), `max` | | Kimi K3.1 Pro | `kimi-k3.1-pro` | 0.8× | `low`, `high`, `max` (default) | | Kimi K3 | `kimi-k3` | 1.2× | `off`, `low`, `high` (default), `max` | | Qwen3.8 Max | `qwen3.8-max` | 0.8× | `low`, `medium`, `xhigh` (default) | | Nemotron 3.5 Super | `nemotron-3.5-super` | 0.08× | `off`, `high` (default) | | Nemotron 3 Ultra | `nemotron-3-ultra` | 0.24× | `off`, `high` (default) | | DeepSeek V4.1 Flash 1017 | `deepseek-v4.1-flash-1017` | 0.12× | `off`, `low`, `high` (default), `max` | | DeepSeek V4.1 Flash | `deepseek-v4.1-flash` | 0.12× | `off`, `low`, `high` (default), `max` | | DeepSeek V4 Flash 0731‡ | `deepseek-v4-flash-0731` | 0.176× | `off`, `low`, `high` (default), `max` | | DeepSeek V4 Pro‡ | `deepseek-v4-pro` | 0.528× | `off`, `low`, `high` (default), `max` | | MiniMax M3.1 Flash | `minimax-m3.1-flash` | 0.06× | `low`, `medium`, `high`, `xhigh`, `max` (default) | | MiniMax M3 | `minimax-m3` | 0.12× | `high` (default) | | Muse Spark 1.3 | `muse-spark-1.3` | 0.5× | `low`, `medium`, `high` (default), `xhigh` | | Muse Spark 1.2 | `muse-spark-1.2` | 0.5× | `low`, `medium`, `high` (default), `xhigh` | | Beam 1.0 | `beam-1.0` | 0.52× | `low`, `medium`, `high` (default), `xhigh`, `max` | | MiniMax M2.7‡ | `minimax-m2.7` | 0.12× | `high` (default) | | Kimi K2.5‡ | `kimi-k2.5` | 0.25× | `off`, `high` (default) | | GLM-5.1‡ | `glm-5.1` | 0.55× | `off`, `high` (default) | ‡ Deprecated. DeepSeek V4 Flash 0731, DeepSeek V4 Pro, MiniMax M2.7, Kimi K2.5 and GLM-5.1 remain available for now and will be removed in a future release. ## Custom models Configure custom models through [Custom Models (BYOK)](/model-independence/byok). Configure custom model endpoints and bring your own API keys. Let Factory route requests across providers automatically. # Contact Support Find the right channel to get help with Factory, depending on what you need. If you need help with Factory, the team and community are here for you. Pick the channel that matches your request so you reach the right people fast. ## Choose a channel Account, billing, and technical issues that need the Factory team. Questions, feedback, and conversation with the community and team. Reproducible bugs and feature requests, tracked in the open. ## Email support Use email for anything specific to your account that should not be public: - Account access, organization, and membership - Billing, invoices, and plan changes - Technical problems that need someone to look at your account Reach the team at [support@factory.com](mailto:support@factory.com). ## Community on Discord - How-to questions and usage tips - Product feedback and ideas - Connecting with other users and the team [Open the Factory Discord invite](https://discord.gg/zuudFXxg69). ## Bugs and feature requests - Reproducible bugs in Droid - Feature requests and enhancement ideas Search the existing issues first, then open a new one if your report is not already there. ## Report an AI safety concern To report adverse impacts or concerns about Factory's AI systems, use our [AIMS External Reporting Form](https://docs.google.com/forms/d/e/1FAIpQLScJASmKUdwKqFQJPMfxhfZkcFp8P4feuIIHBp8BlAYb0jIRlQ/viewform). ## Write a report we can act on Whether you email us or open a GitHub issue, a few details help us resolve it faster: {/* sweep-allow: term-bullets */} - **What happened** and what you expected to happen instead - **Steps to reproduce**, including the exact command or action - **Version and environment**: operating system, terminal or IDE, and the Droid version - **Evidence**: relevant error messages, logs, or screenshots - **Impact**: how often it happens and whether it blocks your work Run `droid --version` to confirm which version you are on before reporting a bug. Found a security vulnerability? Do not post it publicly. Report it privately to [security@factory.com](mailto:security@factory.com). Running Droid in a regulated or enterprise environment? See Factory for Enterprise. # Factory App Use the Factory App for a visual Droid workspace with local machine access, project switching, and reviewable sessions. Use the Factory App when you want a visual workspace for Droid sessions, project switching, model controls, machine connections, and review state. Preview whatever Droid makes, from code to documents to live sites, and comment right where a change belongs. The app keeps local, web, and mobile review surfaces connected to the same Factory runtime. The app runs on macOS, Windows, and Linux. To install it, follow the [Factory App quickstart](/factory-app/quickstart) or, on Linux, the [Linux install guide](/factory-app/linux). ## When to use the app - You want to review Droid sessions, diffs, and project state outside a terminal. - You switch between projects or machines often. - You need a guided path to local machine access and Factory-managed cloud computers. - You want web and mobile review surfaces for work that starts on your workstation. - You want to hand a large project to a team of agents with [Workstreams](/workstreams/overview). ## What the Factory App brings to your workflow The app is a dedicated workspace with Droid built in, organized around reviewing and refining whatever a session produces. Documents, presentations, spreadsheets, PDFs, live websites, and full code diffs render beside the session that produced them. Design mode selects an element and says what to change; inline code review comments on a diff line by line. Droid acts on the feedback in place. Work directly on your local filesystem with your full development environment, informed by project context, documentation, and team knowledge. Filter and group sessions across projects and machines, synchronized with Jira, Notion, Slack, Linear, PagerDuty, and MCP tools. Delegate work from Slack, Linear, and other apps. The terminal-first surface for the same platform. # Factory App Quickstart Install the Factory App, connect your codebase, and start your first reviewable Droid session. Use this quickstart to install the Factory App, connect a codebase, and start a first reviewable Droid session. ## Step 1: download and install - [Mac (Apple Silicon)](https://app.factory.ai/api/desktop?platform=darwin&architecture=arm64): Download for M-series Macs - [Mac (Intel)](https://app.factory.ai/api/desktop?platform=darwin&architecture=x64): Download for Intel Macs - [Windows (x64)](https://app.factory.ai/api/desktop?platform=win32&architecture=x64): Download for Intel and AMD PCs - [Windows (ARM64)](https://app.factory.ai/api/desktop?platform=win32&architecture=arm64): Download for Snapdragon and ARM PCs - [Linux (x64 and ARM64)](https://docs.factory.com/factory-app/linux): Install with a script or a .deb package - **Mac**: Open the `.dmg` file and drag Factory to Applications - **Windows**: Run the installer - **Linux**: Follow [Install on Linux](/factory-app/linux) to run the install script or install the `.deb` package Launch the Factory App and sign in with your account. Deploying to managed Windows devices? See [Windows MSIX deployment](/enterprise/windows-msix-deployment) for PowerShell installation, device provisioning, and organization-controlled updates. ## Step 2: connect to your codebase Set your working directory to your project folder. The Factory App connects directly to your local machine. Choose your preferred AI model from the model selector. You can change this anytime. ## Step 3: start a reviewable session Start with a context-gathering request: ```text Analyze this codebase and explain the architecture, key entry points, and test setup ``` Then ask for one small, verifiable change: ```text Add error handling to the user authentication flow and show me the diff before applying it ``` Droid analyzes your codebase, proposes changes, and shows what will be modified before applying anything. ## Step 4: connect your engineering systems The Factory App becomes more useful when Droid can read the systems where work starts. Connect team context through: Connect tools and internal services through Model Context Protocol servers. Let Droid read issues and turn product requests into reviewable implementation work. Pull thread context into triage, incident response, and follow-up tasks. ## Step 5: scale with automations Once Droid is part of your daily work, move repeatable steps into persistent automations that cover triage, code review, QA, documentation, and incident response. See which triggers and templates fit your workflow. Run repeatable engineering workflows on a schedule or trigger. Coordinate planned, delegated, and validated multi-agent work. So Droid follows your repository conventions. Before adding more users or shared usage. # Install the Factory App on Linux Install the Factory App on Linux with the install script or the .deb package, then update or remove it. The Factory App runs on x64 and ARM64 Linux. Install it with a script that works on any distribution, or with a `.deb` package on Debian and Ubuntu. For macOS and Windows, follow the [Factory App quickstart](/factory-app/quickstart). ## Choose an install method | Method | Installs to | Root access | Updates | | :----- | :---------- | :---------- | :------ | | [Install script](#install-with-the-script) | `~/.local/share/factory-desktop`, for your user | Not needed | The app updates itself | | [`.deb` package](#install-the-deb-package) | `/usr/lib/factory-desktop`, for every user | Needed | The app links you to each new `.deb` | On Ubuntu 24.04 and later, install the `.deb`. AppArmor restricts unprivileged user namespaces on those releases, and only the `.deb` ships the sandbox helper the app needs to start without them. ## Requirements - An x64 CPU that supports AVX2, or an ARM64 CPU. - A Secret Service provider for sign-in credentials. GNOME and KDE include one. On a minimal window manager, install and start GNOME Keyring, KWallet, or KeePassXC with Secret Service integration. - For the install script: `curl`, `tar`, `sha256sum`, `flock`, and OpenSSL 3. For the hostnames the app must reach, see the [outbound network allowlist](/enterprise/network-and-deployment#outbound-network-allowlist). ## Install with the script ```bash curl -fsSL https://downloads.factory.ai/factory-desktop/install.sh | sh ``` The script detects your architecture, downloads the latest release, and verifies its signed checksum before extracting it. It then adds a `factory-desktop` launcher to `~/.local/bin` and a **Factory** entry to your application menu. To install a specific release, pass its version: ```bash curl -fsSL https://downloads.factory.ai/factory-desktop/install.sh | sh -s -- --version ``` ## Install the `.deb` package Run these commands in Bash. They download the latest `.deb` for your architecture and install it with its dependencies: ```bash version=$(curl -fsSL https://downloads.factory.ai/factory-desktop/LATEST) arch=$(dpkg --print-architecture) curl -fLO "https://downloads.factory.ai/factory-desktop/releases/${version}/linux/${arch/amd64/x64}/factory-desktop_${version}_${arch}.deb" sudo apt install "./factory-desktop_${version}_${arch}.deb" ``` ## Sign in Open **Factory** from your application menu, or run `factory-desktop` in a terminal, and sign in with your account. Then continue with [step 2 of the quickstart](/factory-app/quickstart#step-2-connect-to-your-codebase) to connect your codebase. ## Update - **Script installs** update from inside the app. When the app offers an update and you accept it, the app downloads the release, verifies its signature, switches to it, and restarts. Running the install script again also installs the latest release; restart the app to use it. - **`.deb` installs** update through a new package. Your package manager owns the installed files, so the app does not replace them. When the app offers an update, accepting it opens the download for the new `.deb`. Install that file with `sudo apt install`, as in the commands above. To block in-app updates for your organization, turn on **Disable Auto Update** under **Enterprise Controls → Agent Behavior**. The setting applies to Linux script installs the same way it applies to macOS and Windows. ## Uninstall Remove a script install, including its launcher and menu entry: ```bash curl -fsSL https://downloads.factory.ai/factory-desktop/install.sh | sh -s -- --uninstall ``` Remove a `.deb` install: ```bash sudo apt remove factory-desktop ``` Neither command removes your settings in `~/.config` and `~/.factory`. ## Troubleshoot installation Check whether the script warned that AppArmor restricts unprivileged user namespaces. If it did, uninstall the script install and install the `.deb` instead. The app stores sign-in credentials in a Secret Service provider, and the install script warns when it finds none. Install and start GNOME Keyring, KWallet, or KeePassXC with Secret Service integration, then sign in again. The script verifies each release with OpenSSL 3. If `openssl version` reports 1.x, upgrade OpenSSL or install the `.deb`. If it reports 3.x, the download did not match Factory's signature: run the script again, and contact [support@factory.com](mailto:support@factory.com) if it fails a second time. Connect a codebase and start a session. Configure organization-managed settings. # Worktrees in the Factory App Learn how to run Factory App sessions in separate Git worktrees while keeping your main project folder unchanged. Use a worktree when you want Droid to work on another task without changing the files in your main project folder. The Factory App creates a separate working directory for the session, prepares it, and keeps it isolated from your other work. Factory-managed worktrees are available for Git projects on your local machine and connected Droid Computers. Worktrees require a Git repository. For folders that are not Git repositories, start the session without a worktree. ## What is a worktree? A Git repository can have more than one working directory at the same time. Each directory has its own files and current branch, while all of them share the same commit history. You can think of your main project folder as your regular workspace and a worktree as a second workspace for a separate task. Changes in one workspace do not appear as uncommitted changes in the other. This allows you to make file changes on the same repository in parallel sessions, without the changes interfering with each other. ### Key terms A working directory that contains the repository files for a specific branch or commit. The project directory you selected in Factory. This is usually the checkout you already use in your editor and terminal. A separate checkout of the same Git repository. It has its own working files but shares commits and branches with the main checkout. The branch Factory uses as the starting point for a new worktree. Optional instructions that prepare a new worktree, give Droid initial context, or clean up services later. ## Create your first worktree Start a new session and choose the Git repository you want Droid to work on. Open the **Worktree** selector in the composer. Choose **New worktree**. Use the branch selector to choose the base branch. Factory creates a new branch from it by default, without switching branches in your main checkout. Open the panel beside **New worktree** if you want to keep the worktree permanently, use an existing branch, or run a setup profile. You can leave the defaults in place for your first session. Factory creates the checkout, runs the selected setup profile, and starts Droid inside it. The session shows the creation progress and worktree path. To work in the selected project directory instead, choose **Start without worktree**. ## Choose how long to keep it Every Factory-managed worktree has a lifecycle: | | Ephemeral | Persistent | | ----------------------- | -------------------------------------- | ------------------------------------ | | Best for | A task you expect to finish soon | An environment you plan to revisit | | Sessions | Usually one | Can contain multiple | | Automatic cleanup | Eligible, unless a session is pinned | Never | | Available as a project | No | Yes | Choose **Ephemeral** for most isolated tasks. Choose **Persistent** when you want a long-lived checkout that appears in the project selector for future sessions. Factory remembers your last lifecycle choice for the project. ## Choose how the branch works By default, Factory creates a new branch from the base branch you selected. This is the simplest option because the new worktree owns its branch from the start. To continue work on a branch that already exists, open the branch mode control and choose **Use existing branch**. The branch cannot be: - The repository's default branch. - Checked out in your main checkout or another worktree. If you are unsure which branch mode to use, keep the default. Git allows a branch to be checked out in only one worktree at a time. ## Prepare new worktrees automatically A new checkout may need dependencies, generated files, or project-specific instructions before Droid can begin. A setup profile runs those tasks each time Factory creates a worktree for the project. In the desktop app, open **Settings → Worktrees** and select a project under **Setup profiles**. Select **Add profile** and enter a name. Add at least one setup script, initial prompt, or cleanup script. In the new-session composer, open the panel beside **New worktree** and select the profile. Factory preselects the last profile you used for that project. Each profile can contain: Runs from the root of the new worktree before the session starts. Use it to install dependencies or prepare local tooling. Gives Droid project-specific instructions before it receives your session prompt. Your prompt waits until this instruction finishes. Runs from the worktree root before Factory removes the checkout. Use it to stop services or remove external resources created during setup. Setup and cleanup scripts can use `REPO_ROOT_PATH` to find the main checkout. Factory removes credentials and Factory-specific environment variables before running profile scripts. ### Share a profile with your repository Profiles created in the app stay on the selected machine. To give everyone in the repository the same profile, commit a `.yaml` or `.yml` file under `.factory/worktree-setups/`: ```yaml title=".factory/worktree-setups/node.yaml" name: Node.js setup script: | set -euo pipefail pnpm install initial_prompt: Read the repository instructions before starting. cleanup_script: | docker compose down ``` The supported fields are `name`, `script`, `initial_prompt`, and `cleanup_script`. Shared profiles are read-only in the app. Edit their YAML files in the repository to change them. ## Include local files that Git ignores A worktree starts with the files tracked by Git. Local files excluded by `.gitignore`, such as `.env.local`, are not present automatically. To copy selected ignored files into each new Factory-managed worktree, create `.worktreeinclude` in the root of your main checkout. List one repository-relative path or directory per line: ```text # Local environment and tool configuration .env.local local/ ``` Blank lines and lines that begin with `#` are ignored. Directories are copied recursively. Factory copies matching files before running the setup profile, so the setup script can use them. Only paths already ignored by Git are eligible. Factory skips: - Tracked or unignored paths. - Missing files and directories. - Absolute paths and paths outside the repository. - Symbolic links. - Files that already exist in the new worktree. Review each path before adding it. Files ignored by Git can still contain credentials or other sensitive data. ## Manage and remove worktrees In the desktop app, open **Settings → Worktrees** to: - Change the worktree directory. The default is `~/.factory/worktrees`. - Set the number of ephemeral worktrees Factory keeps. The default limit is 15, but the count may exceed it if no worktrees are eligible for cleanup. - Browse managed worktrees by repository and machine. - Check each worktree's path, size, lifecycle, and active sessions. - Delete a worktree you no longer need. You can also delete a worktree from its sidebar menu. Before you confirm, Factory shows any uncommitted changes, untracked files, and unpushed commits it found. Removing the local branch or remote branch is a separate choice. When you archive the last session in a worktree, Factory asks whether to delete the worktree. If you confirm, Factory runs its cleanup script, removes the checkout, and archives the associated sessions. If you cancel, Factory keeps both the session and the worktree. ### How automatic cleanup works When Factory prepares a new worktree, it checks whether the new worktree would exceed your ephemeral worktree limit. If so, Factory starts cleanup with the least recently used ephemeral worktree and skips that worktree if it has: - A pinned session. - An active or recently used session. - Uncommitted changes or untracked files. - An open pull request. - Unpublished commits, unless the related pull request is merged. If Factory skips a worktree, it checks the next eligible candidate. The limit can remain exceeded if there are not enough safe candidates to remove. Persistent worktrees and worktrees with a pinned session do not count toward the limit. Automatic cleanup respects Git worktree locks and removes only the checkout, not its Git branch. If Factory cannot verify that a checkout is safe to remove, it preserves it. Factory runs background maintenance to keep sessions and worktrees in sync. After an interruption, it can also clean up unused ephemeral worktrees when it is safe to do so. ## Frequently asked questions ### Why is my `.env` file missing? Git worktrees contain tracked files. If Git ignores the file, add its path to [`.worktreeinclude`](#include-local-files-that-git-ignores) so Factory copies it into future worktrees. ### Does deleting a worktree delete its branch? Not automatically. Factory treats removal of the checkout, local branch, and remote branch as separate actions. Automatic cleanup removes only the checkout. ### What happens if I restore a session after deleting its worktree? If the worktree checkout no longer exists, restoring the archived session resumes it from the main checkout (the project directory you selected in Factory) instead of recreating the deleted worktree. ### Where does Factory store worktrees? Factory uses `~/.factory/worktrees` by default. Change the location under **Settings → Worktrees**. Configure personal defaults for Factory App sessions. Start isolated worktree sessions from the Droid CLI. Install the app and start a reviewable Droid session. Give every worktree session your repository instructions. # Multiplayer Sessions Share a Droid session with teammates in your organization so everyone can follow along, send messages, and steer the same session together. Multiplayer sessions are in Private Preview and are turned on per organization. Contact your Factory account team to request access. Behavior and labels may change during the preview. A multiplayer session is a Droid session that several people in your organization work in together. Everyone in the session sees the same transcript live, can send messages, and can steer Droid while it works. A multiplayer session doesn't run as any one person. It runs as an [agent profile](/enterprise/agent-profiles), on that profile's computer, with that profile's Git credentials and connectors. That is why setting up an agent profile is the first step. ## How it works {/* sweep-allow: term-bullets */} - **Shared identity.** Droid runs as the agent profile the session was started on. No individual member's personal credentials, connectors, or computer are used. - **Shared transcript.** Members see each message as it streams, who sent it, who is typing, and who is viewing right now. - **Shared control.** Any member can send messages, queue follow-ups, answer permission prompts, and stop Droid. - **Shared workspace.** Members can browse the session's files, review its changes, and open a terminal in the session's folder. Multiplayer sessions start in two places: | Where | How a session becomes multiplayer | | --- | --- | | [The Factory App](#in-the-factory-app) | Start a new shared session, or share a personal session as a shared copy. Teammates join by link or by invitation. | | [Delegation surfaces](#in-delegation-surfaces) | Delegate work in a Slack or Microsoft Teams channel, a Google Chat space, or a Linear issue. Teammates who reply join the same session. | Either way, it's the same kind of session: members can open it in the Factory App on desktop or the web. ## Before you start - Your organization is in the multiplayer sessions Private Preview. - Your organization uses Factory-hosted services. Multiplayer sessions aren't available in [airgapped deployments](/enterprise/airgapped-deployment). They work even if your organization turns off [Session Contents Sync](/enterprise/hierarchical-settings-and-org-control#session-contents-sync). - Your plan includes agent profiles. See [agent profiles](/enterprise/agent-profiles). - Everyone who joins is an active member of the same Factory organization. - For delegation surfaces, the delegation app is connected. See [Delegations](/delegations). ## Set up an agent profile first Every multiplayer session runs as an agent profile, which decides the session's computer, repositories, Git credentials, connectors, and default model. Before your team starts sharing sessions, a Manager or Owner sets up the **Org Default** profile in **Settings → Identity** → **Agent Profiles**. Org Default is always offered when someone starts a shared session in the Factory App, and it serves every delegation request that no custom profile serves. Follow [configure an agent profile](/enterprise/agent-profiles#configure-an-agent-profile), and check these for multiplayer sessions: - The profile's [compute](/enterprise/agent-profiles#choose-compute) includes the repositories your team works in: its Environment for **Dynamic**, or its computers for **Persistent**. - The profile can access those repositories and has the **Git Credentials** and **Connectors** shared sessions need. Shared sessions clone and push as the agent profile, not as the person who started them. See [repository access](/delegations#repository-access-for-the-service-account). Org Default is built in, but until a Manager or Owner saves it, shared sessions use it as-is: a default model, with no instructions, plugins, or Git credentials. Shared sessions may not be able to reach your repositories until it's set up, so set it up first. To give a team a different model, Environment, or set of credentials, [create a custom agent profile](/enterprise/agent-profiles#create-a-custom-agent-profile) and limit its [access](/enterprise/agent-profiles#access) to that team. People can start shared sessions only on profiles they have access to. For delegation surfaces, also [assign the profile to the app](/enterprise/agent-profiles#assign-profiles-to-delegation-apps). Anyone in a shared session works with the profile's access, including its connectors, so give each profile only what its work needs. ## In the Factory App In the Factory App on desktop or the web, you can start a new shared session or share one you already started, then invite teammates to it. ### Start a shared session 1. Open **New Session**. 2. In the computer picker, choose **Shared** ("Teammates can join by link"). You can also run **Create New Shared Session** from the command palette. 3. Choose an **Agent profile**. Factory selects the profile you used last, or Org Default. 4. Choose a model, or leave it on **Profile default**, and send your first message. The session runs on the profile's computer. If that computer is still starting, the session shows **Starting the shared computer** until it's ready. ### Share a personal session You can turn a session you already started into a multiplayer session. Factory creates a shared copy that runs on an agent profile, titled with "(shared)" after the original title. Your personal session stays as it was, on its own computer. 1. In the session header, select **Share**. 2. In **Share session**, review the options: - **Agent profile**, under **More**: the profile the copy runs on. - **Bring unpushed changes**: carry your uncommitted and unpushed code changes into the copy. Choose **Share without code changes** to start from the remote branch instead. - **Share a summary only**: teammates see a short summary of the conversation so far, and Droid gets a detailed one. By default the copy includes the full history. 3. Select **Next**. Factory summarizes the conversation if you asked it to, creates the shared session, and prepares its link. In the copy, a marker shows where the personal session ended and the shared session began. The **Share** option to create a copy is available only to the session's owner, on a session that isn't already shared. To share it: - Droid must not be working. - The session's computer must be connected and running an up-to-date Droid. - The agent profile's computer must have the session's repository. If something blocks the copy, the dialog says why, for example **Wait for Droid to finish working** or **Reconnect to this session's machine to share it**. Some code changes can't be carried over, such as very large changes or a merge or rebase in progress. Finish or reduce them, or choose **Share without code changes**. ### Invite teammates Open **Share** in a shared session to manage who has access. - **Copy link**: anyone in your organization who opens the link sees **Join session** and becomes a member when they select it. You can also use **Copy Sharable Link** in the session menu. - **Add people**: search your organization by name or email. People you add get a notice in their Factory inbox. - **People with access**: lists the members. The person who started the session is the **Owner**. Every member has the same access: they can view and send messages in the session. There is no view-only member role. To take someone's access away, select **Remove** next to their name. To leave a session yourself, select **Leave**. The last member can't be removed; archive the session instead. ### Send messages Every message shows who sent it. When Droid is busy, new messages wait as steering or queued messages, and every member sees them with the sender's name. You can clear your own pending messages, or all of them. Mention a teammate with `@` to send them an inbox notice. React to a message with an emoji to acknowledge it without interrupting Droid. ### Session settings The agent profile sets the session's connectors, MCP servers, skills, and compute. Members can view them but not change them. Select **Shared session settings** to see the session's agent profile, model, reasoning, and autonomy. - Only the session's owner can change the model. - Shared sessions run at High autonomy, and members can't change the autonomy level. See [Auto-Run](/autonomy-and-safety/auto-run). - Any member can answer a permission prompt, but only for that one request. Answers that would allow a command from then on aren't available in shared sessions. - Any member can stop Droid. ### Work with the session's files Members can open the session's **Changes**, **Files**, and **Terminal** in the pane beside the chat. Edits and terminal commands run on the agent profile's computer, as the agent profile. ### Ambient mode When several people talk in the same session, not every message is meant for Droid. With ambient mode, Droid decides which untagged messages are meant for it and answers only those. Droid still reads every message as context. Ambient mode starts once two or more people have typed in a session. It applies only to messages people type in the Factory App. - **Make sure Droid answers.** Include `@Droid` in your message. Droid always replies to a message that tags it. - **Get a reply to a held message.** When Droid doesn't answer, a **Droid stayed quiet** row appears under the message. Select **Send** to ask Droid to reply. The request is posted as a message from you, quoting the held message. - **Turn it off.** Go to **Settings → Session Defaults**, find **Multiplayer**, and turn off **Ambient mode** to have Droid answer every message. Ambient mode is on by default. The setting applies to sessions you start from then on, not to sessions that already exist. If you don't see the **Multiplayer** section, ambient mode isn't turned on for your organization yet, and Droid answers every message. ## In delegation surfaces When someone [delegates](/delegations) work in a Slack or Microsoft Teams channel, a Google Chat space, or a Linear issue, the session runs as the agent profile that serves them. It's a multiplayer session from the start, with no extra step to share it. ### Teammates join by replying When another member of your Factory organization replies in the thread or issue, their message goes to the same session and they become a member of it. Droid answers each person in turn. If Droid is busy, the message is queued and runs next. Factory matches people by email. A reply from someone Factory can't match to an active member of your organization is refused, and the session doesn't change. Use the same email in Factory and the delegation app. ### Open the session in the Factory App Members can open the session in the Factory App from the link Droid posts, and keep working there with everything described in [In the Factory App](#in-the-factory-app). A shared session that started in a private Slack channel can be joined by link only by members of that channel. ### Direct messages stay personal A direct message to Factory in Slack, Microsoft Teams, or Google Chat runs as the person who sent it, with their own Git credentials and connectors. It's never shared. See [personal and shared identity](/delegations#personal-and-shared-identity). ### Ambient replies in chat threads In Slack, Microsoft Teams, and Google Chat, your organization can let Droid answer replies in threads it's already working in, even when they don't mention it. A Manager or Owner turns this on or off under **Ambient replies** in **Settings → Delegations**. After 24 hours without Droid activity in a thread, mention Droid again to bring it back. ## Limitations {/* sweep-allow: term-bullets */} - **No CLI support.** You can't start, join, or chat in a multiplayer session from the Droid CLI. The CLI's `/share` command creates an organization view-only link to a session, which is a different feature. - **No whole-session unshare.** Remove members one at a time, or archive the session. - **Profile settings are fixed per session.** Members can't change the session's agent profile, connectors, MCP servers, skills, or autonomy. - **Ambient mode is still being tuned.** The **Droid stayed quiet** row and how Droid decides when to reply may change during the preview. ## Troubleshooting Your organization may not be in the Private Preview yet. Contact your Factory account team. The profile's computer or Environment doesn't include the session's repository, or the profile can't access it. Add the repository to the profile's Environment and give the profile access. See [repository access](/delegations#repository-access-for-the-service-account). You don't have access to any custom profile, and Org Default couldn't be loaded. Ask a Manager or Owner to check **Settings → Identity → Agent Profiles**. You aren't a member of the session and can't join it by link. It may have started in a private channel you're not in, or in another organization. Ask to be added to that channel, or ask a member to add you. Every shared session computer may be busy, or your organization may have reached its usage limit. Try again later, or ask a Manager or Owner to check usage. Factory couldn't match their account in the delegation app to an active member of your organization. Check that the email on that account matches their Factory account email. Set up the agent profile multiplayer sessions run as. Connect Slack, Microsoft Teams, Google Chat, Linear, and Jira. Give an agent profile Dynamic compute with your repositories. The desktop and web workspace where you open multiplayer sessions. # App settings Manage personal session defaults and organization usage alerts in the Factory App. The Factory App lets you set personal session defaults so every new session starts the way you want. Your choices are **capped by org policy**: if your organization enforces hard controls, your preferences take effect only within the boundaries those controls allow. See [Enterprise Controls & Managed Settings](/enterprise/hierarchical-settings-and-org-control) for the org side. ## Session defaults Session defaults are applied when a new session starts. In the Factory App, use the mode selector for **Normal Mode**, **Spec Mode**, or **Mission Mode**, and the Autonomy selector for `Auto Off`, `Auto Low`, `Auto Medium`, or `Auto High`. ### Default model Set `model` to a [model ID from the catalog](/models). This is the model new sessions use unless you pick a different one from the model selector. For custom models, see [Custom Models (BYOK)](/model-independence/byok). ### Reasoning effort `reasoningEffort` adjusts how much structured thinking the model performs before replying. The available levels and the default are **set by each model**, so the [Available Models](/models) table is the source of truth for what a given model accepts. Across the catalog they range from least to most deliberation: {/* sweep-allow: term-bullets */} - **`off` / `none`**: no structured reasoning (fastest). - **`minimal`**, **`low`**, **`medium`**, **`high`**: progressively more deliberation. - **`extra high`**, **`max`**: the deepest reasoning, where a model offers it. ### Interaction mode `sessionDefaultSettings.interactionMode` sets whether new sessions start in **Normal Mode** (`auto`) or **Spec Mode** (`spec`). In the app, the mode selector switches between the two. See [Interaction Modes](/autonomy-and-safety/specification-mode) for what each mode does. ### Autonomy level `sessionDefaultSettings.autonomyLevel` sets the default [Autonomy Level](/autonomy-and-safety/auto-run) for new sessions: `off` keeps manual approvals; `low`, `medium`, and `high` pre-authorize work at or below that risk level. In the app, the Autonomy selector chooses `Auto Off`, `Auto Low`, `Auto Medium`, or `Auto High`. ### Spec mode overrides When sessions start in Spec Mode, you can use a different model and reasoning effort for planning: - `sessionDefaultSettings.specModeModel`: the model used for spec mode planning. See [Models](/models) for available IDs. - `sessionDefaultSettings.specModeReasoningEffort`: reasoning effort for the spec mode model. Same values as `reasoningEffort`. ### Delegation defaults If your organization uses [Delegations](/delegations), you can set a personal DM delegation machine, model, reasoning level, and custom instructions under **Settings → Session Defaults → Delegations**. The **DM delegation machine** chooses the computer or Environment that your Slack DMs to Factory run on. The other defaults apply only to work you delegate from Slack, Microsoft Teams, Linear, or Jira: your model and reasoning level override the organization's defaults when policy allows, and your instructions are added to the organization's instructions. These defaults are saved to your Factory account, not `settings.json`. See [Set personal delegation defaults](/delegations#set-personal-delegation-defaults). ## Cloud session sync When `cloudSessionSync` is on, sessions are mirrored to the Factory App so you can revisit conversations from any browser. Your organization can turn off **Session Contents Sync** for everyone, in which case Factory stores only session metadata and, if your organization allows them, session titles and workstream shared folders. See [Session contents sync](/enterprise/hierarchical-settings-and-org-control#session-contents-sync). ## Organization usage alerts Open **Settings → Usage → Organization Usage** to view your active organization's Standard FSC usage for the current calendar month. The month follows the billing subscription's time zone. Usage is scoped to the active organization, not rolled up across every organization in the enterprise. This section is available to Enterprise organizations with organization usage alerts enabled. All organization members can view usage. Only Owners and Managers can change the threshold or email setting. ### Set a monthly alert threshold 1. Select **Set threshold**. 2. Enter a positive amount in **Monthly Alert Threshold (M credits)**. For example, `50` means 50 million credits. 3. Select **Save**. The usage display shows credits consumed, the saved threshold, and the percentage used. Without a threshold, it shows **Unlimited**. Select **Edit threshold** to change the amount, or **Remove threshold** to clear it. The monthly alert threshold is informational, not a real-time usage limit. Reaching it never blocks usage or changes billing. It does not replace individual credit caps or your contracted billing terms. ### Enable organization alert emails After saving a threshold, turn on **Organization Usage Alert Emails**. Emails are off by default and notify the organization's active Owners and Managers at 80% and 100% of the threshold. Turn the switch off to stop emails while keeping the threshold visible. Removing the threshold also disables emails; setting a new threshold does not automatically turn them back on. These controls are stored for the organization in the Factory App, not in personal `settings.json`. Changes to the threshold or email setting appear in the [audit log](/enterprise/audit-log#organization-usage-alert-settings). ## How your preferences interact with org policy Your personal defaults are **session defaults**, not hard controls. They use the most-local-wins precedence: your choice overrides an org default, and a runtime override (such as a `--settings` flag or an in-app selector change) overrides your saved default. But org hard controls always cap what you can choose: - `modelPolicy` (`allowedModelIds`, `blockedModelIds`) decides which models exist at all. You can pick any allowed model, but blocked models are not available. - `maxAutonomyLevel` caps the effective `autonomyLevel` no matter who set it. If the org sets `medium`, your `high` default is clamped to `medium`. In short: your org decides the **boundaries**, and you pick your **preferred defaults inside those boundaries**. For the full hierarchy, merge semantics, and org schema, see [Enterprise Controls & Managed Settings](/enterprise/hierarchical-settings-and-org-control). Full settings.json reference for the Droid CLI. Org-managed settings hierarchy, merge semantics, and schema. Normal, Spec, and Mission Mode with Autonomy Level. How Autonomy Level controls approval prompts. # Droid CLI Use the Droid CLI to run Factory from your terminal, editor, tests, and Git workflow. Use the Droid CLI when you want Droid beside your shell, editor, tests, and Git workflow. It gives the same Factory runtime through an interactive terminal UI with project context, approvals, MCP tools, Missions, and headless execution. ## When to use the CLI - You want Droid to work in the same terminal where you run Git, tests, and scripts. - You prefer keyboard-first review of plans, tool calls, and diffs. - You need quick access to shell commands, slash commands, and project-local context. - You want a path from interactive work to `droid exec` automation. **Quick tip:** Press ! to toggle bash mode and run shell commands directly without AI interpretation. Press Esc to return to normal mode. See the [CLI Reference](/droid-cli/cli-reference#bash-mode) for details. ## Key capabilities The full Factory platform is available from the terminal. Launch multi-agent [Missions](/missions/overview) with `/missions` or `droid exec --mission`, delegate scoped tasks to [Custom Droids](/harness/subagents) via `/droids`, and package reusable procedures as [Skills](/harness/skills) with `/skills` or `/create-skill`. To extend the harness, connect external tools and data sources over [MCP](/harness/mcp) (`droid mcp add` or `/mcp`), run shell commands around agent lifecycle events with [Hooks](/harness/hooks) (`/hooks`), and install bundles of commands, droids, skills, and hooks as [Plugins](/harness/plugins) (`droid plugin install` or `/plugins`). When a workflow stabilizes, take it headless with [Exec Mode](/droid-exec/overview): `droid exec` runs in scripts and CI/CD pipelines with structured input and output formats. ## What `droid` brings to your workflow Droid plans, implements, tests, and reviews changes end to end while approval workflows keep you in control. It works from deep codebase understanding: project files, repository instructions, and connected knowledge inform every answer and scoped change. Connect Jira, Notion, Slack, Linear, PagerDuty, and MCP tools to keep development synchronized with team systems, and move repeatable local workflows into Droid Exec for scripts and CI/CD pipelines. Configure project-specific guidance and conventions. Package reusable procedures as self-contained workflows. # Droid CLI Quickstart Install the Droid CLI, start an interactive terminal session, and delegate your first reviewable coding task. Use this quickstart to install the Droid CLI, start an interactive terminal session, and delegate a first scoped task. You will see how Droid reads your codebase, proposes changes, and waits for review before editing. ## Before you begin Make sure you have: A terminal open in a code project A Git repository (recommended for the full workflow demonstration) ## Step 1: Install and start Droid **macOS/Linux:** `curl -fsSL https://app.factory.ai/cli | sh` **Homebrew:** `brew install --cask droid` **Windows:** `irm https://app.factory.ai/cli/windows | iex` **npm:** `npm install -g droid` **Linux users:** Ensure `xdg-utils` is installed for proper functionality. Install with: `sudo apt-get install xdg-utils` Then navigate to your project and start the Droid CLI. You'll see Droid's welcome screen in a full-screen terminal interface. If prompted, sign in via your browser to connect to Factory's development agent. ## Step 2: understand your codebase Start by asking Droid to map the project before it edits anything: ```text > analyze this codebase and explain the overall architecture ``` ```text > where are the main entry points, test commands, and code conventions? ``` Droid reads the files it needs, summarizes the architecture, and identifies the checks it should run before making changes. ## Step 3: run your first reviewable change Ask for one small, verifiable change: ```text > add structured logging to the app entry point and replace the existing console calls ``` Droid will: 1. Inspect the current implementation. 2. Propose a plan when the task needs one. 3. Show the exact diff. 4. Wait for approval before editing. 5. Run the relevant validators when you ask it to finish the task. Review the diff and run the relevant tests before accepting the change. This propose-and-approve loop is how you keep control as you delegate more work. ## Step 4: pick a goal to go deeper Use Specification Mode so Droid writes a plan before it starts a multi-step implementation. Review pull requests and local diffs for correctness, security, and edge cases. Move repeatable workflows into Droid Exec for scripts, CI, scheduled jobs, and pull request checks. Use Factory Missions when a task needs planning, delegation, validation, and checkpoints. ## Step 5: handle version control Droid makes Git operations conversational and intelligent: ```text > review my uncommitted changes and suggest improvements before I commit ``` ```text > create a well-structured commit with a descriptive message following our team conventions ``` ## Essential controls Here are the key interactions you'll use daily: | Action | What it does | How to use | | ----------------- | ----------------------------------------------------- | -------------------------------------------- | | Send message | Submit a task or question | Type and press Enter | | Multi-line input | Write longer prompts | for new lines | | Approve changes | Accept proposed modifications | Accept change in the TUI | | Reject changes | Decline proposed modifications | Reject change in the TUI | | Switch modes | Toggle between modes | | | Bash mode | Run shell commands directly without AI interpretation | Press ! on an empty input; Esc to return | | Transcript view | Toggle detailed transcript with full message details | | | Mission Control | Toggle Mission Control overlay (orchestrator sessions)| | | Close overlay | Dismiss the active overlay or menu | Escape | | Scroll transcript | Navigate through previous turns | / | | View shortcuts | Open the keyboard shortcuts pane (Esc to close) | Press ? | | Exit session | Leave droid | or type `exit` | ### Useful slash commands Quick shortcuts to common actions: | Command | What it does | | :------ | :----------- | | `/review` | Start the code review workflow ([learn more](/automations/code-review)). | | `/settings` | Configure Droid behavior, models, output style, and preferences. | | `/model` | Switch between AI models mid-session. | | `/sessions` | List and resume previous sessions. | | `/fork` | Copy the current session into a new session. You stay in the original; the receipt prints a `droid --resume ` command to open the fork elsewhere. | | `/compress` | Compress the current session to free up context. | | `/missions` | Open the Missions menu to launch multi-agent projects. | | `/droids` | Manage custom Droids (specialized subagents). | | `/skills` | Manage prompt-based skills (reusable procedures). | | `/hooks` | Manage tool execution hooks for lifecycle automation. | | `/plugins` | Manage plugins and marketplaces. | | `/mcp` | Manage Model Context Protocol servers. | | `/account` | Open your Factory account settings in the browser. | | `/billing` | View and manage your billing settings. | | `/help` | See all available commands. | [Learn how to create custom slash commands →](/harness/custom-slash-commands) Turns a repository into browsable architecture and setup documentation. Starts `/review` for uncommitted changes, commits, and branch diffs. Scores whether a repository is ready for larger autonomous work. Teaches Droid repository-specific conventions before it edits code. # Settings Configure how droid behaves and integrates with your workflow. This is the reference for `settings.json`, the personal CLI configuration file. It covers the settings you control as an individual developer. Settings that are typically managed by an organization (model policy, network restrictions, autonomy ceilings, and similar hard controls) are listed in a [clearly labeled section](#enterprise-and-org-level-settings) below and documented in full in [Enterprise Controls & Managed Settings](/enterprise/hierarchical-settings-and-org-control). For personal session defaults managed in the Factory App, see [App settings](/factory-app/settings). ## Accessing settings To configure droid settings: 1. Run `droid` 2. Enter `/settings` 3. Adjust your preferences interactively Changes take effect immediately and are saved to your settings file. ## Where settings live | OS | Location | | ------------- | -------------------------------------- | | macOS / Linux | `~/.factory/settings.json` | | Windows | `%USERPROFILE%\.factory\settings.json` | If the file doesn't exist, it's created with defaults the first time you run **droid**. ### Local overrides You can create a `settings.local.json` alongside `settings.json` in any `.factory/` folder: - `~/.factory/settings.local.json` (user-level) - `/.factory/settings.local.json` (project-level) Local overrides merge on top of the corresponding `settings.json` at the same level and follow the same hierarchy precedence. Add `settings.local.json` to `.gitignore` if you want to keep machine-specific preferences out of version control. ## Legacy Droid YAML configuration `.droid.yaml` was an older project configuration surface. Use the current `.factory/` files instead: - Use `settings.json` and `settings.local.json` for Droid preferences and local overrides. - Use [AGENTS.md](/harness/agents-md) for repository instructions, conventions, and validation commands. - Use [MCP servers](/harness/mcp), [hooks](/harness/hooks), and [skills](/harness/skills) for integrations, automation, and reusable workflows. ## Available settings | Setting | Options | Default | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- | -------------------------------------------------------------------------- | | `model` | Any [available model ID](/models) | Product default | The default AI model used by droid | | `reasoningEffort` | Model-dependent: `none`, `dynamic`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` (see [per-model options](/models)) | Model-dependent default | Controls how much structured thinking the model performs. | | `legacyModelOverrides` | Array of model IDs | `[]` | Legacy models you chose to keep. Droid neither warns about nor upgrades them. Read from user settings only. See [Legacy models](/droid-cli/cli-reference#legacy-models). | | `outputStyle` | `default`, `concise`, or a [custom style](/droid-cli/output-styles) selected in `/settings` | `default` | Controls how Droid structures and writes responses in CLI, `droid exec`, Automations, Missions, and Factory App sessions. | | `sessionDefaultSettings.interactionMode` | `auto`, `spec` | `auto` | Sets whether new sessions start in Auto or Spec Mode. | | `sessionDefaultSettings.autonomyLevel` | `off`, `low`, `medium`, `high` | `off` | Sets the default [Autonomy Level](/autonomy-and-safety/auto-run) for new sessions. | | `cloudSessionSync` | `true`, `false` | `true` | Mirror CLI sessions to Factory web. | | `diffMode` | `github`, `unified` | `github` | Choose between split GitHub-style diffs and a single-column view. | | `completionSound` | `off`, `bell`, `fx-ok01`, `fx-ack01`, or custom file path | `fx-ok01` | Audio cue when a response finishes. | | `awaitingInputSound` | `off`, `bell`, `fx-ok01`, `fx-ack01`, or custom file path | `fx-ack01` | Audio cue when droid is waiting for user input. | | `soundFocusMode` | `always`, `focused`, `unfocused` | `always` | When to play sound notifications. | | `permissionRules` | Versioned object with a `rules` array | No custom rules | Recommended command policy: `allow`, `ask`, or `block`. See [Permission rules](/autonomy-and-safety/permission-rules). | | `commandAllowlist` | Array of commands | Safe defaults provided | **Deprecated.** Still respected for backward compatibility; use an `allow` rule for new policy. | | `commandDenylist` | Array of commands | Restrictive defaults provided | **Deprecated.** Still respected for backward compatibility; use an `ask` rule for new policy. | | `commandBlocklist` | Array of commands | `[]` (none) | **Deprecated.** Still respected for backward compatibility; use a `block` rule for new policy. | | `includeCoAuthoredByDroid` | `true`, `false` | `true` | Automatically append the Droid co-author trailer to commits. | | `enableDroidShield` | `true`, `false` | `true` | Enable secret scanning and git guardrails. | | `hooks.hooksDisabled` | `true`, `false` | `false` | Turn hooks off without removing them; the level that sets it decides which hooks stop. See [Hooks](#hooks). | | `disabledSkills` | Array of skill names | `[]` | Disable discovered skills without deleting their files. | | `ideAutoConnect` | `true`, `false` | `false` | Auto-connect to IDE from external terminals. | | `showThinkingInMainView` | `true`, `false` | `false` | Display AI thinking/reasoning blocks in the main chat view. | | `streamAssistantResponses` | `true`, `false` | `false` | Display Droid's response text and visible thinking progressively as they arrive in the terminal. | | `customModels` | Array of model configs | `[]` | Custom model configurations for BYOK. See [BYOK docs](/model-independence/byok). | | `vimMode` | `true`, `false` | `false` | Use vim keybindings (INSERT and NORMAL modes) in the chat input. Toggle with `/vim`; an explicit choice is saved. | | `blockOnMcpLoad` | `true`, `false` | `false` | Wait for MCP servers to finish loading before starting an agent turn. | ### Model Set `model` to a [model ID from Factory-Managed Inference](/models). For custom models, see [Custom Models (BYOK)](/model-independence/byok). ### Reasoning effort `reasoningEffort` adjusts how much structured thinking the model performs before replying. The available levels and the default are **set by each model**, so the [Available Models](/models) table is the source of truth for what a given model accepts. Across the catalog they range from least to most deliberation: {/* sweep-allow: term-bullets */} - **`off` / `none`**: no structured reasoning (fastest). - **`dynamic`**: use the model's dynamic reasoning behavior. - **`minimal`**, **`low`**, **`medium`**, **`high`**: progressively more deliberation. - **`xhigh`**, **`max`**: the deepest reasoning, where a model offers it. Each model accepts only the subset shown in its [Available Models](/models) row, and its default sits within that subset (for example, Claude Opus 4.8 defaults to `high`, while Claude Sonnet 4.5 defaults to `off`). ### Output style Choose **Default**, **Concise**, or a custom style from `/settings`. Select custom styles in the TUI instead of editing their saved values by hand. Droid discovers them from user, project, and folder `.factory/output-styles/` directories and enabled plugins. See [Output styles](/droid-cli/output-styles) for the file format, scope, and session behavior. ### Autonomy level Use `sessionDefaultSettings.interactionMode` to choose whether new sessions start in Auto or Spec Mode, and `sessionDefaultSettings.autonomyLevel` to set the default [Autonomy Level](/autonomy-and-safety/auto-run). `off` keeps manual approvals; `low`, `medium`, and `high` pre-authorize work at or below that risk level. `sessionDefaultSettings.autonomyMode` is deprecated and retained for older configurations. ### Diff mode Control how droid displays code changes: - **`github`**: Side-by-side, higher fidelity render (recommended). - **`unified`**: Traditional single-column diff format. ### Cloud session sync When this switch is on, every CLI session is mirrored to Factory web so you can revisit conversations in the browser: - **`true`**: Sync sessions to the web app. - **`false`**: Keep sessions local only. If your organization sets **Session Contents Sync**, its choice applies and this setting is locked. When your organization turns it off, session contents stay on your computer whatever this setting says. See [Session contents sync](/enterprise/hierarchical-settings-and-org-control#session-contents-sync). ### Sound notifications Configure audio feedback for droid events: **Completion sound** (`completionSound`) - plays when a response finishes: Built-in completion sound (default) - soft success bloop. Alternative built-in sound effect - tactile ripple feedback. Use the system terminal bell. No sound notifications. Provide a file path to your own sound file (e.g., `"/path/to/sound.wav"`). **Awaiting input sound** (`awaitingInputSound`) - plays when droid is waiting for user input. Same options as completion sound, defaults to `fx-ack01`. **Sound focus mode** (`soundFocusMode`) - controls when sounds play: Play sounds regardless of window focus (default). Only play sounds when the terminal is focused. Only play sounds when the terminal is not focused. Access sound settings via `/settings` or → **Settings** in the TUI. ### Hooks `hooksDisabled` turns hooks off without removing their configuration. It belongs inside the `hooks` key of `settings.json` (or at the top level of `hooks.json`). You can also toggle it from the `/hooks` menu or `/settings`. ```json title="~/.factory/settings.json" { "hooks": { "hooksDisabled": true } } ``` - **`false`** (default): this level does not turn hooks off. A higher-precedence level, an org `hooksDisabled: true`, or the org's `allowManagedHooksOnly` can still keep hooks from running. - **`true`** at the deciding member level: user and project hooks, and the hooks of plugins the org did not enable, do not run. Org-managed hooks and the hooks of org-enabled plugins still run unless the org sets `hooksDisabled: true`. When several member levels set `hooksDisabled`, the highest-precedence one decides: a `--settings` file, then folder, project, and user settings. An org `hooksDisabled: true` overrides them all. A repository's project settings therefore outrank your user setting. See [Disable hooks](/harness/hooks#disable-hooks). `showHookOutput`, also inside the `hooks` key, controls whether the CLI shows hook rows in the session transcript. It defaults to `true`; a hook that returns `suppressOutput: true` still hides its successful output from the main chat view. With `showHookOutput` set to `false`, the CLI still shows a notice when a hook fails without blocking. ### Disabled skills `disabledSkills` is a ledger of skill names that Droid should not invoke. Configure it from the `/skills` manager or edit the user or project settings file directly: ```json { "disabledSkills": ["deploy-production", "summarize-diff"] } ``` User and project arrays are combined, so a skill disabled at either level remains disabled. Stale entries are safe: a name has no effect until Droid discovers a matching skill. See [Skills](/harness/skills#manage-skills) for the manager, source precedence, and `SKILL.md` controls. ### IDE auto-connect The `ideAutoConnect` setting controls whether droid automatically connects to your IDE when running from external terminals (outside the IDE's built-in terminal): - **`false`**: Only auto-connect when running inside IDE terminal (default) - **`true`**: Auto-connect to IDE from any terminal ## Permission rules Use `permissionRules` to allow, require approval for, or block shell commands. Rules match exact, ordered argument tokens and include examples that verify their behavior. They replace the deprecated command lists, which remain respected for backward compatibility. ```json { "permissionRules": { "version": 1, "rules": [ { "id": "user/git-push", "decision": "ask", "match": { "prefix": ["git", "push"] }, "tests": { "match": ["git push origin main"], "noMatch": ["git status"] } } ] } } ``` Run `droid rules check` after editing settings. See [Permission rules](/autonomy-and-safety/permission-rules) for availability, matching, source precedence, and migration. For the organization editor, see [Manage permission rules](/enterprise/hierarchical-settings-and-org-control#manage-permission-rules). ## Command allowlist, denylist & blocklist These settings are **deprecated, not removed**. Existing lists remain respected for backward compatibility; immediate migration is not required. Use `permissionRules` for new policies. Review [coexistence and migration](/autonomy-and-safety/permission-rules#migrate-legacy-command-lists) before replacing existing entries. Legacy command patterns that can run without command approval unless a restriction takes precedence. The replacement decision is `allow`. Legacy command patterns that require confirmation in permission-checked execution. A matching command can run after approval. The replacement decision is `ask`, not `block`. Legacy command patterns that produce a hard block. An effective block cannot be approved, even with `--skip-permissions-unsafe`. The replacement decision is `block`. When using legacy lists alone, a block takes precedence over a deny, which takes precedence over an allow. Commands with no match fall back to normal approval handling. With rules enabled, a native rule can replace a custom legacy restriction from the same settings source; restrictions from other sources still participate. ### Legacy configuration example ```json { "commandAllowlist": ["ls", "pwd", "dir"], "commandDenylist": ["rm -rf /", "mkfs", "shutdown"], "commandBlocklist": ["shutdown", "mkfs", "curl"] } ``` This remains a supported compatibility configuration. For new configuration, use tested [permission rules](/autonomy-and-safety/permission-rules#create-a-rule) instead. ## Session defaults Defaults applied when a new session starts. See also `sessionDefaultSettings.interactionMode` and `sessionDefaultSettings.autonomyLevel` in the table above. | Setting | Type | Options | Default | Description | | ------------------------------------------------ | ------ | ---------------------------------------- | -------------- | ---------------------------------------------------------- | | `sessionDefaultSettings.specModeModel` | string | Any [available model ID](/models) | Inherits model | Override the model used when sessions start in Spec Mode. | | `sessionDefaultSettings.specModeReasoningEffort` | string | Model-dependent (see [/models](/models)) | Model default | Reasoning effort applied to the spec model. | ## Display and UI Tune how droid renders content in the terminal. How tool results are rendered in the transcript. Options: `expanded`, `compact`. Show the live token usage indicator at the bottom of the input. Control how the todo list is shown in the terminal UI. Animate the droid logo on startup. Options: `once`, `always`, `off`. Color theme used by the TUI. Accepts a theme ID (see `/themes`). Force droid's theme to override the terminal's color scheme. Enable Nerd Font glyphs in the UI (requires a Nerd Font in your terminal). ### Response streaming Turn on **Stream responses as they arrive** in the **Preferences** tab of `/settings` to display Droid's response text progressively instead of waiting for each block to finish. The `streamAssistantResponses` setting defaults to `false`; leaving it off preserves the block-by-block display. Streaming does not enable thinking visibility. To stream thinking blocks in the main chat view too, turn on **Show thinking in chat view** (`showThinkingInMainView`). Both settings are top-level keys in `settings.json`: ```json { "streamAssistantResponses": true, "showThinkingInMainView": true } ``` These are terminal display preferences, not controls for how much reasoning the model performs. Use [Reasoning effort](#reasoning-effort) to adjust that behavior. Factory's web and desktop apps already stream responses and are not affected by `streamAssistantResponses`. ## Additional sound and notification settings Extends the [Sound notifications](#sound-notifications) section with toggles for the bell, per-event focus modes, and subagent activity. | Setting | Type | Options | Default | Description | | -------------------------------- | ------- | -------------------------------------- | --------- | -------------------------------------------------------------------- | | `subagentSounds` | string | `on`, `off` | `off` | Play sounds for subagent lifecycle events (start, complete, error). | | `completionSoundFocusMode` | string | `always`, `focused`, `unfocused` | Inherits `soundFocusMode` | Override focus behavior for completion sounds. | | `awaitingInputSoundFocusMode` | string | `always`, `focused`, `unfocused` | Inherits `soundFocusMode` | Override focus behavior for awaiting-input sounds. | ## Mission settings Configure [Missions](/missions/overview), multi-agent orchestration runs. The six mission model and reasoning fields can also be set as organization defaults in [Enterprise Controls](/enterprise/hierarchical-settings-and-org-control#mission-defaults). They resolve independently with [session-default precedence](/enterprise/hierarchical-settings-and-org-control#how-precedence-works-hard-controls-vs-session-defaults), so more-local settings can override org defaults within the organization's model policy. The `skipScrutiny` and `skipUserTesting` toggles remain user-managed and are not accepted in org-managed settings. Default model used by mission worker subagents. Accepts any [available model ID](/models). Reasoning effort for mission workers. Options are model-dependent (see [/models](/models)). Model used by mission validators (scrutiny / user-testing workers). Accepts any [available model ID](/models). Reasoning effort for validation workers. Options are model-dependent (see [/models](/models)). Skip scrutiny validation milestones during missions. Skip user-testing validation milestones during missions. Model used by the mission orchestrator. Accepts any [available model ID](/models). Reasoning effort for the mission orchestrator. Options are model-dependent (see [/models](/models)). Prevent the OS from sleeping while a mission is running. ## Subagent settings Configure the autonomy and models used by subagents spawned by the Task tool. These appear in the **Subagents** tab of `/settings`. | Setting | Type | Options | Default | Description | | ----------------------- | ------ | ----------------------------------------- | --------- | ------------------------------------------------------------------------------------ | | `subagentAutonomyLevel` | string | `inherit`, `off`, `low`, `medium`, `high` | `inherit` | [Autonomy Level](/autonomy-and-safety/auto-run) applied to subagents spawned by the Task tool. | ### Subagent autonomy level `subagentAutonomyLevel` controls how much subagents can do without approval: {/* sweep-allow: term-bullets */} - **`inherit`**: Subagents use the parent session's autonomy level (default). - **`off`**: Subagents require manual approval for every action. - **`low`**, **`medium`**, **`high`**: Pre-authorize subagent work at or below that risk level. An explicit level is still clamped to the org-managed `maxAutonomyLevel`, so it can never exceed the enterprise cap. Mission workers do not use this setting. ### Subagent model settings Subagents are routed by a complexity tier (`light`, `medium`, `heavy`). Each tier can pin its own model and reasoning effort under `subagentModelSettings`. | Setting | Type | Options | Default | Description | | --------------------------------------------- | ------ | ---------------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------- | | `subagentModelSettings.lightModel` | string | Any [available model ID](/models) or `inherit` | `inherit` | Model for light-complexity subagents (e.g. the built-in `explorer`). | | `subagentModelSettings.lightReasoningEffort` | string | Model-dependent: `none`, `dynamic`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` | Parent/model default | Reasoning effort for light-complexity subagents. | | `subagentModelSettings.mediumModel` | string | Any [available model ID](/models) or `inherit` | `inherit` | Model for medium-complexity subagents (e.g. the built-in `worker`). | | `subagentModelSettings.mediumReasoningEffort` | string | Model-dependent: `none`, `dynamic`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` | Parent/model default | Reasoning effort for medium-complexity subagents. | | `subagentModelSettings.heavyModel` | string | Any [available model ID](/models) or `inherit` | `inherit` | Model for heavy-complexity subagents. | | `subagentModelSettings.heavyReasoningEffort` | string | Model-dependent: `none`, `dynamic`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` | Parent/model default | Reasoning effort for heavy-complexity subagents. | How the tiers are chosen: - The built-in `worker` subagent runs at `medium` complexity and `explorer` at `light`. Custom droids and the Task tool can request a specific tier. - **`inherit`** (the default) means the subagent uses the spawning session's active model and reasoning effort. Upgrading the parent session's model does not retroactively change a tier pinned to a specific model. - A custom droid with an explicit `model` in its configuration uses that model directly and bypasses complexity routing. - Without an explicit reasoning effort, a routed tier preserves the parent's active effort when it uses the same model; if it switches models, it uses the routed model's default. Explicit efforts are clamped to what the selected model supports. ## Context and compaction Controls when and how droid compacts the conversation to stay within the model's context window. Token threshold that triggers automatic compaction of the current session. Per-model overrides for `compactionTokenLimit`, as a `{ "": number }` map. Which model performs compaction: `same` uses the current session model, or specify a model ID. Per-model fallback routing when a selected model is unavailable, as a `{ "": "" }` map. ## Spec mode settings Controls the persistent spec store created by Spec Mode. | Setting | Type | Options | Default | Description | | ----------------- | ------- | ------------------------ | ----------------------------- | -------------------------------------------------------------------------- | | `specSaveDir` | string | Directory path | `~/.factory/specs` | Directory where saved specs are written. Supports `~` expansion. | ## Infrastructure System-level settings for status line, worktrees, and request timeouts. Custom status line configuration. Accepts `{ "command": string, "padding"?: number, "maxRows"?: number }`. The `command` is executed and its stdout rendered above the input. Configure interactively with `/statusline`. Default parent directory for git worktrees created with `--worktree` / `-w`. Timeout in milliseconds for individual LLM requests before they are aborted. Timeout in milliseconds for subagent inactivity before Droid treats the worker as stalled. Allow this machine to be used for remote Droid Computer access. ## Enterprise and org-level settings **These keys are org-managed, not personal preferences.** They are typically configured by an organization Manager or Owner and pushed to members through the Factory App or a managed `settings.json`. They appear here so the `settings.json` schema is complete in one place, but individual users should not expect to change them. See [Enterprise Controls & Managed Settings](/enterprise/hierarchical-settings-and-org-control) for hierarchy, merge semantics, and admin enforcement details. Usage alert preferences are Factory App controls; individual users control their own threshold alerts. | Setting | Type | Options | Default | Description | | ------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `maxAutonomyLevel` | string | `off`, `low`, `medium`, `high` | `high` | **Enterprise.** Maximum [Autonomy Level](/autonomy-and-safety/auto-run) any session may use. Higher levels selected by users are clamped. | | `webSearchDisabled` | boolean | `true`, `false` | `false` | **Org-only.** Set `true` to remove built-in Web Search from the CLI. User, project, and folder values are ignored; Web Fetch is unchanged. See [managed tool controls](/enterprise/hierarchical-settings-and-org-control#autonomy-safety-and-commands). | | `subagentAutonomyLevel` | string | `low`, `medium`, `high`, `inherit` | `inherit` | **Enterprise.** Default autonomy ceiling for subagent workers. | | `modelPolicy` | object | `{ "allowedModelIds"?: string[], "blockedModelIds"?: string[], "allowCustomModels"?: boolean, "allowedBaseUrls"?: string[] }` | unset | **Enterprise.** Restrict which models members can select, control whether custom models are permitted, and allowlist base URLs for custom model providers. | | `mcpPolicy` | object | `{ "enabled"?: boolean, "allowlist"?: string[] }` | unset | **Enterprise.** Control whether MCP servers can run and which servers are permitted. See [MCP](/harness/mcp). | | `mcpAutonomyOverrides` | object | Per-server and per-tool autonomy map | unset | **Enterprise.** Set default autonomy levels for specific MCP servers or tools. | | `mcpAutonomyUrlOverrides` | array | URL pattern autonomy rules | unset | **Enterprise.** Set autonomy defaults for MCP tools that target matching URLs. | | `missionPolicy` | object | `{ "restrictedAccess"?: boolean, "allowedUserIds"?: string[] }` | unset | **Enterprise.** Restrict who can launch [Missions](/missions/overview). | | `networkPolicy` | object | `{ "allowedIps": string[] }` | unset | **Enterprise.** Restrict outbound network access from droid sessions to the specified IPs or CIDR ranges in `allowedIps`. | | `sandbox` | object | `{ "enabled"?: boolean, "mode"?: string, "filesystem"?: object, "network"?: object }` | unset | Sandbox configuration controlling filesystem and network isolation for tool execution. See [Sandbox](/autonomy-and-safety/sandbox). | | `restrictMemberVisibility` | boolean | `true`, `false` | `false` | **Org-level.** Hide other org members from non-admin users. | | `restrictApiKeyCreationToManagers` | boolean | `true`, `false` | `false` | **Org-level.** Only org managers may create API keys. | | `apiKeyMaxLifetimeDays` | number | `1`–`365` | unset | **Org-level.** Maximum lifetime, in days, of new and rotated Factory API keys. See [API key lifetime limit](/enterprise/hierarchical-settings-and-org-control#api-key-lifetime-limit). | | `sessionRetentionDays` | number | `14`–`365` | Org default | **Org-level.** How long synced session history is retained before deletion. | | `wikiCloudSync` | boolean | `true`, `false` | `true` | **Org-level.** Sync generated [Wiki](/automations/wiki/overview) content to Factory cloud. | | `voiceDictationEnabled` | boolean | `true`, `false` | Org default | **Org-level.** Control whether voice dictation is available as an input method to organization members. | | `disableWeeklyUsageSummary` | boolean | `true`, `false` | `false` (summary on) | **Enterprise/org-level.** Opt out of the weekly usage-cap summary email sent to Managers and Owners for users and active service accounts at or above 80% of their monthly credit cap. Set `true` to suppress. | | `managedComputersEnabled` | boolean | `true`, `false` | `false` | **Enterprise.** Enable Factory-managed remote computers for the org. | | `managedComputersAllowedEmails` | array | Email allowlist | unset | **Enterprise.** Limit Factory-managed Droid Computers to specific members. | | `byomComputersEnabled` | boolean | `true`, `false` | `false` | **Enterprise.** Allow members to register their own computers for Remote Control via `droid computer register`. | | `byomComputersAllowedEmails` | array | Email allowlist | unset | **Enterprise.** Limit Remote Control registration to specific members. | | `factoryRouterGuidance` | string | Routing guidance text | unset | **Enterprise.** Organization-wide guidance for Factory Router model selection. | | `factoryRouterRules` | array | Routing rule objects | unset | **Enterprise.** Conditional Factory Router guidance rules. | | `allowManagedHooksOnly` | boolean | `true`, `false` | `false` | **Enterprise.** Load only org-managed hooks and the hooks of org-enabled plugins. User, project, and other plugin hooks are ignored. | | `disableAutoUpdate` | boolean | `true`, `false` | `false` | **Enterprise.** Disable automatic Droid CLI updates where managed deployment controls updates. | ## Factory App usage alert preferences The following preference is stored in each user's Factory App profile. It cannot be configured in `settings.json`. | Preference | Type | Options | Default | Description | | ------------------------- | ------- | --------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `disableUsageLimitAlerts` | boolean | `true`, `false` | `false` (alerts on) | Opt out of the emails sent when you reach 80% and 100% of your monthly credit cap. Set `true` to stop these alerts. | ## Example configuration ```json { "model": "claude-opus-5-5", "reasoningEffort": "medium", "outputStyle": "concise", "diffMode": "github", "cloudSessionSync": true, "completionSound": "fx-ok01", "awaitingInputSound": "fx-ack01", "soundFocusMode": "always" } ``` Editor-specific setup. Command flags and options. Customize how Droid structures and writes interactive responses. Add custom models and API keys. # Image generation Generate and edit images from a Droid session, and choose the image model that fits the job. Droid can create and edit images in the middle of a session. Ask for a logo, an icon, a UI mockup, an architecture diagram, or a change to an image you already have, and Droid calls its built-in `GenerateImage` tool. The image appears inline in the conversation and is saved to disk so you can use it in your project. There is nothing to install. Image generation is on by default, and image models are billed like any other model usage. ## Generate an image Describe what you want in plain language. Droid turns your request into a detailed prompt for the image model, so you do not need to write one yourself. ```text > Create a 1024x1024 app icon for a weather CLI: a minimal cloud with a lightning bolt, flat style, navy and amber ``` Droid saves each result under `~/.factory/generated-images/` with a short, descriptive file name, and reports the path. Ask Droid to copy the file into your repository if you want to keep it with your code. The image model only sees the prompt Droid writes and any reference images Droid passes. It does not see your conversation or your codebase. If details matter (exact copy, brand colors, dimensions, style), say them explicitly so Droid includes them in the prompt. ## Edit an existing image To change an image instead of starting over, refer to it in your request. Droid passes the image to the model as a reference and describes only the change. ```text > Make the background of that icon transparent and the bolt slightly thicker ``` You can edit: - **Images Droid generated** in the current or an earlier session, from `~/.factory/generated-images/`. - **Images you attached** to the session, for example by pasting or dragging a screenshot into the CLI. Each call accepts up to 4 reference images in PNG or JPEG format, up to 5 MB each. Droid re-encodes and compresses them before upload. ## Choose a model Droid supports three image models. All of them generate and edit images, accept reference images, and render legible text. They differ in speed, editing precision, and how much they reason about the content. | Model | Provider | Best for | Trade-off | | :---- | :------- | :------- | :-------- | | **GPT Image 2.5 Sunburst** (default) | OpenAI | Polished final assets and multi-step edit chains where every revision must stay clean | Slowest of the three | | **GPT Image 2.5 Flare** | OpenAI | Fast drafts, quick iterations, and high-volume work | Slightly lower peak quality than Sunburst | | **Gemini 3 Pro Image** (Nano Banana Pro) | Google | Infographics, explainer diagrams, multilingual text, and compositions built from several references | Different style and content filters from the OpenAI models | ### GPT Image 2.5 Sunburst OpenAI's full-size image model, released in September 2026, and Droid's default. OpenAI positions it for premium work that needs tight control across a chain of edits. - **Precise, scoped edits.** Ask for one change (a product, a background, a line of copy) and the subject, composition, and surrounding layout stay put. - **Stable multi-turn editing.** Earlier edits survive later ones, so the fourth revision is as clean as the first. - **Reference fidelity.** Faces, products, and brand elements carry into new scenes and styles with their distinctive details intact. - **Text and layout.** OpenAI calls out better infographic accuracy and layout in 2.5, and it handles posters, packaging, and labels well. - **Top of the leaderboards at launch.** Sunburst debuted first on LMArena's text-to-image and image-edit leaderboards, ahead of every other model (scores were preliminary at launch). Pick Sunburst when the image is a deliverable: a landing page hero, marketing creative, a product shot, or anything you will refine over several rounds. ### GPT Image 2.5 Flare The small, fast variant of GPT Image 2.5. OpenAI measures it at up to half the latency of GPT Image 2, at comparable quality, and it ranked second only to Sunburst on LMArena at launch. - **Speed.** Best for quick drafts, placeholder art, exploring several directions, or generating many assets in one session. - **Same editing model.** It shares the 2.5 improvements in scoped edits and reference fidelity, with a little less polish than Sunburst. OpenAI's own advice is a good rule: if speed matters and Flare already meets your quality bar, use it. If quality is the constraint, start with Sunburst, get the result you want, then check whether Flare can match it faster. ### Gemini 3 Pro Image Google DeepMind's image model, also known as Nano Banana Pro. It is built on Gemini 3 Pro and uses that model's reasoning and world knowledge to plan an image before rendering it. - **Information-dense visuals.** Strong at infographics, explainers, step-by-step diagrams, and turning notes or outlines into a visual, because it reasons about what the content should say. - **Text in many languages.** Google describes it as its best model for legible in-image text, from short taglines to full paragraphs, including translating and localizing text in an existing image. - **Multi-reference composition.** Good at blending several reference images into one scene while keeping people, products, and branding consistent. - **Studio-style controls.** Handles edits to lighting, camera angle, focus, and aspect ratio (for example, day to night, or reframing to 1:1 without moving the subject). Pick Gemini 3 Pro Image for diagrams and explainers, localized or text-heavy mockups, and composites built from several references. It is also a useful second opinion: because it comes from a different provider, it can succeed on a prompt that the OpenAI models refuse. Every model can still misplace text, drift on recurring characters across separate generations, or change details you meant to keep. Quote exact copy in your request, reuse a reference image instead of re-describing a character, and check the result before you ship it. ## Set your image model Open `/settings` and change **Image generation model** on the **Session** tab. Selecting the row cycles through the models your organization allows, plus **Factory default**. You can also set it in `settings.json`: ```json title="~/.factory/settings.json" { "imageGenerationModel": "gpt-image-2.5-flare" } ``` | Model | ID | | :---- | :- | | GPT Image 2.5 Sunburst | `gpt-image-2.5-sunburst` | | GPT Image 2.5 Flare | `gpt-image-2.5-flare` | | Gemini 3 Pro Image | `gemini-3-pro-image-preview` | Image models do not appear in the main model picker. They are only used through the `GenerateImage` tool, so your session model and your image model are independent. ### Automatic fallback Droid tries your selected model first. If the provider refuses the prompt or the request fails (for example, an outage or rate limit), Droid retries with the next allowed model in this order: GPT Image 2.5 Sunburst, GPT Image 2.5 Flare, then Gemini 3 Pro Image. The two GPT Image 2.5 models share content filters, so a refusal from one usually moves straight on to Gemini. ## Organization controls Admins control image generation in Enterprise Controls or org-managed settings: Turns image generation on or off for the whole organization. When `false`, Droid stops offering the `GenerateImage` tool and the server rejects image-model requests. Allowlist of image model IDs. Users can only select, and Droid can only fall back to, models on this list. An empty list disables image generation. Default image model for the organization. Users can override it with their own setting. Image models are not covered by `modelPolicy` allow and block lists, so use these settings instead. `imageGenerationEnabled` and `imageGenerationAllowedModelIds` are hard controls that users cannot override. `imageGenerationModel` is a default that users can change. See [Feature controls](/enterprise/hierarchical-settings-and-org-control#feature-controls) for the full reference. Configure the CLI, including your session and image models. See every model available in Droid. # Output styles Control how Droid structures and writes responses across the CLI, droid exec, Missions, and the Factory App. Output styles add response-writing instructions to every Droid session whose responses you read. Choose a built-in style or create a Markdown file for a personal, project, or shared team style. ## Choose an output style 1. Start an interactive session with `droid`. 2. Enter `/settings`. 3. Select **Output style**. 4. Choose a built-in or custom style. Droid includes two built-in styles: Use Droid's standard response style. Return short, direct responses without unnecessary detail. The picker shows where each custom style came from, such as a user, project, or plugin. Your selection is saved as the `outputStyle` setting in `~/.factory/settings.json`, so `droid exec`, Automations, Missions, and the Factory App use the same style. ## Create a custom style Create an `output-styles` directory at the scope where you want the style to be available: | Scope | Location | | :---- | :------- | | User | `~/.factory/output-styles/.md` | | Project | `/.factory/output-styles/.md` | | Folder | `//.factory/output-styles/.md` | | Plugin | `/output-styles/.md` | Droid loads direct `.md` children of each `output-styles` directory. Nested files and other file types are ignored. Each file contains optional YAML frontmatter followed by the instructions Droid should apply: ```markdown title="~/.factory/output-styles/review-notes.md" --- name: Review Notes description: Put findings before the summary --- Start with actionable findings, ordered by severity. Keep the summary to two sentences. ``` `name` appears in the picker and defaults to the filename without `.md`. `description` appears below the name in the picker. Keep the Markdown body focused on response presentation. Repository instructions, tool permissions, and user requests still apply. Droid uses the style content available when a session sends its first request. Start a new session to use edits to that style. Selecting a different style takes effect on the next request. ## Scope and precedence Output styles apply to interactive CLI sessions, `droid exec`, Automations, Missions, and Factory App and web sessions. Subagents and mission workers report to another agent rather than to you, so they always use Droid's standard style. Droid combines styles from the active settings hierarchy and enabled plugins. Higher-priority sources win when the same style is provided more than once. The built-in `Default` and `Concise` styles are reserved and cannot be replaced. When Droid asks you to trust a working folder, review its style files before accepting. Project and folder styles, including styles from project-scoped plugins, remain unavailable until the folder is trusted. `droid exec` cannot ask, so it uses them only in folders you have already trusted. ## Troubleshooting Confirm the style is a direct `.md` child of `output-styles/` with a non-empty body. Run `/diagnostics` to see the source path and validation error, including when a style exceeds the size limit. Diagnostics do not include the style's instruction body. Confirm the style still exists, passes validation, comes from a trusted folder, and belongs to an enabled plugin. Subagents and mission workers always use Droid's standard style. Droid keeps an unavailable selection but uses **Default** until the style becomes available again. Configure the saved output style and other Droid preferences. Package output styles with reusable Droid extensions. Review interactive commands and headless output formats. See how organization, folder, project, and user sources resolve. # Droid CLI Reference Complete reference for the Droid CLI, including commands and flags ## Installation **macOS/Linux:** `curl -fsSL https://app.factory.ai/cli | sh` **Homebrew:** `brew install --cask droid` **Windows:** `irm https://app.factory.ai/cli/windows | iex` **npm:** `npm install -g droid` The Droid CLI operates in two modes: - **Interactive (`droid`)** - Chat-first REPL with slash commands - **Non-interactive (`droid exec`)** - Single-shot execution for automation and scripting ### Installing a specific version Pin a version when upgrades must be reviewed and applied intentionally, such as in CI runners, provisioned development environments, or other reproducible systems. #### npm Specify an exact package version: ```bash npm install -g droid@0.174.0 ``` The binaries published through npm have auto-updates disabled at build time, so the installed version remains pinned. To upgrade, install the new version explicitly with npm. #### Built-in updater After installing Droid through the standalone installer, select a version with: ```bash droid update --version 0.174.0 ``` This command can also roll back to an older version. Use `droid update --check` to check for an available update without installing it. Standalone installations enable automatic updates by default. After selecting a version, follow the [auto-update guidance](#auto-updates) to keep it pinned. #### Direct binary download Release binaries and their SHA256 checksums use the following paths: ```text https://downloads.factory.ai/factory-cli/releases//// https://downloads.factory.ai/factory-cli/releases////.sha256 ``` - ``: `linux`, `darwin`, or `windows` - ``: `x64`, `arm64`, or `x64-baseline` - ``: `droid` on Linux and macOS, or `droid.exe` on Windows For example, download and verify the Linux x64 binary: ```bash VERSION=0.174.0 BASE_URL="https://downloads.factory.ai/factory-cli/releases/${VERSION}/linux/x64" curl -fsSLO "${BASE_URL}/droid" curl -fsSLO "${BASE_URL}/droid.sha256" echo "$(awk '{print $1}' droid.sha256) droid" | sha256sum --check chmod +x droid ``` Move the verified binary to a directory on `PATH`. The download URL layout is an implementation detail, so always pin a version and verify its checksum. ## Droid CLI commands | Command | Description | Example | | :----------------------------------- | :--------------------------------------------------------------------- | :--------------------------------------------- | | `droid` | Start interactive REPL | `droid` | | `droid "query"` | Start REPL with initial prompt | `droid "explain this project"` | | `droid --resume [sessionId]` | Resume a session (defaults to last modified). Alias: `-r` | `droid --resume` | | `droid --fork ` | Fork and resume a session in a new copy | `droid --fork session-abc123` | | `droid exec "query"` | Execute task without interactive mode | `droid exec "summarize src/auth"` | | `droid exec -f prompt.md` | Load prompt from file | `droid exec -f .factory/prompts/review.md` | | `cat file \| droid exec` | Process piped content | `git diff \| droid exec "draft release notes"` | | `droid exec -s "query"` | Resume existing session in exec mode | `droid exec -s session-123 "continue"` | | `droid exec --list-tools` | List available tools, then exit | `droid exec --list-tools` | | `droid search "query"` | Search across local sessions (messages, documents, tool results). Alias: `droid find` | `droid search "auth bug"` | | `droid rules check` | Validate permission rules and optionally preview command policy | `droid rules check --command 'git push origin main'` | | `droid loop ` | Create, list, pause, resume, or cancel a session's recurring prompts; Droid runs them as tools in a session ([details](#schedule-recurring-prompts)) | `droid loop --help` | | `droid work-item link` | Link the calling session to a Linear issue; Droid runs it as a tool in a session ([details](#link-a-session-to-a-work-item)) | `droid work-item link --help` | | `droid analytics effectiveness ` | Fetch usage for, and render, the Agent Effectiveness report ([details](#generate-an-agent-effectiveness-report)) | `droid analytics effectiveness usage --date-range last_30_days` | | `droid analytics readiness store` | Store a `/readiness-report` result; Droid runs it as a tool in a session ([details](#store-a-readiness-report)) | `droid analytics readiness store --help` | | `droid mcp add ` | Add an MCP server | `droid mcp add api https://api.example.com/mcp --type http` | | `droid mcp remove ` | Remove an MCP server | `droid mcp remove linear` | | `droid mcp auth` | Sign in to every MCP server that needs authentication, one at a time | `droid mcp auth` | | `droid plugin install ` | Install a plugin. Alias: `droid plugin i` | `droid plugin install droid-control@factory-plugins` | | `droid plugin uninstall ` | Uninstall a plugin. Alias: `droid plugin remove` | `droid plugin uninstall droid-control@factory-plugins` | | `droid plugin update ` | Update a plugin to the latest version | `droid plugin update droid-control@factory-plugins` | | `droid plugin list` | List installed plugins | `droid plugin list` | | `droid plugin marketplace` | Manage plugin marketplaces | `droid plugin marketplace` | | `droid computer register [name]` | Register this computer for Remote Control | `droid computer register laptop` | | `droid computer remove` | Remove this computer's Remote Control registration | `droid computer remove` | | `droid computer list` | List computers and Factory Environments as JSON; use `--human` for readable tables | `droid computer list --human` | | `droid computer service-accounts list` | List service accounts (Manager role or higher) | `droid computer service-accounts list` | | `droid computer ssh ` | SSH into a registered computer | `droid computer ssh laptop` | | `droid computer port-forward ` | Forward local ports to a computer over the relay | `droid computer port-forward laptop 8080:80` | | `droid daemon` | Run the Factory daemon server | `droid daemon` | | `droid daemon --remote-control` | Connect this computer through [Remote Control](/remote-control). Alias: `--remote-access` | `droid daemon --remote-control` | | `droid update` | Manually update the CLI to latest version | `droid update` | ## List computers and environments `droid computer list` lists your computers and the Factory Environments visible to your identity, including whether each Environment can launch. It is read-only and prints JSON by default. Use `--human` for readable tables. ```bash droid computer list droid computer list --human ``` To list another identity's inventory, first list the organization's service accounts, then select an active account by its ID or name. Both account discovery and account selection require the **Manager role or higher**. Replace the example values with an account returned by the first command: ```bash droid computer service-accounts list droid computer list --service-account-id sa_example droid computer list --service-account-name "deploy-bot" ``` | Flag | Behavior | | :--- | :------- | | `--service-account-id ` | List the selected service account's computers and Factory Environments instead of your own. | | `--service-account-name ` | Select the same inventory by account name. Supply either the ID or the name, not both. | | `--human` | Print readable output instead of JSON; nonempty lists appear as a computer table followed by a Factory Environments table. | The service-account list returns `{"ok": true, "data": {"serviceAccounts": [...]}}`. Each account has `id`, `name`, and `status`. Deleted accounts are omitted; inactive accounts remain visible, but only active accounts can be selected with the flags above or run automations. ### Read the human output In English, `--human` prints a computer table with `COMPUTER`, `STATUS`, `PROVIDER`, and `ID` columns and marks this machine with `(this machine)` when Droid can identify it. When there are no computers, it prints a message instead: how to register this machine for your own inventory, or `No computers registered for service account "".` for a selected account. When Environments are returned, a `Factory Environments:` section follows after a blank line. The table has `ENVIRONMENT`, `STATUS`, `SCOPE`, `LAUNCHABLE`, and `ID` columns, and `LAUNCHABLE` is `yes` or `no`. For example, with illustrative names and IDs: ```text COMPUTER STATUS PROVIDER ID laptop (this machine) active byom 3f2a9c1e-5b7d-4e8a-9c0f-1d2e3f4a5b6c dev-box active e2b 8b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e Factory Environments: ENVIRONMENT STATUS SCOPE LAUNCHABLE ID team-default ready organization yes 0c56098a-c40d-4a56-bdd2-8f58120dc456 my-sandbox building user no 6de596d4-1a67-4ebc-be46-61265c198698 ``` With `--service-account-id` or `--service-account-name`, the heading is `Factory Environments service account "" can launch:`. If the Environment lookup fails, one line replaces the Environments section, and the computers still list. The HTTP status appears when one is available: ```text Factory Environments could not be listed (HTTP : ). ``` Without an HTTP status, the line is `Factory Environments could not be listed ().` When the lookup succeeds with no Environments, the section is omitted. ### Read the JSON result A successful computer list returns `{"ok": true, "data": {...}}` with these fields: | Field | Meaning | | :---- | :------ | | `data.serviceAccount` | The selected account (`id`, `name`, `status`), or `null` for your own inventory. | | `data.computers` | Computer rows with `id`, `name`, `providerType`, `thisMachine`, and `status` when known. An unknown status appears as `unknown` in the human table. | | `data.environments` | A successful Environment lookup (`ok: true`, `items`) or a failed lookup (`ok: false`, `error`, and an HTTP `status` when available). | Each Environment item has `id`, `name`, `status`, `scope`, and `launchable`. Use an Environment with `launchable: true` when choosing an automation's `environmentName`. Account selection applies to both the computers and Environments in the result. An Environment lookup can fail while the computer list succeeds. Check `data.environments.ok` before reading `items`: `ok: false` means the lookup failed, **not** that no Environments exist. The top-level `ok` can still be `true`, and the command can exit successfully with the computer inventory intact. ### Migrate existing scripts and prompts `droid computer list` defaults to JSON. If a script expects the computer table, add `--human` and account for the Factory Environments section, or update the script to read `data.computers` and handle `data.environments` separately. Update tool names in prompts and automation instructions: | Previous tool | Current tool | | :------------ | :----------- | | `ListComputers` | `computer_list` (Script: `tools.computer.list`) | | `ListServiceAccounts` | `computer_service_accounts_list` (Script: `tools.computer.service_accounts_list`) | | `PickSlackChannels` | Removed. | ## Check permission rules Use `droid rules check` to validate [permission rules](/autonomy-and-safety/permission-rules), run their embedded matching examples, and preview a decision without executing a command. ```bash droid rules check droid rules check --command 'git push origin main' droid rules check --file rules.json --command 'npm publish' --json ``` | Option | Behavior | | :----- | :------- | | `--file ` | Check a standalone `{version, rules}` object or bare rule array. Does not load built-ins or other settings. A full `settings.json` wrapper is not accepted. | | `--command ` | Preview the policy decision for a non-empty command. Quote it so your shell passes it as one argument. | | `--json` | Print the report as one JSON object, including rule diagnostics and, when requested, decision and match details. | Without `--file`, the checker validates resolved settings. A command preview follows the active policy engine; validating rules does not enable enforcement on a client still using legacy policy. Exit code `0` means the check succeeded, even if the preview says `block`. Invalid rules or failed examples produce exit code `1`. Preview covers command policy only, not hooks, sandbox permissions, autonomy, or session approvals. The `commandAllowlist`, `commandDenylist`, and `commandBlocklist` settings are deprecated but remain respected for backward compatibility. Use `permissionRules` for new policy; see [migration guidance](/autonomy-and-safety/permission-rules#migrate-legacy-command-lists). ## Run loop, work item, and analytics commands `droid loop`, `droid work-item link`, and `droid analytics` are the command form of tools that Droid calls during a session. The `droid analytics effectiveness` commands and their tools share one schema: each flag is a field of the tool, spelled in kebab case on the command line, and the tool returns the command's `data`. For example, `droid analytics effectiveness usage --date-range last_30_days` is the `analytics_effectiveness_usage` tool with `dateRange: "last_30_days"`, which a Script calls as `tools.analytics.effectiveness_usage`. The `droid loop` commands, `droid work-item link`, and `droid analytics readiness store` run only as tools or in a Script. Their commands accept no input; they name the tool to call instead. Where a command runs decides what it does: | Where | Behavior | | :---- | :------- | | A Droid session | Droid calls the tool directly. If the session's shell runs one of these commands, it exits `1` with `in_process_command` and names the tool to call instead. | | A terminal outside any session | The `droid analytics effectiveness` commands run. The `droid loop` commands, `droid work-item link`, and `droid analytics readiness store` exit `1` with `in_process_command` and name the tool to call, because each acts on a session. | A command prints `{"ok": true, "data": {...}}` to stdout and exits `0` when it succeeds. A failure prints `{"ok": false, "code": "...", "error": "..."}` to stderr, sometimes with `details`, and exits `1`. A command group that is not enabled for your organization fails with an unknown-command error instead, and a failure while Droid starts, such as a settings file it cannot read, can print a plain-text error instead. A flag that takes JSON accepts it inline or from a file, as in `--request @request.json`. | Code | Meaning | | :--- | :------ | | `invalid_input` | The command line could not be parsed, such as an unknown flag or an `@file` that cannot be read; a flag or tool field failed its schema; or `loop_resume` was given a listed loop that is not paused. | | `not_found` | The loop ID matched no loop in this session, or `loop_pause` or `loop_resume` was given a cancelled or expired loop. | | `unavailable` | The command needs a session, this machine cannot schedule loops, or session contents sync is off. | | `permission_denied` | A permission rule or the sandbox denied a file the command writes, such as the report `droid analytics effectiveness render` saves. | | `in_process_command` | A session's shell ran the command, or a terminal ran a command that runs only as a tool. `details.tool` and `details.scriptPath` name the tool to call. | | `request_failed` | The local daemon or Droid refused a request the command made. When Droid answered, `status` carries its HTTP status. | In Airgap Mode, Droid does not offer the `work_item_link` and `analytics_effectiveness_usage` tools, because each needs Droid on every run. ### Schedule recurring prompts In a session, type `/loop ` or ask Droid to repeat a task on a schedule. `/loop ` schedules the loop directly; for a request in prose, Droid creates the loop with the `loop_create` tool. `/loop status` lists the session's loops, and `/loop stop ` stops one (`/loop stop all` stops every loop in the session). ```text > /loop 30m check the CI run on my pull request and fix any failure ``` Loops fire from the daemon on the session's machine, so they run on your own machine and on [Computers](/droid-computers/overview). On your own machine, a loop runs only while its session is open. On a Computer, a loop keeps running after you leave the session: each run wakes the Computer and reopens the session. There a loop expires seven days after it is created or last resumed, rescheduled, or given a new prompt, so a forgotten loop does not keep running unattended. Workspace sandboxes cannot schedule loops, because nothing wakes a paused sandbox for a scheduled run. Droid manages a session's loops with five tools, which a Script calls as `tools.loop.create`, `tools.loop.list`, `tools.loop.pause`, `tools.loop.resume`, and `tools.loop.cancel`: | Tool | What it does | Fields | | :--- | :----------- | :----- | | `loop_create` | Schedule `prompt` as a recurring prompt for the calling session. Inside a Task, the loop belongs to the session that launched the Task when the Task's session records one, and otherwise to the Task's own session. Runs only in a session. | `prompt` and `cron`, both required; `waitForSchedule` | | `loop_list` | List the session's loops, with their IDs, schedules, and states. | None | | `loop_pause` | Stop a loop from running and keep it, so `loop_resume` can restart it. | `loopId` | | `loop_resume` | Run a paused loop on its schedule again. A listed loop that is not paused fails with `invalid_input`; a cancelled or expired loop, which `loop_list` does not show, fails with `not_found`. | `loopId` | | `loop_cancel` | Delete a loop. Cancelling a loop that is already cancelled succeeds again. | `loopId` | For example, a Script schedules a loop that checks CI every 15 minutes, starting at the first scheduled run, with `tools.loop.create({ prompt: "check CI", cron: "*/15 * * * *", waitForSchedule: true })`. `cron` takes a five-field cron expression in UTC: - A step cadence such as `*/15 * * * *` or `0 */2 * * *` is anchored to the minute the loop is created, so its scheduled runs fall on minute boundaries. It must be an exact interval from 1 minute to 24 hours. - A time of day, such as `0 9 * * *` for 09:00 UTC, is kept as written. - The loop also runs once right away unless `waitForSchedule` is `true`. Without that run, the scheduler skips a first scheduled run that falls less than 30 seconds after the loop is created. A loop belongs to the session that created it. A loop created inside a Task belongs instead to the session that launched the Task, when the Task's session records one. Each run prompts the session the loop belongs to. To manage a session's loops, use `/loop` in that session or ask Droid. #### Read the loop output `/loop status` prints one line per loop: ```text 6503a90d · active · next 9:15am · expires in 7d · #3 · check CI ``` The fields are the loop ID; its state, such as `active` or `paused`; the next run time, or the cadence when no run is scheduled or the loop is paused; `expires in