Droid Exec (Headless) - Factory Documentation

Droid Exec is Factory’s headless execution mode designed for automation workflows. Unlike the interactive CLI, droid exec runs as a one-shot command that completes a task and exits, making it ideal for CI/CD pipelines, shell scripts, and batch processing.

Explore the Droid Exec cookbooks.

Summary and goals

Droid Exec is a one-shot task runner designed to:

Produce readable logs, and structured artifacts when requested
Enforce opt-in for mutations/command execution (secure-by-default)
Fail fast on permission violations with clear errors
Support simple composition for batch and parallel work

Non-Interactive

Single run execution that writes to stdout/stderr for CI/CD integration

Secure by Default

Read-only by default with explicit opt-in for mutations via autonomy levels

Composable

Designed for shell scripting, parallel execution, and pipeline integration

Clean Output

Structured output formats and artifacts for automated processing

Execution model

Non-interactive single run that writes to stdout/stderr.
Default is spec-mode: the agent is only allowed to execute read-only operations.
Add --auto to enable edits and commands; risk tiers gate what can run.

CLI help (excerpt):

Usage: droid exec [options] [prompt]

Execute a single command (non-interactive mode)

Arguments:
  prompt                          The prompt to execute

Options:
  -o, --output-format <format>          Output format (default: "text")
  --input-format <format>               Input format: stream-jsonrpc for multi-turn sessions
  -f, --file <path>                     Read prompt from file
  --auto <level>                        Autonomy level: low|medium|high
  --skip-permissions-unsafe             Skip ALL permission checks - allows all permissions (unsafe)
  -s, --session-id <id>                 Existing session to continue (requires a prompt)
  --fork <id>                           Fork an existing session and continue from it
  -m, --model <id>                      Model ID to use
  -r, --reasoning-effort <level>        Reasoning effort (defaults per model)
  --spec-model <id>                     Model ID to use for spec mode
  --spec-reasoning-effort <level>       Reasoning effort for spec mode
  --use-spec                            Start in spec mode
  --enabled-tools <ids>                 Enable specific tools (comma or space separated list)
  --disabled-tools <ids>                Disable specific tools (comma or space separated list)
  --list-tools                          List available tools for the selected model and exit
  --cwd <path>                          Working directory path
  -w, --worktree [name]                 Run in a git worktree
  --worktree-dir <path>                 Directory for worktree creation
  --tag <spec>                          Session tag (name or JSON, repeatable)
  --log-group-id <id>                   Log group ID for filtering logs
  --append-system-prompt <text>         Append custom text to end of system prompt
  --append-system-prompt-file <path>    Append file contents to end of system prompt
  --mission                             Run in mission mode (multi-agent orchestration)
  --worker-model <id>                   Model for mission workers
  --worker-reasoning-effort <level>     Reasoning effort for mission workers
  --validator-model <id>                Model for mission validators
  --validator-reasoning-effort <level>  Reasoning effort for mission validators
  -h, --help                            display help for command

Use any available model ID with --model or --spec-model. For custom models, see Bring Your Own Key (BYOK).

Installation

Install the Droid CLI

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

Get Factory API Key

Generate your API key from the Factory Settings Page

Set Environment Variable

Export your API key as an environment variable:

export FACTORY_API_KEY=fk-...

Quickstart

Direct prompt:
- droid exec "analyze code quality"
- droid exec "fix the bug in src/main.js" --auto low
From file:
- droid exec -f prompt.md
Pipe:
- echo "summarize repo structure" | droid exec
Session continuation:
- droid exec --session-id <session-id> "continue with next steps"

Autonomy Levels

Droid exec uses a tiered autonomy system to control what operations the agent can perform. By default, it runs in read-only mode, requiring explicit flags to enable modifications.

DEFAULT (no flags) - Read-only Mode

The safest mode for reviewing planned changes without execution:

✅ Reading files or logs: cat, less, head, tail, systemctl status
✅ Display commands: echo, pwd
✅ Information gathering: whoami, date, uname, ps, top
✅ Git read operations: git status, git log, git diff
✅ Directory listing: ls, find (without -delete or -exec)
❌ No modifications to files or system
Use case: Safe for reviewing what changes would be made

# Analyze and plan refactoring without making changes
droid exec "Analyze the authentication system and create a detailed plan for migrating from session-based auth to OAuth2. List all files that would need changes and describe the modifications required."

# Review code quality and generate report
droid exec "Review the codebase for security vulnerabilities, performance issues, and code smells. Generate a prioritized list of improvements needed."

# Understand project structure
droid exec "Analyze the project architecture and create a dependency graph showing how modules interact with each other."

`--auto low` - Low-risk Operations

Enables basic file operations while blocking system changes:

✅ File creation/editing in project directories
❌ No system modifications or package installations
Use case: Documentation updates, code formatting, adding comments

# Safe file operations
droid exec --auto low "add JSDoc comments to all functions"
droid exec --auto low "fix typos in README.md"

`--auto medium` - Development Operations

Operations that may have significant side effects, but these side effects are typically harmless and straightforward to recover from. Adds common development tasks to low-risk operations:

Installing packages from trusted sources: npm install, pip install (without sudo)
Network requests to trusted endpoints: curl, wget to known APIs
Git operations that modify local repositories: git commit, git checkout, git pull (but not git push)
Building code with tools like make, npm run build, mvn compile
❌ No git push, sudo commands, or production changes
Use case: Local development, testing, dependency management

# Development tasks
droid exec --auto medium "install deps, run tests, fix issues"
droid exec --auto medium "update packages and resolve conflicts"

`--auto high` - Production Operations

Commands that may have security implications such as data transfers between untrusted sources or execution of unknown code, or major side effects such as irreversible data loss or modifications of production systems/deployments.

Running arbitrary/untrusted code: curl | bash, eval, executing downloaded scripts
Exposing ports or modifying firewall rules that could allow external access
Git push operations that modify remote repositories: git push, git push —force
Irreversible actions to production deployments, database migrations, or other sensitive operations
Commands that access or modify sensitive information like passwords or keys
❌ Still blocks: sudo rm -rf /, system-wide changes
Use case: CI/CD pipelines, automated deployments

# Full workflow automation
droid exec --auto high "fix bug, test, commit, and push to main"
droid exec --auto high "deploy to staging after running tests"

`--skip-permissions-unsafe` - Bypass All Checks

DANGEROUS: This mode allows ALL operations without confirmation. Only use in completely isolated environments like Docker containers or throwaway VMs.

⚠️ Allows ALL operations without confirmation
⚠️ Can execute irreversible operations
Cannot be combined with —auto flags
Use case: Isolated environments

# In a disposable Docker container for CI testing
docker run --rm -v $(pwd):/workspace alpine:latest sh -c "
  apk add curl bash &&
  curl -fsSL https://app.factory.ai/cli | sh &&
  droid exec --skip-permissions-unsafe 'Install all system dependencies, modify system configs, run integration tests that require root access, and clean up test databases'
"

# In ephemeral GitHub Actions runner for rapid iteration
# where the runner is destroyed after each job
droid exec --skip-permissions-unsafe "Modify /etc/hosts for test domains, install custom kernel modules, run privileged container tests, and reset network interfaces"

# In a temporary VM for security testing
droid exec --skip-permissions-unsafe "Run penetration testing tools, modify firewall rules, test privilege escalation scenarios, and generate security audit reports"

Fail-fast Behavior

If a requested action exceeds the current autonomy level, droid exec will:

Stop immediately with a clear error message
Return a non-zero exit code
Not perform any partial changes

This ensures predictable behavior in automation scripts and CI/CD pipelines.

Output formats and artifacts

Droid exec supports three output formats for different use cases:

text (default)

Human-readable output for direct consumption or logs:

$ droid exec --auto low "create a python file that prints 'hello world'"
Perfect! I've created a Python file named `hello_world.py` in your home directory that prints 'hello world' when executed.

json

Structured JSON output for parsing in scripts and automation:

$ droid exec "summarize this repository" --output-format json
{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "duration_ms": 5657,
  "num_turns": 1,
  "result": "This is a Factory documentation repository containing guides for CLI tools, web platform features, and onboarding procedures...",
  "session_id": "8af22e0a-d222-42c6-8c7e-7a059e391b0b"
}

Use JSON format when you need to:

Parse the result in a script
Check success/failure programmatically
Extract session IDs for continuation
Process results in a pipeline

Build custom flows on raw JSON-RPC

For custom integrations, you can run Droid as a long-lived subprocess and drive the full JSON-RPC control surface over stdin/stdout:

droid exec --input-format stream-jsonrpc --output-format stream-jsonrpc --auto low

This is the lowest-level integration path for building your own interaction model around Droid. Your process can send turns, stream assistant output, handle permissions, update settings, manage MCP/tools, interrupt work, and resume or fork sessions. Each stdin line is one JSON-RPC request. Each stdout line is a JSON-RPC response, server request, or notification. A custom client typically:

Spawns droid exec with the project cwd and desired flags
Writes newline-delimited JSON-RPC requests with unique IDs
Starts with droid.initialize_session or droid.load_session
Sends turns with droid.add_user_message
Reads stdout line-by-line and matches responses by id
Handles droid.session_notification events for assistant text deltas, tool events, token usage, errors, and turn completion
Responds to server-to-client requests such as droid.request_permission and droid.ask_user
Calls other session methods to interrupt work, update settings, manage MCP servers/tools, inspect context, fork sessions, or compact history
Implements timeouts, process cleanup, and session persistence

You can build on top of raw stdin/stdout to create custom interaction flows such as:

Web, desktop, or IDE agent experiences with your own UX and controls
Chat or copiloting surfaces that route user actions into Droid turns
CI and workflow runners that execute Droid tasks and surface progress in build logs
Orchestrators that queue work, resume sessions, fork conversations, and persist results
Policy layers that approve, deny, transform, or audit tool permission requests
Bridges from Droid events into your own protocol, message bus, telemetry, or storage layer

For protocol reference and implementation patterns, see the low-level client and process transport in the TypeScript SDK. Prefer an SDK when possible:

TypeScript: @factory/droid-sdk for Node.js apps, streaming, multi-turn sessions, structured output, permissions, tool controls, and SDK-backed MCP tools
Python: droid-sdk for asyncio apps, streaming, direct client control, notifications, permissions, and typed event handling

For automated pipelines, you can also direct the agent to write specific artifacts:

droid exec --auto low "Analyze dependencies and write to deps.json"
droid exec --auto low "Generate metrics report in CSV format to metrics.csv"

Working directory

Use --cwd to scope execution:

droid exec --cwd /home/runner/work/repo "Map internal packages and dump graphviz DOT to deps.dot"

Use -w, --worktree [name] to run the task inside an isolated git worktree on its own branch. This is useful for fanning out parallel droid exec jobs against the same repo without file conflicts:

droid exec --worktree codemod-a --auto medium "apply codemod A" &
droid exec --worktree codemod-b --auto medium "apply codemod B" &
wait

Clean worktrees are auto-removed on exit; dirty ones are preserved so you can review and push the work.

Models and reasoning effort

Choose a model with -m and adjust reasoning with -r. See the Available Models for available models.

droid exec -m claude-sonnet-4-5-20250929 -r medium -f plan.md

Use --use-spec to start in specification mode, where the agent plans before executing:

droid exec --use-spec --auto low "refactor the auth module"

You can also use a different model for the spec phase:

droid exec --use-spec --spec-model claude-haiku-4-5-20251001 --auto medium "implement feature X"

Tool controls

List available tools for a model:

droid exec --list-tools
droid exec --model gpt-5-codex --list-tools --output-format json

Enable or disable specific tools:

# Enable additional tools
droid exec --enabled-tools ApplyPatch "refactor files"

# Disable specific tools
droid exec --auto medium --disabled-tools execute-cli "run edits only"

Custom models

You can configure custom models to use with droid exec by adding them to your ~/.factory/settings.json file:

{
  "customModels": [
    {
      "model": "gpt-5.1-codex-custom",
      "displayName": "My Custom Model",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "your-api-key-here",
      "provider": "openai"
    }
  ]
}

To use a custom model, use the custom: prefix followed by the display name (with spaces replaced by dashes) and the index:

droid exec --model "custom:My-Custom-Model-0" "analyze this codebase"

If you have multiple custom models configured:

{
  "customModels": [
    {
      "model": "kimi-k2",
      "displayName": "Kimi K2 [Groq]",
      "baseUrl": "https://api.groq.com/openai/v1",
      "apiKey": "your-groq-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 16384
    },
    {
      "model": "openai/gpt-oss-20b",
      "displayName": "GPT-OSS-20B [OpenRouter]",
      "baseUrl": "https://openrouter.ai/api/v1",
      "apiKey": "YOUR_OPENROUTER_KEY",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 32000
    }
  ]
}

You would reference them as:

--model "custom:Kimi-K2-[Groq]-0"
--model "custom:GPT-OSS-20B-[OpenRouter]-1"

The index corresponds to the position in the customModels array (0-based).

Reasoning effort (-r / --reasoning-effort) is not yet supported for custom models, but coming soon.

Sessions, tagging, and logs

Forking lets you branch off an existing session without disturbing the original; the new run starts from the forked session’s history and is assigned a fresh session ID.

# Continue a session in-place
droid exec --session-id <session-id> "next steps"

# Branch off a session into a new run
droid exec --fork <session-id> --auto low "try an alternative refactor"

Use --tag to attach searchable labels to a run. The flag is repeatable and accepts either a plain name or a JSON object for structured metadata. Pair it with --log-group-id to bucket logs from related runs together for easier filtering and aggregation downstream.

droid exec \
  --tag release-v2 \
  --tag '{"name":"team","value":"platform"}' \
  --log-group-id ci-nightly \
  --auto low "run nightly checks and write report.md"

Customizing the system prompt

Use --append-system-prompt to append additional text to the end of the system prompt for a single run, or --append-system-prompt-file to append the contents of a file. Both flags can be combined and are useful for injecting project-specific guidance, style guides, or invariants without modifying global settings.

droid exec \
  --append-system-prompt "Always prefer functional React components." \
  --auto low "review src/components for class-based components"

droid exec \
  --append-system-prompt-file ./docs/style-guide.md \
  --auto low "lint prose in README.md against the style guide"

Mission mode

Mission mode runs droid exec as a multi-agent orchestrator that plans work, delegates to worker agents, and validates results. Enable it with --mission and optionally select dedicated models and reasoning effort levels for the worker and validator roles.

droid exec --mission \
  --worker-model claude-sonnet-4-5-20250929 \
  --worker-reasoning-effort medium \
  --validator-model claude-sonnet-4-5-20250929 \
  --validator-reasoning-effort high \
  --auto medium \
  "ship the new billing webhook end-to-end"

Mission mode flags

Flag	Description
`--mission`	Run in mission mode (multi-agent orchestration).
`--worker-model <id>`	Model ID used by mission worker agents.
`--worker-reasoning-effort <level>`	Reasoning effort for mission workers.
`--validator-model <id>`	Model ID used by mission validator agents.
`--validator-reasoning-effort <level>`	Reasoning effort for mission validators.

The top-level -m, --model and -r, --reasoning-effort flags still apply to the orchestrator itself; the worker and validator overrides only affect the agents the orchestrator spawns.

Batch and parallel patterns

Shell loops (bounded concurrency):

# Process files in parallel (GNU xargs -P)
find src -name "*.ts" -print0 | xargs -0 -P 4 -I {} \
  droid exec --auto low "Refactor file: {} to use modern TS patterns"

Background job parallelization:

# Process multiple directories in parallel with job control
for path in packages/ui packages/models apps/factory-app; do
  (
    cd "$path" &&
    droid exec --auto low "Run targeted analysis and write report.md"
  ) &
done
wait  # Wait for all background jobs to complete

Chunked inputs:

# Split large file lists into manageable chunks
git diff --name-only origin/main...HEAD | split -l 50 - /tmp/files_
for f in /tmp/files_*; do
  list=$(tr '\n' ' ' < "$f")
  droid exec --auto low "Review changed files: $list and write to review.json"
done
rm /tmp/files_*  # Clean up temporary files

Workflow Automation (CI/CD):

# Dead code detection and cleanup suggestions
name: Code Cleanup Analysis
on:
  schedule:
    - cron: '0 1 * * 0' # Weekly on Sundays
  workflow_dispatch:
jobs:
  cleanup-analysis:
    strategy:
      matrix:
        module: ['src/components', 'src/services', 'src/utils', 'src/hooks']
    steps:
      - uses: actions/checkout@v4
      - run: droid exec --cwd "${{ matrix.module }}" --auto low "Identify unused exports, dead code, and deprecated patterns. Generate cleanup recommendations in cleanup-report.md"

Unique usage examples

License header enforcer:

git ls-files "*.ts" | xargs -I {} \
  droid exec --auto low "Ensure {} begins with the Apache-2.0 header; add it if missing"

API contract drift check (read-only):

droid exec "Compare openapi.yaml operations to our TypeScript client methods and write drift.md with any mismatches"

Security sweep:

droid exec --auto low "Run a quick audit for sync child_process usage and propose fixes; write findings to sec-audit.csv"

Exit behavior

0: success
Non-zero: failure (permission violation, tool error, unmet objective). Treat non-zero as failed in CI.

Best practices

Favor --auto low; keep mutations minimal and commit/push in scripted steps.
Avoid --skip-permissions-unsafe unless fully sandboxed.
Ask the agent to emit artifacts your pipeline can verify.
Use --cwd to constrain scope in monorepos.

​Summary and goals

Non-Interactive

Secure by Default

Composable

Clean Output

​Execution model

​Installation

​Quickstart

​Autonomy Levels

​DEFAULT (no flags) - Read-only Mode

​--auto low - Low-risk Operations

​--auto medium - Development Operations

​--auto high - Production Operations

​--skip-permissions-unsafe - Bypass All Checks

​Fail-fast Behavior

​Output formats and artifacts

​text (default)

​json

​Build custom flows on raw JSON-RPC

​Working directory

​Models and reasoning effort

​Tool controls

​Custom models

​Sessions, tagging, and logs

​Customizing the system prompt

​Mission mode

​Mission mode flags

​Batch and parallel patterns

​Unique usage examples

​Exit behavior

​Best practices

Summary and goals

Execution model

Installation

Quickstart

Autonomy Levels

DEFAULT (no flags) - Read-only Mode

`--auto low` - Low-risk Operations

`--auto medium` - Development Operations

`--auto high` - Production Operations

`--skip-permissions-unsafe` - Bypass All Checks

Fail-fast Behavior

Output formats and artifacts

text (default)

json

Build custom flows on raw JSON-RPC

Working directory

Models and reasoning effort

Tool controls

Custom models

Sessions, tagging, and logs

Customizing the system prompt

Mission mode

Mission mode flags

Batch and parallel patterns

Unique usage examples

Exit behavior

Best practices