OpenHands automation

OpenHands automation server

1: Defaults

Runs the OpenHands automation server natively from a uv-managed virtual environment. It stores schedules and event triggers, tracks run lifecycle, and dispatches conversations to the agent server.

The automation server is not a sandbox. It records which agent server should run a dispatched conversation and hands that work to AUTOMATION_AGENT_SERVER_URL; setting that variable selects the agent server’s local mode, which uses a persistent local agent server instead of managed OpenHands Cloud sandboxes.

openhands_automation_agent_server_api_key must equal the agent server’s session API key because both services authenticate the same X-Session-API-Key value. openhands_automation_local_api_key is the key browsers present to this service.

The service stores state in SQLite via AUTOMATION_DB_URL by default, which local mode supports without a separate database role. Set openhands_automation_database_url to a PostgreSQL URL to use one instead. openhands_automation_kv_secret enables the automation key-value store and is required for automations that persist state between runs.

openhands_automation_base_url is the externally reachable origin the service appends /api/automation to when it builds callback URLs, so it must be the origin the browser and the dispatched agent server side both use.

1 - Defaults

Defaults for openhands_automation

openhands_automation_user: openhands
openhands_automation_user_uid: 8154
openhands_automation_dir: /opt/openhands-automation
openhands_automation_home_dir: "{{ openhands_automation_dir }}/home"
openhands_automation_work_dir: "{{ openhands_automation_dir }}/work"
openhands_automation_state_dir: "{{ openhands_automation_dir }}/state"
openhands_automation_disk:
openhands_automation_packages:
  - python3.12
  - uv
openhands_automation_host: 127.0.0.1
openhands_automation_port: 18001
openhands_automation_version: "{{ undefined() }}"
openhands_automation_agent_server_version: "{{ undefined() }}"
openhands_automation_agent_server_url: "{{ undefined() }}"
openhands_automation_sandbox_agent_server_url: ""
openhands_automation_agent_server_api_key: "{{ undefined() }}"
openhands_automation_base_url: "{{ undefined() }}"
openhands_automation_local_api_key: "{{ undefined() }}"
openhands_automation_kv_secret: "{{ undefined() }}"
openhands_automation_database_url: "sqlite+aiosqlite:///{{ openhands_automation_state_dir }}/automations.db"
openhands_automation_workspace_base: "{{ openhands_automation_work_dir }}/automations"
openhands_automation_venv_dir: "{{ openhands_automation_dir }}/venv"
openhands_automation_service_path: /lib/systemd/system/openhands-automation.service
openhands_automation_env_path: "{{ openhands_automation_dir }}/.env"
openhands_automation_env:
  PYTHONUTF8: "1"
  OPENHANDS_REMOTE_WS_READY_REQUIRED: "false"
  OPENHANDS_SUPPRESS_BANNER: "1"
openhands_automation_env_override: {}