Droid Exec (Headless)

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-json 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)
  -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
  --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
  -h, --help                      display help for command

Supported models (examples):

claude-opus-4-5-20251101 (default)
claude-sonnet-4-5-20250929
claude-haiku-4-5-20251001
gpt-5.1-codex
gpt-5.1
gemini-3-pro-preview
glm-4.6

See the model table for the full list of available models and their costs.

Installation

Install 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

stream-json / debug

Streaming JSONL messages showing the agent’s execution in real-time. Each line is a separate JSON event that can be parsed independently:

$ droid exec "run ls command" --output-format stream-json
{"type":"system","subtype":"init","cwd":"/path/to/dir","session_id":"abc-123","tools":["Read","Execute",...],"model":"claude-sonnet-4-5-20250929"}
{"type":"message","role":"user","id":"msg-1","text":"run ls command","timestamp":1762517060816,"session_id":"abc-123"}
{"type":"message","role":"assistant","id":"msg-2","text":"I'll run the ls command to list the contents...","timestamp":1762517062000,"session_id":"abc-123"}
{"type":"tool_call","id":"call-1","messageId":"msg-2","toolId":"Execute","toolName":"Execute","parameters":{"command":"ls -la"},"timestamp":1762517062500,"session_id":"abc-123"}
{"type":"tool_result","id":"call-1","messageId":"msg-3","toolId":"Execute","isError":false,"value":"total 16\ndrwxr-xr-x@ 8 user staff...","timestamp":1762517063000,"session_id":"abc-123"}
{"type":"completion","finalText":"The ls command has been executed successfully. Here are the directory contents...","numTurns":1,"durationMs":3000,"session_id":"abc-123","timestamp":1762517064000}

The debug format is a deprecated alias for stream-json and works identically.

stream-jsonrpc (multi-turn)

For SDK integration and multi-turn conversations, use the JSON-RPC streaming protocol:

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

This mode reads JSONL messages from stdin and outputs JSON-RPC formatted responses, enabling:

Multi-turn conversations within a single exec invocation
Dynamic mode switching during execution
Full tool access like the interactive TUI

Send messages via stdin in JSONL format and receive structured JSON-RPC responses. Key event types:

system - Session initialization with available tools and model
message - User or assistant text messages
tool_call - Agent calling a tool (Read, Execute, etc.)
tool_result - Result from tool execution
completion - Final event with the complete response in finalText

The completion event is always emitted last and contains:

finalText - The agent’s final response text
numTurns - Number of assistant turns taken
durationMs - Total execution time in milliseconds
session_id - Session identifier for continuation

Stream-JSON format is useful for:

Monitoring agent behavior in real-time
Streaming progress updates to users
Troubleshooting execution issues
Understanding tool usage patterns
Extracting the final result from completion.finalText

Example parsing in shell script:

# Extract just the final result
droid exec "analyze code" --output-format stream-json | \
  jq -r 'select(.type == "completion") | .finalText'

# Monitor tool calls in real-time
droid exec "complex task" --output-format stream-json | \
  jq -r 'select(.type == "tool_call") | "\(.toolName): \(.parameters.command // .parameters.file_path // "")"'

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"

Models and reasoning effort

Choose a model with -m and adjust reasoning with -r. See the model table 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.

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.

Welcome

Integrations

Features

Reference

Enterprise

Resources

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

stream-json / debug

stream-jsonrpc (multi-turn)

Working directory

Models and reasoning effort

Tool controls

Custom models

Batch and parallel patterns

Unique usage examples

Exit behavior

Best practices

Welcome

Integrations

Features

Reference

Enterprise

Resources

​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

​stream-json / debug

​stream-jsonrpc (multi-turn)

​Working directory

​Models and reasoning effort

​Tool controls

​Custom models

​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

stream-json / debug

stream-jsonrpc (multi-turn)

Working directory

Models and reasoning effort

Tool controls

Custom models

Batch and parallel patterns

Unique usage examples

Exit behavior

Best practices