/openhands-automation

name: openhands-automation
description: This skill should be used when the user asks to "create an automation", "schedule a task", "set up a cron job", "webhook integration", "event-triggered automation", or mentions automations, scheduled tasks, cron scheduling, or webhook events in OpenHands Cloud.
triggers:
- automation
- automations
- scheduled task
- cron job
- cron schedule
- webhook
- webhooks
- event trigger
- github event
- pull request automation
- issue automation
- /automation:create

OpenHands Automations

Create and manage automations that run inside an OpenHands agent server — triggered by cron schedules or webhook events (GitHub, custom services). Windows PowerShell equivalents for the automation API `curl` examples and shell-variable conventions are in `references/windows.md`.

Automation Creation Process

The agent must follow these steps when creating an automation:

• Quickly check that you can access the correct automations backend using the auth mechanism below
• Quickly check that you can access any necessary integrations (e.g. GitHub, Slack); if access fails, inform the user and stop
• Ask the user for any necessary information, e.g. if you need the name of a Slack channel or GitHub repo to proceed
• Write the code or prompt that will be sent to the automations backend _inside the current workspace_
• Show the code to the user with the `canvas_ui` tool if available, otherwise present it in a fenced code block in your reply
• Message the user with a concise summary of how the automation will behave, and ask if they are ready to deploy it

Architecture

Two components work together to run automations:

**Automation Service** (API at `OPENHANDS_HOST/api/automation/v1`) Manages the *when*: holds automation definitions, schedules cron-triggered runs, dispatches webhook-triggered runs, and receives completion callbacks to mark runs as done. This is the API you call to create, update, and manage automations.

**Agent Server** (accessible as `AGENT_SERVER_URL` inside script runs) Manages the *what*: the runtime environment where automation scripts execute and where conversations (AI agent interactions with tools, bash, file editing, etc.) run. When a run is triggered, the automation service uploads the automation's tarball to the agent server, which unpacks and runs the entrypoint script. The script connects back to the agent server using `AGENT_SERVER_URL` and a session API key to start, monitor, and stop conversations.

The agent server typically runs inside a **sandbox** (a Docker or Kubernetes container). Some deployments use sandboxless mode, where the agent server runs directly on a host.

**Key environment variables:**

| Variable | Availability | Description | |---|---|---| | `RUNTIME_URL` | Ambient in cloud environments | Public-facing URL of the **agent server** sandbox. Use this to determine whether external webhook delivery is possible — if unset or local, webhooks cannot be received. The automation service may run at a separate URL (see Determining the API Host). | | `AGENT_SERVER_URL` | Injected into scripts at run time, local Agent Canvas only | Internal URL of the agent server. Available inside script execution context; **not** an ambient environment variable outside of a running script, and not set on OpenHands Cloud or Enterprise. | | `OPENHANDS_HOST` | Shell convention only — set manually | Base URL for the automation service API. **Not a real environment variable.** Set it from an explicit host, a detected local Agent Canvas server, or the cloud default. Used in all `curl` examples throughout this skill. |

> **⚠️ CRITICAL — Agent behavior rules:** > > 0. **Does this task need an LLM at all? Check first.** Before picking a preset, ask whether the task actually requires reasoning, judgment, summarization, or open-ended tool use. If it is fully deterministic — fixed data transforms, scheduled HTTP calls, healthcheck pings, file rotation, picking from a known list, posting a templated message — an LLM-driven preset is overkill. Every run will consume LLM tokens, which adds up fast at high frequencies (every 5 min ≈ 288 runs/day). Surface the trade-off to the user and offer the custom-script path (see `references/custom-automation.md`) as the cheaper, more reliable option. Be especially careful for cron schedules tighter than hourly. > > **Instant-recognition patterns — these are always deterministic, never use an LLM preset:** > - "post a quote / message / fact every N minutes" (rotating from a list) > - "send a scheduled reminder / standup / digest" > - "ping a health-check URL on a schedule" > - "post to Slack / webhook every N minutes" > - Any task where the full output could be written as a static template right now > > 1. **For LLM-appropriate work, default to preset endpoints.** They handle all SDK boilerplate, tarball packaging, and upload automatically: > - **Prompt preset** (`POST /v1/preset/prompt`) — for tasks expressed as a natural language prompt that benefit from agent reasoning > - **Plugin preset** (`POST /v1/preset/plugin`) — when plugins with skills, MCP configs, or commands are needed > 2. **Present the options, then build the one the user picks.** Whenever rule 0 applies, or neither preset is a clean fit (custom Python dependencies, a non-Python entrypoint, a multi-file project, direct SDK lifecycle control), lay the choices out side by side with a one-line note on cost and reliability for each, and let the user choose: > - **Prompt preset** - natural language prompt execution (LLM-driven) > - **Plugin preset** - load plugins with extended capabilities (skills, MCP, hooks, commands) > - **Custom script** - full control over code, with or without an LLM; see `references/custom-automation.md` > > Do not silently fall back to either side. The "ready to deploy?" confirmation in the creation process applies to every path equally; a custom script needs no extra permission beyond it, and a pre