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
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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file openhands_automation-1.2.0.tar.gz.
File metadata
- Download URL: openhands_automation-1.2.0.tar.gz
- Upload date:
- Size: 674.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6968a7dd5acef4679c9de4edf9e75e8193279b0863d556eaa621b57b8796e7ab
|
|
| MD5 |
aefc9b2ef228ca992a49a2d5339d4c01
|
|
| BLAKE2b-256 |
8f65e4bc8dae0d51ce901070a01e3da131d26addd3c9b0a9ad1ac3db76a13609
|
Provenance
The following attestation bundles were made for openhands_automation-1.2.0.tar.gz:
Publisher:
pypi-release.yml on OpenHands/automation
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
openhands_automation-1.2.0.tar.gz -
Subject digest:
6968a7dd5acef4679c9de4edf9e75e8193279b0863d556eaa621b57b8796e7ab - Sigstore transparency entry: 2223207473
- Sigstore integration time:
-
Permalink:
OpenHands/automation@f271b234c0f2c75f7d0f34727b6e39e99441279d -
Branch / Tag:
refs/tags/1.2.0 - Owner: https://github.com/OpenHands
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
pypi-release.yml@f271b234c0f2c75f7d0f34727b6e39e99441279d -
Trigger Event:
push
-
Statement type:
File details
Details for the file openhands_automation-1.2.0-py3-none-any.whl.
File metadata
- Download URL: openhands_automation-1.2.0-py3-none-any.whl
- Upload date:
- Size: 172.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c9f0d53e8d2ef70a44700e6d5d1228228697de465ee768774ae5b374f51e955d
|
|
| MD5 |
62c5152f7f7f6cf44bfc20d337e8bd4e
|
|
| BLAKE2b-256 |
ac1f494b5a314da50716cd6f5d4f0edf6d86609821a9ccd3760997531fd760bb
|
Provenance
The following attestation bundles were made for openhands_automation-1.2.0-py3-none-any.whl:
Publisher:
pypi-release.yml on OpenHands/automation
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
openhands_automation-1.2.0-py3-none-any.whl -
Subject digest:
c9f0d53e8d2ef70a44700e6d5d1228228697de465ee768774ae5b374f51e955d - Sigstore transparency entry: 2223207872
- Sigstore integration time:
-
Permalink:
OpenHands/automation@f271b234c0f2c75f7d0f34727b6e39e99441279d -
Branch / Tag:
refs/tags/1.2.0 - Owner: https://github.com/OpenHands
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
pypi-release.yml@f271b234c0f2c75f7d0f34727b6e39e99441279d -
Trigger Event:
push
-
Statement type:
