OpenHands/docs/modules/usage/how-to/headless-mode.md

Headless Mode

You can run OpenHands with a single command, without starting the web application. This makes it easy to write scripts and automate tasks with OpenHands.

This is different from CLI Mode, which is interactive, and better for active development.

With Python

To run OpenHands in headless mode with Python:

1. Ensure you have followed the Development setup instructions.
2. Run the following command:

poetry run python -m openhands.core.main -t "write a bash script that prints hi"

You'll need to be sure to set your model, API key, and other settings via environment variables or the config.toml file.

With Docker

To run OpenHands in Headless mode with Docker:

1. Set the following environmental variables in your terminal:

• SANDBOX_VOLUMES to specify the directory you want OpenHands to access (Ex: export SANDBOX_VOLUMES=$(pwd)/workspace:/workspace:rw).
  • The agent works in /workspace by default, so mount your project directory there if you want the agent to modify files.
  • For read-only data, use a different mount path (Ex: export SANDBOX_VOLUMES=$(pwd)/workspace:/workspace:rw,/path/to/large/dataset:/data:ro).
• LLM_MODEL to the model to use (Ex: export LLM_MODEL="anthropic/claude-3-5-sonnet-20241022").
• LLM_API_KEY to the API key (Ex: export LLM_API_KEY="sk_test_12345").

2. Run the following Docker command:

docker run -it \
    --pull=always \
    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.36-nikolaik \
    -e SANDBOX_USER_ID=$(id -u) \
    -e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \
    -e LLM_API_KEY=$LLM_API_KEY \
    -e LLM_MODEL=$LLM_MODEL \
    -e LOG_ALL_EVENTS=true \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v ~/.openhands-state:/.openhands-state \
    --add-host host.docker.internal:host-gateway \
    --name openhands-app-$(date +%Y%m%d%H%M%S) \
    docker.all-hands.dev/all-hands-ai/openhands:0.36 \
    python -m openhands.core.main -t "write a bash script that prints hi"

The -e SANDBOX_USER_ID=$(id -u) is passed to the Docker command to ensure the sandbox user matches the host user’s permissions. This prevents the agent from creating root-owned files in the mounted workspace.

Advanced Headless Configurations

To view all available configuration options for headless mode, run the Python command with the --help flag.

Additional Logs

For the headless mode to log all the agent actions, in the terminal run: export LOG_ALL_EVENTS=true