Skip to main content

​
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

​
See Also