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

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.13.2
File	Size	Uploaded
openhands_automation-1.13.2.tar.gz	741.5 kB	Sep 17, 2026	Details

Built distribution (wheel)

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

Total release size: 1.0 MB

Release files / openhands_automation-1.13.2.tar.gz

Download URL	openhands_automation-1.13.2.tar.gz
Size	741.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`2e1b8219e1563c47b425087ee592f7130257741d7d3737cd4c7c5d0a935df9b8`
BLAKE2b-256 checksum How to use checksums	`82044e0871fa2b3cad2901dcca5dff09a0748f16b9a958ba932cc09687c84e9f`
Upload date	Sep 17, 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/4472528503d911d1e18362cbee8639d67d309614

Workflow

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

Artifact

Subject: openhands_automation-1.13.2.tar.gz
SHA-256 checksum: 2e1b8219e1563c47b425087ee592f7130257741d7d3737cd4c7c5d0a935df9b8 Verifying attestations

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

Download URL	openhands_automation-1.13.2-py3-none-any.whl
Size	306.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`b410d1faadb8a37979bbd44854f9f54475491f8ea0aae2daac919188bdd4aef2`
BLAKE2b-256 checksum How to use checksums	`40e29c76c719ce943a2e18684f0891995828c58b0a1d10c8e18856b1cd133586`
Upload date	Sep 17, 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/4472528503d911d1e18362cbee8639d67d309614

Workflow

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

Artifact

Subject: openhands_automation-1.13.2-py3-none-any.whl
SHA-256 checksum: b410d1faadb8a37979bbd44854f9f54475491f8ea0aae2daac919188bdd4aef2 Verifying attestations