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

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.32.1
File Size Uploaded Provenance Actions
openhands_automation-1.32.1.tar.gz 1.2 MB With provenance Details for openhands_automation-1.32.1.tar.gz

Built distribution (wheel)

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

Total release size: 1.7 MB

Release files / openhands_automation-1.32.1.tar.gz

Download URL openhands_automation-1.32.1.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
2757402c3779f4db15a8d93e2175bec8fc7f11d6dfb83e9f365a4c301f992ead
BLAKE2b-256 checksum
How to use checksums
5c8ef2a9702e22af7d0cabac6164dfa369a6d4ddada27a01c548fb2400113448
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 Nov 11, 2026.

Transparency log

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

Download URL openhands_automation-1.32.1-py3-none-any.whl
Size 437.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4eaa9917f88e53cfbde47c302265e61dd692e3f88b242ec9eefaa7d2901b381b
BLAKE2b-256 checksum
How to use checksums
a6765f648e928577db4ef75774ea13b75b7e3cff4b6fec83c848ff052d5dc0aa
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 Nov 11, 2026.

Transparency log

Security for openhands-automation 1.32.1

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.32.1.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 Nov 11, 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.32.1 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