Skip to main content

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.

Metadata

Release files for openhands-automation 1.26.0

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.26.0
File Size Uploaded Provenance Actions
openhands_automation-1.26.0.tar.gz 1.1 MB With provenance Details for openhands_automation-1.26.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for openhands-automation 1.26.0
File Interpreter ABI Platform Actions
openhands_automation-1.26.0-py3-none-any.whl Python 3 none any Details for openhands_automation-1.26.0-py3-none-any.whl

Total release size: 1.4 MB

Release files / openhands_automation-1.26.0.tar.gz

Download URL openhands_automation-1.26.0.tar.gz
Size 1.1 MB
Tags Source
SHA-256 checksum
How to use checksums
849f3472c452a9bb129fb7ec5fa7f452d75a110fa7ded71f5b13a603bd39863d
BLAKE2b-256 checksum
How to use checksums
6d7f7b711039e4636856191e67ab8b4a6250f5c09d4d49907c55b466197652d5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 26, 2026.

Transparency log

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

Download URL openhands_automation-1.26.0-py3-none-any.whl
Size 375.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d67c3119ee629d85e56d0da652dec29481e1a24e97d27a95d9990c8cd5fa60ed
BLAKE2b-256 checksum
How to use checksums
a93a4eccfe8e2996e76b5d74d02dcfe504c00f12c65271743fa40dd17ad01822
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 26, 2026.

Transparency log

Security for openhands-automation 1.26.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

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for openhands_automation-1.26.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 26, 2026.

Transparency log

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

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.26.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page