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
SQLite databases are migrated on startup. PostgreSQL databases are not, unless
AUTOMATION_RUN_MIGRATIONS_ON_STARTUP=true (or 1). With it set, each replica runs
alembic upgrade head before it serves requests, and a failed migration stops it from
starting. Replicas that start at the same time take turns through an advisory lock.
Set AUTOMATION_CREATE_DATABASE_IF_MISSING=true (or 1) to have the migrations create the
PostgreSQL database first if it does not exist. This works both on startup and with
alembic upgrade head. The migrations connect to the postgres database to create it, so
the database user needs the CREATEDB privilege.
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.
4 maintainers
Metadata
4 maintainers
Release files for openhands-automation 1.23.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| openhands_automation-1.23.0.tar.gz | 1.0 MB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| openhands_automation-1.23.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.4 MB
Release files / openhands_automation-1.23.0.tar.gz
| Download URL | openhands_automation-1.23.0.tar.gz |
|---|---|
| Size | 1.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8bfcf2f4a839569c163acfd7b3aca540de73a65b5db8b638d9f51f530dfece63
|
|
BLAKE2b-256 checksum How to use checksums |
0e096a475a861bd1eabd99e6ba562d5cc7c7386ca8fa8f53342b77dfe850a97b
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logRelease files / openhands_automation-1.23.0-py3-none-any.whl
| Download URL | openhands_automation-1.23.0-py3-none-any.whl |
|---|---|
| Size | 363.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
376df3f5522695f697c7be30d220847b5ac0f98d01389494fdcfbed6ce82630c
|
|
BLAKE2b-256 checksum How to use checksums |
f7301baec9caca182e096f9c438c30bac155d3dbb92a25aba6a5611d0ea56805
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logSecurity for openhands-automation 1.23.0
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.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for openhands_automation-1.23.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
