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.
4 maintainers
Release files for openhands-automation 1.14.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 | |
|---|---|---|---|
| openhands_automation-1.14.0.tar.gz | 738.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| openhands_automation-1.14.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.0 MB
Release files / openhands_automation-1.14.0.tar.gz
| Download URL | openhands_automation-1.14.0.tar.gz |
|---|---|
| Size | 738.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9ac84222b60243fc31db96a6538dcbd87341bfb59632a2c819436d82302015de
|
|
BLAKE2b-256 checksum How to use checksums |
0da5ffddcc87b33904ac36923b40a2ea8a03206e0dffaee5bc0d4dc5edc23cd2
|
| 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 Sep 22, 2026.
Transparency logRelease files / openhands_automation-1.14.0-py3-none-any.whl
| Download URL | openhands_automation-1.14.0-py3-none-any.whl |
|---|---|
| Size | 306.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c174ba0ae5767618b406c7c7d783d92ecf014a889dbd90caa7420a817e41e8ab
|
|
BLAKE2b-256 checksum How to use checksums |
3794961839488b2f0ca69c8204937a81715a5b65643c19fcc3aa4ccb5f4a2d1e
|
| 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 Sep 22, 2026.
Transparency log
