Headless Mode - OpenHands Docs

Overview

Headless mode runs OpenHands without the interactive terminal UI, making it ideal for:

CI/CD pipelines
Automated scripting
Integration with other tools
Batch processing

openhands --headless -t "Your task here"

Requirements

Must specify a task with --task or --file

Headless mode always runs in always-approve mode. The agent will execute all actions without any confirmation. This cannot be changed—--llm-approve is not available in headless mode.

Basic Usage

# Run a task in headless mode
openhands --headless -t "Write a Python script that prints hello world"

# Load task from a file
openhands --headless -f task.txt

JSON Output Mode

The --json flag enables structured JSONL (JSON Lines) output, streaming events as they occur:

openhands --headless --json -t "Create a simple Flask app"

Each line is a JSON object representing an agent event:

{"type": "action", "action": "write", "path": "app.py", ...}
{"type": "observation", "content": "File created successfully", ...}
{"type": "action", "action": "run", "command": "python app.py", ...}

Use Cases for JSON Output

CI/CD pipelines: Parse events to determine success/failure
Automated processing: Feed output to other tools
Logging: Capture structured logs for analysis
Integration: Connect OpenHands with other systems

Example: Capture Output to File

openhands --headless --json -t "Add unit tests" > output.jsonl

​Overview

​Requirements

​Basic Usage

​JSON Output Mode

​Use Cases for JSON Output

​Example: Capture Output to File

​See Also

Overview

Requirements

Basic Usage

JSON Output Mode

Use Cases for JSON Output

Example: Capture Output to File

See Also