OpenHands Automation Service

⚠️ Beta: This project is currently in beta. APIs and features may change without notice.

Scheduled and event-driven automation execution for OpenHands Cloud. This service allows users to create automations that run on a schedule (cron) or in response to events (webhooks).

Features

Scheduled Automations: Run OpenHands conversations on a cron schedule
Event-Driven: Trigger automations via webhooks (e.g., GitHub events)
API Key Management: Per-user API keys for secure automation access
Run History: Track automation runs with status and results

Repository boundaries

The Automation Service owns automation definitions, cron scheduling, webhooks, run history, dispatch, and sandbox lifecycle orchestration. It manages when work runs; the Agent Server and OpenHands/software-agent-sdk execute the agent conversations and own agent/tool behavior, workspaces, events, and API endpoints.

OpenHands/typescript-client provides typed browser access to the Agent Server API, while OpenHands/OpenHands owns Agent Canvas UI and frontend integration. If a change belongs in one of those repositories, open the PR there rather than duplicating the logic here.

Development

Prerequisites

Python 3.12+
uv for dependency management
PostgreSQL (or use testcontainers for testing)

Setup

# Install dependencies
uv sync --group dev

# Run the service locally (requires PostgreSQL)
uv run uvicorn openhands.automation.app:app --host 0.0.0.0 --port 8000 --reload

Testing

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=openhands/automation --cov-report=term-missing

Code Quality

# Run pre-commit hooks
uv run pre-commit run --all-files

# Format code
uv run ruff format

# Lint code
uv run ruff check --fix

# Type check
uv run pyright

Database Migrations

# Create a new migration
uv run alembic revision --autogenerate -m "description"

# Apply migrations
uv run alembic upgrade head

Docker

# Build the image
docker build -t automation -f containers/Dockerfile .

# Run the container
docker run -p 8000:8000 automation

Project Structure

openhands/
└── automation/      # Main application package (openhands.automation namespace)
    ├── app.py           # FastAPI application entry point
    ├── router.py        # API routes for CRUD operations
    ├── scheduler.py     # Background scheduler for cron jobs
    ├── dispatcher.py    # Dispatches pending runs to OpenHands
    ├── models.py        # SQLAlchemy models
    ├── schemas.py       # Pydantic schemas for API
    └── utils/           # Utility functions
migrations/          # Alembic database migrations
tests/               # Unit tests
containers/          # Docker configuration

Deployment

This service is deployed via the deploy repository. Docker images are automatically built and pushed to ghcr.io/openhands/automation on every push to main and on tags.

Release files for openhands-automation 1.15.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for openhands-automation 1.15.0
File	Size	Uploaded
openhands_automation-1.15.0.tar.gz	761.3 kB	Sep 23, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for openhands-automation 1.15.0
File	Interpreter	ABI	Platform	Reset
openhands_automation-1.15.0-py3-none-any.whl 319.1 kB Sep 23, 2026	Python 3	none	any	Details

Total release size: 1.1 MB

Release files / openhands_automation-1.15.0.tar.gz

Download URL	openhands_automation-1.15.0.tar.gz
Size	761.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`a18093cf1b28278fb21e7c9a51f242b51cd49f077bfb88a695674e7f80abab2f`
BLAKE2b-256 checksum How to use checksums	`7d4f6dde975e16db60ca18cc4afddbab7898f969c3df67d261c0e9b5ac020e18`
Upload date	Sep 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/OpenHands/automation
Publishing commit: github.com/OpenHands/automation/tree/49fe6639aa328cd5c24a6c869712445bebf9bacc

Workflow

Publishing configuration: github.com/OpenHands/automation/blob/49fe6639aa328cd5c24a6c869712445bebf9bacc/.github/workflows/pypi-release.yml
Publishing logs: github.com/OpenHands/automation/actions/runs/35886030029/attempts/1

Artifact

Subject: openhands_automation-1.15.0.tar.gz
SHA-256 checksum: a18093cf1b28278fb21e7c9a51f242b51cd49f077bfb88a695674e7f80abab2f Verifying attestations

Release files / openhands_automation-1.15.0-py3-none-any.whl

Download URL	openhands_automation-1.15.0-py3-none-any.whl
Size	319.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`488bbe7311814b61ef214f6c0c849db1cde7068b6ad86202712f194458946fee`
BLAKE2b-256 checksum How to use checksums	`777310665c75507c764cff8a792f782458b2d29deb5cd22af461b9bf86dae22e`
Upload date	Sep 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/OpenHands/automation
Publishing commit: github.com/OpenHands/automation/tree/49fe6639aa328cd5c24a6c869712445bebf9bacc

Workflow

Publishing configuration: github.com/OpenHands/automation/blob/49fe6639aa328cd5c24a6c869712445bebf9bacc/.github/workflows/pypi-release.yml
Publishing logs: github.com/OpenHands/automation/actions/runs/35886030029/attempts/1

Artifact

Subject: openhands_automation-1.15.0-py3-none-any.whl
SHA-256 checksum: 488bbe7311814b61ef214f6c0c849db1cde7068b6ad86202712f194458946fee Verifying attestations