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.1

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.1
File	Size	Uploaded
openhands_automation-1.15.1.tar.gz	762.0 kB	Sep 25, 2026	Details

Built distribution (wheel)

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

Total release size: 1.1 MB

Release files / openhands_automation-1.15.1.tar.gz

Download URL	openhands_automation-1.15.1.tar.gz
Size	762.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`f073719797795a5792ef760c5352878e497b5ec6387cc734535b2dd5a7f2e9af`
BLAKE2b-256 checksum How to use checksums	`c1ff2c4c785f7453c2a38370238d2946f2714c00ddecf2610ae29b6f031f7d88`
Upload date	Sep 25, 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/decc587ec8808f2bc6e04677e3e16236a6ab9f5d

Workflow

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

Artifact

Subject: openhands_automation-1.15.1.tar.gz
SHA-256 checksum: f073719797795a5792ef760c5352878e497b5ec6387cc734535b2dd5a7f2e9af Verifying attestations

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

Download URL	openhands_automation-1.15.1-py3-none-any.whl
Size	319.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`abc0903cd9d78682223eac2ad81e01c5babf9f31c3d5991ffacf3d80f48a660c`
BLAKE2b-256 checksum How to use checksums	`7d95814359254ac472c1324201df4ba4e7f6419a89fa5667172f9c886797d5de`
Upload date	Sep 25, 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/decc587ec8808f2bc6e04677e3e16236a6ab9f5d

Workflow

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

Artifact

Subject: openhands_automation-1.15.1-py3-none-any.whl
SHA-256 checksum: abc0903cd9d78682223eac2ad81e01c5babf9f31c3d5991ffacf3d80f48a660c Verifying attestations