From 35f864fcee580c0c7780cc1bdab7eee2f9cc89da Mon Sep 17 00:00:00 2001 From: enyst <6080905+enyst@users.noreply.github.com> Date: Mon, 20 Apr 2026 04:07:11 +0000 Subject: [PATCH] docs: sync llms context files --- llms-full.txt | 1885 +++++++++++++++++++++++++++++++++++++++++-------- llms.txt | 7 + 2 files changed, 1603 insertions(+), 289 deletions(-) diff --git a/llms-full.txt b/llms-full.txt index e77a8dbce..e7feb708c 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -9140,7 +9140,7 @@ from openhands.sdk.agent import ACPAgent from openhands.sdk.conversation import Conversation # Point at any ACP-compatible server -agent = ACPAgent(acp_command=["npx", "-y", "claude-code-acp"]) +agent = ACPAgent(acp_command=["npx", "-y", "@agentclientprotocol/claude-agent-acp"]) conversation = Conversation(agent=agent, workspace="./my-project") conversation.send_message("Explain the architecture of this project.") @@ -9196,9 +9196,9 @@ If you attach to an existing conversation by `conversation_id`, use `ACPAgent` f ```python icon="python" agent = ACPAgent( - acp_command=["npx", "-y", "claude-code-acp"], + acp_command=["npx", "-y", "@agentclientprotocol/claude-agent-acp"], acp_args=["--profile", "my-profile"], # extra CLI args - acp_env={"CLAUDE_API_KEY": "sk-..."}, # extra env vars + acp_env={"ANTHROPIC_API_KEY": "sk-..."}, # extra env vars ) ``` @@ -9229,7 +9229,7 @@ Usage data comes from two ACP protocol sources: Always call `agent.close()` when you are done to terminate the ACP server subprocess. A `try/finally` block is recommended: ```python icon="python" -agent = ACPAgent(acp_command=["npx", "-y", "claude-code-acp"]) +agent = ACPAgent(acp_command=["npx", "-y", "@agentclientprotocol/claude-agent-acp"]) try: conversation = Conversation(agent=agent, workspace=".") conversation.send_message("Hello!") @@ -9247,14 +9247,14 @@ This example is available on GitHub: [examples/01_standalone_sdk/40_acp_agent_ex ```python icon="python" expandable examples/01_standalone_sdk/40_acp_agent_example.py """Example: Using ACPAgent with Claude Code ACP server. -This example shows how to use an ACP-compatible server (claude-code-acp) +This example shows how to use an ACP-compatible server (claude-agent-acp) as the agent backend instead of direct LLM calls. It also demonstrates ``ask_agent()`` — a stateless side-question that forks the ACP session and leaves the main conversation untouched. Prerequisites: - Node.js / npx available - - Claude Code CLI authenticated (or CLAUDE_API_KEY set) + - ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY set (can point to LiteLLM proxy) Usage: uv run python examples/01_standalone_sdk/40_acp_agent_example.py @@ -9266,7 +9266,7 @@ from openhands.sdk.agent import ACPAgent from openhands.sdk.conversation import Conversation -agent = ACPAgent(acp_command=["npx", "-y", "@zed-industries/claude-code-acp"]) +agent = ACPAgent(acp_command=["npx", "-y", "@agentclientprotocol/claude-agent-acp"]) try: cwd = os.getcwd() @@ -9285,18 +9285,24 @@ try: "Based on what you just saw, which agent class is the newest addition?" ) print(f"ask_agent response: {response}") + # Report cost (ACP server reports usage via session_update notifications) + cost = agent.llm.metrics.accumulated_cost + print(f"EXAMPLE_COST: {cost:.4f}") finally: # Clean up the ACP server subprocess agent.close() +cost = conversation.conversation_stats.get_combined_metrics().accumulated_cost +print(f"\nEXAMPLE_COST: {cost}") print("Done!") ``` -This example does not use an LLM API key directly — the ACP server (Claude Code) handles authentication on its own. +This example uses ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY environment variables to configure the Claude Code ACP server. ```bash Running the Example -# Ensure Claude Code CLI is authenticated first -# (or set CLAUDE_API_KEY in your environment) +# Set up environment variables (can point to LiteLLM proxy) +export ANTHROPIC_BASE_URL="https://your-proxy.example.com" +export ANTHROPIC_API_KEY="your-api-key" cd software-agent-sdk uv run python examples/01_standalone_sdk/40_acp_agent_example.py ``` @@ -10272,12 +10278,20 @@ By default, all agents include `finish` tool and the `think` tool. | Agent | Tools | Description | |--------|-------|-------| -| **default** | `terminal`, `file_editor`, `task_tracker`, `browser_tool_set` | General-purpose agent. Used as the fallback when no agent name is specified. | -| **default cli mode** | `terminal`, `file_editor`, `task_tracker` | Same as `default` but without browser tools (used in CLI mode). | -| **explore** | `terminal` | Read-only codebase exploration agent. Finds files, searches code, reads source — never creates or modifies anything. | -| **bash** | `terminal` | Command execution specialist. Runs shell commands, builds, tests, and git operations. | +| **general-purpose** | `terminal`, `file_editor`, `task_tracker` | General-purpose agent for tasks requiring a combination of capabilities. Used as the fallback when no agent name is specified. | +| **code-explorer** | `terminal` | Read-only codebase exploration agent. Finds files, searches code, reads source — never creates or modifies anything. | +| **bash-runner** | `terminal` | Command execution specialist. Runs shell commands, builds, tests, linters, and git operations. Returns concise reports instead of raw output. | +| **web-researcher** | `browser_tool_set` + MCP (`fetch`, `tavily`) | Web research specialist. Searches the web, navigates documentation, and extracts information from URLs. | -In CLI mode, the `default` agent (with browser tools) is replaced by the `default cli mode` agent. In non-CLI mode, `default cli mode` is filtered out. +When `enable_browser=False`, browser-dependent agents like `web-researcher` are not registered. + + +**Deprecated names:** The following legacy names are deprecated (since v1.12.0) and will be removed in version 2.0.0: +- `default` → use `general-purpose` +- `default cli mode` → use `general-purpose` +- `explore` → use `code-explorer` +- `bash` → use `bash-runner` + ### Registering Built-in Sub-Agents @@ -10286,11 +10300,11 @@ Call `register_builtins_agents()` to register all built-in sub-agents. This is t ```python icon="python" focus={3-4, 6-7} from openhands.tools.preset.default import register_builtins_agents -# Register built-in sub-agents (default, explore, bash) +# Register all built-in sub-agents (including web-researcher) register_builtins_agents() -# Or in CLI mode (swaps default for default cli mode — no browser) -register_builtins_agents(cli_mode=True) +# Or without browser-dependent agents (excludes web-researcher) +register_builtins_agents(enable_browser=False) ``` @@ -17121,8 +17135,8 @@ jobs: # - one model will be randomly selected per review llm-model: anthropic/claude-sonnet-4-5-20250929 llm-base-url: '' - # Review style: roasted (other option: standard) - review-style: roasted + # [DEPRECATED] review-style is no longer used; standard and roasted are merged + # review-style: roasted # Extensions version to use (version tag or branch name) extensions-version: main # Secrets @@ -17136,7 +17150,7 @@ jobs: |-------|-------------|----------|---------| | `llm-model` | LLM model to use | Yes | - | | `llm-base-url` | LLM base URL (optional) | No | `''` | -| `review-style` | Review style: 'standard' or 'roasted' | No | `roasted` | +| `review-style` | **[DEPRECATED]** Previously chose between `standard` and `roasted`. Now ignored — the styles have been merged. | No | `roasted` | | `extensions-version` | Git ref for extensions (tag, branch, or commit SHA) | No | `main` | | `extensions-repo` | Extensions repository (owner/repo) | No | `OpenHands/extensions` | | `llm-api-key` | LLM API key | Yes | - | @@ -17147,8 +17161,8 @@ jobs: - [PR Review Plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review) - Complete plugin with scripts and skills (in extensions repo) - [Agent Script](https://github.com/OpenHands/extensions/blob/main/plugins/pr-review/scripts/agent_script.py) - Main review agent script - [Prompt Template](https://github.com/OpenHands/extensions/blob/main/plugins/pr-review/scripts/prompt.py) - Review prompt template -- [Workflow File](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/03_github_workflows/02_pr_review/workflow.yml) - Example workflow -- [Composite Action](https://github.com/OpenHands/software-agent-sdk/blob/main/.github/actions/pr-review/action.yml) - Reusable GitHub Action +- [Example Workflow](https://github.com/OpenHands/extensions/blob/main/plugins/pr-review/workflows/pr-review-by-openhands.yml) - Example workflow +- [Composite Action](https://github.com/OpenHands/extensions/blob/main/plugins/pr-review/action.yml) - Reusable GitHub Action ### TODO Management Source: https://docs.openhands.dev/sdk/guides/github-workflows/todo-management.md @@ -27800,275 +27814,790 @@ Key aspects of the plugin system: 4. Initialization: Plugins are initialized asynchronously when the runtime starts and are accessible to actions 5. Usage: Plugins extend capabilities (e.g., Jupyter for IPython cells); the server exposes any web endpoints (ports) via host port mapping -### Hooks -Source: https://docs.openhands.dev/openhands/usage/customization/hooks.md - -## Overview - -Hooks let you run custom shell scripts at key moments during an OpenHands session. They are configured per-repository -via a `.openhands/hooks.json` file and work across **Cloud**, **CLI**, and **local GUI** setups. The hooks format is -compatible with [Claude Code hooks](https://code.claude.com/docs/en/hooks), so you can reuse hook scripts across both tools. +### Creating Automations +Source: https://docs.openhands.dev/openhands/usage/automations/creating-automations.md -Common use cases include: -- **Blocking dangerous commands** before execution (e.g., preventing `rm -rf /`) -- **Enforcing quality gates** before the agent finishes (e.g., requiring linting or tests to pass) -- **Logging and auditing** tool usage for compliance -- **Injecting context** into user prompts (e.g., appending git status) + +**Beta Feature**: Automations is currently in beta and available for **OpenHands Cloud** and **OpenHands Enterprise** users only. + -## Hook Types +The easiest way to create an automation is to ask OpenHands directly. The Automation Skill handles all the details—you just describe what you want. -| Hook | When It Runs | Can Block? | -|------|-------------|------------| -| `PreToolUse` | Before the agent executes a tool | Yes | -| `PostToolUse` | After a tool finishes executing | No | -| `UserPromptSubmit` | Before a user message is processed | Yes | -| `Stop` | When the agent tries to finish | Yes | -| `SessionStart` | When a conversation begins | No | -| `SessionEnd` | When a conversation ends | No | +## Prompt vs Plugin Automations -**Blocking** means the hook can prevent the operation from proceeding. For example, a `Stop` hook can force the agent -to keep working if linting checks haven't passed yet. Note that hooks with `"async": true` run in the background and -can never block, regardless of event type. +There are two types of automations: -## Quick Start + + + Most automations are prompt-based. Just describe the task in natural language: - - - ### Create the Hooks Directory + ``` + Create an automation called "Daily Standup Summary" that runs every weekday + at 9 AM Eastern. It should check our GitHub repo for PRs merged yesterday + and post a summary to #engineering on Slack. + ``` - In your repository root, create the `.openhands` directory if it doesn't already exist: + This is all you need for reports, monitoring, data syncs, and most common tasks. + + + For specialized capabilities, include one or more plugins from the [OpenHands extensions repository](https://github.com/OpenHands/extensions): - ```bash - mkdir -p .openhands/hooks ``` - - - ### Write a Hook Script + Create an automation using the code-review plugin that runs every weekday + at 9 AM. It should review any Python files changed in the last 24 hours. + ``` - Create a shell script for your hook. For example, a Stop hook that requires linting to pass before the agent can finish: + Plugins provide additional skills, MCP configurations, or custom commands that extend what the automation can do. + + - ```bash .openhands/hooks/lint_check.sh - #!/bin/bash - # Stop hook: Don't let the agent stop if linting fails +The agent will: +1. Confirm the automation name and what it does +2. Set up the schedule you requested +3. Create the automation (with plugins if specified) - cd "$OPENHANDS_PROJECT_DIR" +Once created, it runs automatically on schedule. - # Run your linter - if ! npm run lint 2>&1; then - echo '{"decision": "deny", "reason": "Linting failed. Please fix the issues before finishing."}' - exit 2 - fi +## What to Include in Your Request - exit 0 - ``` +When asking OpenHands to create an automation, include: - Make the script executable: +- **What it should do**: Describe the task clearly +- **When it should run**: Daily, weekly, every hour, etc. +- **Timezone** (optional): Defaults to UTC if not specified +- **Name** (optional): The agent can suggest one based on your description +- **Plugins** (optional): Mention specific plugins if you need extended capabilities - ```bash - chmod +x .openhands/hooks/lint_check.sh - ``` - - - ### Create `hooks.json` +## Writing Good Automation Prompts - Create `.openhands/hooks.json` to register your hooks: +The prompt is what the AI agent executes each time the automation runs. Write it like you're giving instructions to a capable assistant. - ```json .openhands/hooks.json - { - "stop": [ - { - "matcher": "*", - "hooks": [ - { - "command": ".openhands/hooks/lint_check.sh", - "timeout": 120 - } - ] - } - ] - } - ``` - - - ### Commit to Your Repository +### Be Specific - ```bash - git add .openhands/hooks.json .openhands/hooks/ - git commit -m "Add OpenHands hooks" + + + ``` + Generate a report + ``` + + + ``` + Generate a weekly status report that: + 1. Lists all GitHub PRs merged in the last 7 days + 2. Summarizes open issues by priority + 3. Formats everything as markdown + 4. Posts to the #team-updates Slack channel ``` + + - The next time OpenHands works on your repository, the hooks will be active automatically. - - +### Include Where to Send Results -## Configuration Reference +Tell the automation what to do with its output: -### `hooks.json` Format +- "Post to the #alerts Slack channel" (requires [Slack MCP](/openhands/usage/cloud/slack-installation)) +- "Save to `reports/weekly-summary.md`" +- "Create a GitHub issue with the findings" (automatic if you logged in with GitHub) +- "Send a message via the configured notification service" -The `.openhands/hooks.json` file maps hook event types to matchers and commands using `snake_case` keys: + +Git providers you logged in with (GitHub, GitLab, Bitbucket) are automatically available. Other services like Slack require [MCP configuration](/openhands/usage/settings/mcp-settings). + -```json -{ - "pre_tool_use": [ - { - "matcher": "terminal", - "hooks": [ - { "command": ".openhands/hooks/block_dangerous.sh", "timeout": 10 } - ] - } - ], - "stop": [ - { - "matcher": "*", - "hooks": [ - { "command": ".openhands/hooks/require_tests.sh", "timeout": 120 } - ] - } - ] -} -``` +### Specify Error Handling -### Claude Code Compatibility +For monitoring tasks, explain what should happen when things go wrong: -The hooks format is compatible with [Claude Code hooks](https://code.claude.com/docs/en/hooks). PascalCase event -keys (e.g., `PreToolUse`) and the `{"hooks": {...}}` wrapper are both supported, so you can share hook scripts -between the two tools. The main differences are the file location (`.openhands/hooks.json` vs `.claude/settings.json`) -and tool names (e.g., `terminal` vs `Bash`). +``` +Check the health endpoint at https://api.example.com/health. +If it returns anything other than 200 OK, send an alert to #ops +with the status code and response body. +If it's healthy, just log success without alerting. +``` -### Hook Definition Fields +## What Your Automation Can Access -| Field | Type | Default | Description | -|-------|------|---------|-------------| -| `type` | string | `"command"` | Hook type (currently only `"command"` is supported) | -| `command` | string | *(required)* | Shell command or path to script to execute | -| `timeout` | integer | `60` | Maximum execution time in seconds | -| `async` | boolean | `false` | Run in background without waiting for result | +Each automation runs in a full OpenHands sandbox with: -### Matcher Patterns +- **Terminal access**: Run any bash commands +- **File operations**: Create, read, and modify files +- **Your LLM**: Uses your configured model from settings +- **Your secrets**: Access API keys stored in Settings > Secrets +- **MCP integrations**: Use your configured MCP servers +- **Network access**: Make HTTP requests, connect to APIs +- **Git provider access**: Tokens from your Cloud login (GitHub, GitLab, or Bitbucket) are automatically included -The `matcher` field determines which tools trigger the hook (only relevant for `PreToolUse` and `PostToolUse`): +## Schedules -| Pattern | Description | Example | -|---------|-------------|---------| -| `*` | Matches all tools | `"matcher": "*"` | -| Exact name | Matches a specific tool | `"matcher": "terminal"` | -| Regex | Auto-detected or wrapped in `/` | `"matcher": "/terminal\|browser/"` | +Tell OpenHands when you want the automation to run in plain language: -For hooks that aren't tool-specific (`Stop`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`), set the matcher to `"*"` or omit it. +- "every weekday at 9 AM" +- "every Monday morning" +- "hourly" +- "every 15 minutes" +- "first day of each month" +- "twice a day at 9 AM and 5 PM" -## How Hook Scripts Work +The agent converts this to the appropriate cron schedule. -### Input + +If you're familiar with cron expressions, you can specify them directly: "Run on cron schedule `0 9 * * 1-5`" + -Hook scripts receive a JSON payload on **stdin** with details about the event: +## After Creation -```json -{ - "event_type": "PreToolUse", - "tool_name": "terminal", - "tool_input": { "command": "rm -rf /tmp/data" }, - "session_id": "abc-123", - "working_dir": "/workspace" -} -``` +Once your automation is created: - -Additional fields may be present depending on the hook event type (e.g., `tool_response` for PostToolUse, `message` for UserPromptSubmit). - +- **It starts enabled** by default and will run on the next scheduled time +- **You can view past runs** in the OpenHands UI +- **Each run creates a conversation** you can review or continue +- **You can disable, update, or delete it** anytime (see [Managing Automations](/openhands/usage/automations/managing-automations)) -The following **environment variables** are also set: +## Next Steps -| Variable | Description | -|----------|-------------| -| `OPENHANDS_EVENT_TYPE` | The hook event type (e.g., `PreToolUse`) | -| `OPENHANDS_TOOL_NAME` | The tool being used (for tool hooks) | -| `OPENHANDS_PROJECT_DIR` | The project working directory | -| `OPENHANDS_SESSION_ID` | The current session ID | +- [Automations overview & examples](/openhands/usage/automations/overview) +- [Manage your automations](/openhands/usage/automations/managing-automations) -### Output +### Managing Automations +Source: https://docs.openhands.dev/openhands/usage/automations/managing-automations.md -Hook scripts communicate results through **exit codes** and optional **JSON on stdout**: + +**Beta Feature**: Automations is currently in beta and available for **OpenHands Cloud** and **OpenHands Enterprise** users only. + -**Exit codes:** -- `0` - Success. The operation proceeds normally. -- `2` - Block. The operation is denied. -- Any other code - Error. The operation proceeds, but the error is logged. +You can manage your automations by asking OpenHands directly—just like you created them. -**JSON output (optional):** +## Viewing Your Automations -```json -{ - "decision": "deny", - "reason": "rm -rf commands are blocked for safety", - "additionalContext": "Extra context to pass to the agent" -} +``` +List my automations ``` -| Field | Description | -|-------|-------------| -| `decision` | `"allow"` or `"deny"` - overrides the exit code | -| `reason` | Human-readable explanation shown in the UI | -| `additionalContext` | Additional context injected into the agent's prompt | +``` +Show me the details of the "Daily Report" automation +``` -## Real-World Example +## Enabling and Disabling -The OpenHands Agent SDK repository uses a Stop hook that runs pre-commit checks, targeted pytest suites, and GitHub CI -status verification before allowing the agent to finish: +Pause an automation without deleting it: -- [`.openhands/hooks.json`](https://github.com/OpenHands/software-agent-sdk/blob/main/.openhands/hooks.json) - hook configuration -- [`.openhands/hooks/on_stop.sh`](https://github.com/OpenHands/software-agent-sdk/blob/main/.openhands/hooks/on_stop.sh) - the stop hook script +``` +Disable the "Daily Report" automation +``` -This hook setup prevents the agent from finishing if pre-commit, tests, or CI are failing. +Turn it back on: -## More Examples +``` +Enable the "Daily Report" automation +``` -### Block Dangerous Commands (PreToolUse) + +Disabling an automation keeps all its settings intact. Use this when you want to temporarily stop runs without losing your configuration. + -Prevent the agent from running destructive shell commands: +## Changing the Schedule -```bash .openhands/hooks/block_dangerous.sh -#!/bin/bash -# Read JSON input from stdin -input=$(cat) -command=$(echo "$input" | jq -r '.tool_input.command // ""') +``` +Change the "Daily Report" automation to run at 10 AM instead of 9 AM +``` -if [[ "$command" =~ "rm -rf" ]]; then - echo '{"decision": "deny", "reason": "rm -rf commands are blocked for safety"}' - exit 2 -fi +``` +Update the "Weekly Cleanup" automation to run on Sundays at 2 AM UTC +``` -exit 0 +## Running Manually + +Test an automation or run it outside its normal schedule: + +``` +Trigger the "Daily Report" automation now ``` -```json .openhands/hooks.json -{ - "pre_tool_use": [ - { - "matcher": "terminal", - "hooks": [{ "command": ".openhands/hooks/block_dangerous.sh", "timeout": 10 }] - } - ] -} +``` +Run the "Health Check" automation immediately ``` -### Enforce Linting Before Stop +This is useful for: +- Testing a newly created automation +- Running a report on-demand +- Debugging issues -Don't let the agent finish until linting passes - this is what prevents linting errors from being committed: +## Viewing Past Runs -```bash .openhands/hooks/lint_on_stop.sh -#!/bin/bash -cd "$OPENHANDS_PROJECT_DIR" +``` +Show me recent runs of the "Daily Report" automation +``` -# Run pre-commit or your linter -if ! pre-commit run --all-files 2>&1; then - echo '{"decision": "deny", "reason": "Linting failed. Fix the issues before finishing."}' - exit 2 -fi +Each run creates a conversation that automatically appears in your conversations list. You can: +- **View in the OpenHands UI** to see what happened +- **Continue** if you want to interact with the sandbox +- **Debug** if something went wrong -exit 0 -``` + +Automations are user-scoped, so all your automation runs appear alongside your regular conversations. Look for them in your conversations list after each scheduled run. + -```json .openhands/hooks.json +### Run Statuses + +- **Pending**: Scheduled, waiting to start +- **Running**: Currently executing +- **Completed**: Finished successfully +- **Failed**: Something went wrong—check the run details + +## Deleting Automations + +``` +Delete the "Old Report" automation +``` + + +Deleting an automation is permanent. Consider disabling it instead if you might need it later. + + +## Next Steps + +- [Automations overview & examples](/openhands/usage/automations/overview) +- [Create new automations](/openhands/usage/automations/creating-automations) + +### Automations Overview +Source: https://docs.openhands.dev/openhands/usage/automations/overview.md + + +**Beta Feature**: Automations is currently in beta and available for **OpenHands Cloud** and **OpenHands Enterprise** users only. + + +Automations let you schedule AI-powered tasks that run automatically—daily reports, health checks, data syncs, and more. Each automation runs a full OpenHands conversation on your chosen schedule, with access to your LLM settings, stored secrets, and integrations. + +Your git provider credentials are automatically available—if you logged into OpenHands Cloud with GitHub, GitLab, or Bitbucket, that access is included by default. + +## What Can Automations Do? + +- **Generate reports**: Daily standups, weekly summaries, or monthly metrics +- **Monitor systems**: Check API health, SSL certificates, or uptime +- **Sync data**: Pull from external APIs, update spreadsheets, or refresh dashboards +- **Maintain code**: Run dependency checks, security scans, or cleanup tasks +- **Send notifications**: Post updates to Slack, create GitHub issues, or send alerts + + +Automations can only interact with services you've configured access to. For example, posting to Slack requires the [Slack MCP integration](/openhands/usage/cloud/slack-installation). Git providers you logged in with (GitHub, GitLab, Bitbucket) are automatically available. + + +## Two Types of Automations + +When you ask OpenHands to create an automation, you can choose between: + +- **Prompt-based** (most common): Describe what the automation should do in natural language. Great for reports, monitoring, data syncs, and most tasks. + +- **Plugin-based**: Include one or more plugins that provide additional skills or capabilities. Use this when you need specialized tools from the [OpenHands extensions repository](https://github.com/OpenHands/extensions). + +Both types are created the same way—just describe what you want and OpenHands will guide you through the setup. + +## Creating Your First Automation + +Just ask OpenHands to create one: + +``` +Create an automation that runs every Monday at 9 AM and summarizes +our open GitHub issues, then posts the summary to #engineering on Slack. +``` + +For plugin-based automations, mention the plugin: + +``` +Create an automation using the code-review plugin that runs daily +and reviews any Python files changed in the last 24 hours. +``` + +The Automation Skill guides you through: +1. Naming your automation +2. Setting the schedule +3. Choosing a timezone +4. Confirming the task description (and plugins, if any) + +That's it—the system handles the rest. + +## How It Works + +When your automation runs: +1. A fresh sandbox is created +2. The OpenHands agent executes your prompt +3. The conversation is saved so you can review it later +4. You can even continue the conversation if needed + +Automations are user-scoped—each automation and its runs belong to you. Conversations created by your automations automatically appear in your conversations list, just like any other conversation you start. + +Your automation has access to everything a normal OpenHands conversation does: terminal, file editing, your configured LLM, stored secrets, and MCP integrations. Git provider tokens from your Cloud login (GitHub, GitLab, or Bitbucket) are automatically included. + +## Getting Started + +Before creating automations, complete this one-time setup: + +### 1. Create an OpenHands API Key + +Go to [Settings > API Keys](https://app.all-hands.dev/settings/api-keys) and create a new API key. + +### 2. Save the API Key as a Secret + +Copy the API key value and go to [Settings > Secrets](https://app.all-hands.dev/settings/secrets). Create a new secret with: +- **Name**: `OPENHANDS_API_KEY` +- **Value**: Your API key from step 1 + +This allows the Automation Skill to create and manage automations on your behalf. + +### 3. Start a Conversation + +Open a new conversation in OpenHands and ask it to create an automation: + +``` +Create an automation that runs every Monday at 9 AM and summarizes +our open GitHub issues, then posts to #engineering on Slack. +``` + +You can also list existing automations, enable/disable them, or trigger manual runs—all through conversation. + +## Prerequisites + +- **OpenHands Cloud or Enterprise account** (not available in open-source) +- **Configured LLM** in your [settings](https://app.all-hands.dev/settings) +- **Stored secrets** (optional) for any additional API keys your automations need (e.g., Slack tokens) + +--- + +## Use Case Automations + +{/* BEGIN:use-case-automations — auto-generated from use-case frontmatter */} + +Each use case has a ready-to-use automation prompt. Click a card to see the full instructions. + + + + Review open PRs daily for bugs, style issues, and security concerns. + + + Check for outdated packages weekly and report available updates. + + + Monitor API health, analyze errors, and alert your team automatically. + + + Scan dependencies for known CVEs, find hardcoded secrets, and alert your team on a schedule. + + + +{/* END:use-case-automations */} + +## General Automations + +Ready-to-use templates for common operational tasks. + + + + Summarize PRs opened, merged, and reviewed daily. + + + Generate weekly GitHub activity and issue reports. + + + Check SSL expiry dates and alert before they lapse. + + + Remove stale temporary files and report what was cleaned. + + + Verify database backups exist and are recent. + + + Pull analytics data periodically and flag big changes. + + + +### Daily GitHub Summary + +``` +Create an automation called "Daily GitHub Summary" that runs every weekday at 9 AM Eastern. + +It should: +1. Summarize PRs opened, merged, and reviewed in the last 24 hours +2. List any PRs that have been open for more than 3 days +3. Format as a clean markdown summary +4. Post to the #engineering Slack channel +``` + +### Weekly Metrics Report + +``` +Create an automation called "Weekly Metrics" that runs every Monday at 9 AM. + +It should generate a weekly report covering: +- GitHub activity (commits, PRs merged, issues closed) +- Open issues grouped by priority +- PRs awaiting review for more than 3 days + +Save the report to weekly-reports/ with the current date in the filename. +``` + +### SSL Certificate Monitor + +``` +Create an automation called "SSL Monitor" that runs daily at 8 AM. + +It should check SSL certificate expiry for these domains: +- api.example.com +- app.example.com +- www.example.com + +If any certificate expires within 30 days, alert #devops with the domain and days remaining. +``` + +### Weekly Cleanup + +``` +Create an automation called "Weekly Cleanup" that runs every Sunday at 2 AM UTC. + +It should: +1. Find and delete temporary files older than 7 days +2. Create a summary of what was removed (file paths and sizes) +3. Post the cleanup summary to #ops +``` + +### Backup Verification + +``` +Create an automation called "Backup Check" that runs daily at 6 AM. + +It should verify that database backups exist and were created within the last 24 hours. +List the most recent backup for each database with its timestamp and size. +If any backup is missing or stale, send an urgent alert to #alerts. +``` + +### Analytics Data Sync + +``` +Create an automation called "Analytics Sync" that runs every 6 hours. + +It should: +1. Pull the latest data from our analytics API +2. Update metrics.json with the new data +3. Calculate week-over-week changes for key metrics +4. If any metric changed by more than 20%, flag it in a summary message +``` + +--- + +## Tips for Writing Good Prompts + + + + Tell the automation exactly what to do: + - "Check X and if Y, then Z" + - "Generate a report and save it to..." + - "Fetch data, compare with expected values, and report differences" + + + Specify what should happen when things go wrong: + - "If the response is not 200..." + - "If any backup is missing..." + - "If the check fails, alert the team" + + + Be explicit about outputs: + - "Post to the #channel Slack channel" + - "Save to reports/ with the current date" + - "Create a GitHub issue with the findings" + + + +## Next Steps + +- [Creating Automations](/openhands/usage/automations/creating-automations) — More details on writing prompts +- [Managing Automations](/openhands/usage/automations/managing-automations) — Update, disable, or delete automations +- [Use Cases Overview](/openhands/usage/use-cases/overview) — Explore the full use case guides behind these automations + +### Hooks +Source: https://docs.openhands.dev/openhands/usage/customization/hooks.md + +## Overview + +Hooks let you run custom shell scripts at key moments during an OpenHands session. They are configured per-repository +via a `.openhands/hooks.json` file and work across **Cloud**, **CLI**, and **local GUI** setups. The hooks format is +compatible with [Claude Code hooks](https://code.claude.com/docs/en/hooks), so you can reuse hook scripts across both tools. + +Common use cases include: +- **Blocking dangerous commands** before execution (e.g., preventing `rm -rf /`) +- **Enforcing quality gates** before the agent finishes (e.g., requiring linting or tests to pass) +- **Logging and auditing** tool usage for compliance +- **Injecting context** into user prompts (e.g., appending git status) + +## Hook Types + +| Hook | When It Runs | Can Block? | +|------|-------------|------------| +| `PreToolUse` | Before the agent executes a tool | Yes | +| `PostToolUse` | After a tool finishes executing | No | +| `UserPromptSubmit` | Before a user message is processed | Yes | +| `Stop` | When the agent tries to finish | Yes | +| `SessionStart` | When a conversation begins | No | +| `SessionEnd` | When a conversation ends | No | + +**Blocking** means the hook can prevent the operation from proceeding. For example, a `Stop` hook can force the agent +to keep working if linting checks haven't passed yet. Note that hooks with `"async": true` run in the background and +can never block, regardless of event type. + +## Quick Start + + + + ### Create the Hooks Directory + + In your repository root, create the `.openhands` directory if it doesn't already exist: + + ```bash + mkdir -p .openhands/hooks + ``` + + + ### Write a Hook Script + + Create a shell script for your hook. For example, a Stop hook that requires linting to pass before the agent can finish: + + ```bash .openhands/hooks/lint_check.sh + #!/bin/bash + # Stop hook: Don't let the agent stop if linting fails + + cd "$OPENHANDS_PROJECT_DIR" + + # Run your linter + if ! npm run lint 2>&1; then + echo '{"decision": "deny", "reason": "Linting failed. Please fix the issues before finishing."}' + exit 2 + fi + + exit 0 + ``` + + Make the script executable: + + ```bash + chmod +x .openhands/hooks/lint_check.sh + ``` + + + ### Create `hooks.json` + + Create `.openhands/hooks.json` to register your hooks: + + ```json .openhands/hooks.json + { + "stop": [ + { + "matcher": "*", + "hooks": [ + { + "command": ".openhands/hooks/lint_check.sh", + "timeout": 120 + } + ] + } + ] + } + ``` + + + ### Commit to Your Repository + + ```bash + git add .openhands/hooks.json .openhands/hooks/ + git commit -m "Add OpenHands hooks" + ``` + + The next time OpenHands works on your repository, the hooks will be active automatically. + + + +## Configuration Reference + +### `hooks.json` Format + +The `.openhands/hooks.json` file maps hook event types to matchers and commands using `snake_case` keys: + +```json +{ + "pre_tool_use": [ + { + "matcher": "terminal", + "hooks": [ + { "command": ".openhands/hooks/block_dangerous.sh", "timeout": 10 } + ] + } + ], + "stop": [ + { + "matcher": "*", + "hooks": [ + { "command": ".openhands/hooks/require_tests.sh", "timeout": 120 } + ] + } + ] +} +``` + +### Claude Code Compatibility + +The hooks format is compatible with [Claude Code hooks](https://code.claude.com/docs/en/hooks). PascalCase event +keys (e.g., `PreToolUse`) and the `{"hooks": {...}}` wrapper are both supported, so you can share hook scripts +between the two tools. The main differences are the file location (`.openhands/hooks.json` vs `.claude/settings.json`) +and tool names (e.g., `terminal` vs `Bash`). + +### Hook Definition Fields + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `type` | string | `"command"` | Hook type (currently only `"command"` is supported) | +| `command` | string | *(required)* | Shell command or path to script to execute | +| `timeout` | integer | `60` | Maximum execution time in seconds | +| `async` | boolean | `false` | Run in background without waiting for result | + +### Matcher Patterns + +The `matcher` field determines which tools trigger the hook (only relevant for `PreToolUse` and `PostToolUse`): + +| Pattern | Description | Example | +|---------|-------------|---------| +| `*` | Matches all tools | `"matcher": "*"` | +| Exact name | Matches a specific tool | `"matcher": "terminal"` | +| Regex | Auto-detected or wrapped in `/` | `"matcher": "/terminal\|browser/"` | + +For hooks that aren't tool-specific (`Stop`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`), set the matcher to `"*"` or omit it. + +## How Hook Scripts Work + +### Input + +Hook scripts receive a JSON payload on **stdin** with details about the event: + +```json +{ + "event_type": "PreToolUse", + "tool_name": "terminal", + "tool_input": { "command": "rm -rf /tmp/data" }, + "session_id": "abc-123", + "working_dir": "/workspace" +} +``` + + +Additional fields may be present depending on the hook event type (e.g., `tool_response` for PostToolUse, `message` for UserPromptSubmit). + + +The following **environment variables** are also set: + +| Variable | Description | +|----------|-------------| +| `OPENHANDS_EVENT_TYPE` | The hook event type (e.g., `PreToolUse`) | +| `OPENHANDS_TOOL_NAME` | The tool being used (for tool hooks) | +| `OPENHANDS_PROJECT_DIR` | The project working directory | +| `OPENHANDS_SESSION_ID` | The current session ID | + +### Output + +Hook scripts communicate results through **exit codes** and optional **JSON on stdout**: + +**Exit codes:** +- `0` - Success. The operation proceeds normally. +- `2` - Block. The operation is denied. +- Any other code - Error. The operation proceeds, but the error is logged. + +**JSON output (optional):** + +```json +{ + "decision": "deny", + "reason": "rm -rf commands are blocked for safety", + "additionalContext": "Extra context to pass to the agent" +} +``` + +| Field | Description | +|-------|-------------| +| `decision` | `"allow"` or `"deny"` - overrides the exit code | +| `reason` | Human-readable explanation shown in the UI | +| `additionalContext` | Additional context injected into the agent's prompt | + +## Real-World Example + +The OpenHands Agent SDK repository uses a Stop hook that runs pre-commit checks, targeted pytest suites, and GitHub CI +status verification before allowing the agent to finish: + +- [`.openhands/hooks.json`](https://github.com/OpenHands/software-agent-sdk/blob/main/.openhands/hooks.json) - hook configuration +- [`.openhands/hooks/on_stop.sh`](https://github.com/OpenHands/software-agent-sdk/blob/main/.openhands/hooks/on_stop.sh) - the stop hook script + +This hook setup prevents the agent from finishing if pre-commit, tests, or CI are failing. + +## More Examples + +### Block Dangerous Commands (PreToolUse) + +Prevent the agent from running destructive shell commands: + +```bash .openhands/hooks/block_dangerous.sh +#!/bin/bash +# Read JSON input from stdin +input=$(cat) +command=$(echo "$input" | jq -r '.tool_input.command // ""') + +if [[ "$command" =~ "rm -rf" ]]; then + echo '{"decision": "deny", "reason": "rm -rf commands are blocked for safety"}' + exit 2 +fi + +exit 0 +``` + +```json .openhands/hooks.json +{ + "pre_tool_use": [ + { + "matcher": "terminal", + "hooks": [{ "command": ".openhands/hooks/block_dangerous.sh", "timeout": 10 }] + } + ] +} +``` + +### Enforce Linting Before Stop + +Don't let the agent finish until linting passes - this is what prevents linting errors from being committed: + +```bash .openhands/hooks/lint_on_stop.sh +#!/bin/bash +cd "$OPENHANDS_PROJECT_DIR" + +# Run pre-commit or your linter +if ! pre-commit run --all-files 2>&1; then + echo '{"decision": "deny", "reason": "Linting failed. Fix the issues before finishing."}' + exit 2 +fi + +exit 0 +``` + +```json .openhands/hooks.json { "stop": [ { @@ -29652,7 +30181,7 @@ The Software Agent SDK provides composite GitHub Actions for common workflows: - **[Automated PR Review](/openhands/usage/use-cases/code-review)** - Automatically review pull requests with inline comments - **[SDK GitHub Workflows Guide](/sdk/guides/github-workflows/pr-review)** - Build custom GitHub workflows with the SDK -For example, to set up automated PR reviews, see the [Automated Code Review](/openhands/usage/use-cases/code-review) guide which uses the real `OpenHands/software-agent-sdk/.github/actions/pr-review` composite action. +For example, to set up automated PR reviews, see the [Automated Code Review](/openhands/usage/use-cases/code-review) guide which uses the `OpenHands/extensions/plugins/pr-review` composite action. ### What You Can Automate @@ -33029,7 +33558,7 @@ The PR review workflow uses the OpenHands Software Agent SDK to analyze your cod - `openhands-agent` is requested as a reviewer 2. **Analysis**: The agent receives the complete PR diff and uses two skills: - - [**`/codereview`**](https://github.com/OpenHands/extensions/tree/main/skills/codereview) or [**`/codereview-roasted`**](https://github.com/OpenHands/extensions/tree/main/skills/codereview-roasted): Analyzes code for quality, security, and best practices + - [**`/codereview`**](https://github.com/OpenHands/extensions/tree/main/skills/code-review): Analyzes code for quality, security, data structures, and best practices with a focus on simplicity and pragmatism - [**`/github-pr-review`**](https://github.com/OpenHands/extensions/tree/main/skills/github-pr-review): Posts structured inline comments via the GitHub API 3. **Output**: Review comments are posted directly on the PR with: @@ -33037,15 +33566,6 @@ The PR review workflow uses the OpenHands Software Agent SDK to analyze your cod - Specific line references - Actionable suggestions with code examples -### Review Styles - -Choose between two review styles: - -| Style | Description | Best For | -|-------|-------------|----------| -| **Standard** ([`/codereview`](https://github.com/OpenHands/extensions/tree/main/skills/codereview)) | Pragmatic, constructive feedback focusing on code quality, security, and best practices | Day-to-day code reviews | -| **Roasted** ([`/codereview-roasted`](https://github.com/OpenHands/extensions/tree/main/skills/codereview-roasted)) | Linus Torvalds-style brutally honest review emphasizing "good taste", data structures, and simplicity | Critical code paths, learning opportunities | - ## Quick Start @@ -33074,10 +33594,9 @@ Choose between two review styles: runs-on: ubuntu-latest steps: - name: Run PR Review - uses: OpenHands/software-agent-sdk/.github/actions/pr-review@main + uses: OpenHands/extensions/plugins/pr-review@main with: llm-model: anthropic/claude-sonnet-4-5-20250929 - review-style: standard llm-api-key: ${{ secrets.LLM_API_KEY }} github-token: ${{ secrets.GITHUB_TOKEN }} ``` @@ -33118,7 +33637,7 @@ The workflow uses a reusable composite action from the Software Agent SDK that h |-------|-------------|----------|---------| | `llm-model` | LLM model to use | Yes | - | | `llm-base-url` | LLM base URL (for custom endpoints) | No | `''` | -| `review-style` | Review style: `standard` or `roasted` | No | `roasted` | +| `review-style` | **[DEPRECATED]** Previously chose between `standard` and `roasted`. Now ignored — the styles have been merged. | No | `roasted` | | `extensions-version` | Git ref for extensions (tag, branch, or commit SHA) | No | `main` | | `extensions-repo` | Extensions repository (owner/repo) | No | `OpenHands/extensions` | | `llm-api-key` | LLM API key | Yes | - | @@ -33186,14 +33705,12 @@ Customize the workflow by modifying the action inputs: ```yaml - name: Run PR Review - uses: OpenHands/software-agent-sdk/.github/actions/pr-review@main + uses: OpenHands/extensions/plugins/pr-review@main with: # Change the LLM model llm-model: anthropic/claude-sonnet-4-5-20250929 # Use a custom LLM endpoint llm-base-url: https://your-llm-proxy.example.com - # Switch to "roasted" style for brutally honest reviews - review-style: roasted # Pin to a specific extensions version for stability extensions-version: main # Secrets @@ -33262,10 +33779,30 @@ See real automated reviews in action on the OpenHands Software Agent SDK reposit +## Automate This + +You can schedule daily code reviews using [OpenHands Automations](/openhands/usage/automations/overview). +Copy this prompt into a new conversation to set one up: + +``` +Create an automation called "Daily Code Review" that runs every weekday at 9 AM. + +It should: +1. Find all open PRs that have no reviews yet +2. For each PR, review the diff for bugs, style issues, and security concerns +3. Post a summary of findings as a comment on each PR + +Learn more at https://docs.openhands.dev/openhands/usage/use-cases/code-review +``` + +For inline review comments on every push, use the +[pr-review plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review) +as a GitHub Action instead. + ## Related Resources -- [PR Review Workflow Reference](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/02_pr_review) - Full workflow example and agent script -- [Composite Action](https://github.com/OpenHands/software-agent-sdk/blob/main/.github/actions/pr-review/action.yml) - Reusable GitHub Action for PR reviews +- [PR Review Plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review) - Full workflow example and agent script +- [Composite Action](https://github.com/OpenHands/extensions/blob/main/plugins/pr-review/action.yml) - Reusable GitHub Action for PR reviews - [Software Agent SDK](/sdk/index) - Build your own AI-powered workflows - [GitHub Integration](/openhands/usage/cloud/github-installation) - Set up GitHub integration for OpenHands Cloud - [Skills Documentation](/overview/skills) - Learn more about OpenHands skills @@ -33547,6 +34084,23 @@ Create an upgrade plan that handles all these together, addressing breaking changes in the correct order. ``` +## Automate This + +You can schedule weekly dependency checks using [OpenHands Automations](/openhands/usage/automations/overview). +Copy this prompt into a new conversation to set one up: + +``` +Create an automation called "Dependency Checker" that runs every Monday at 8 AM. + +It should: +1. Scan all package.json and requirements.txt files +2. Check for outdated dependencies +3. Create a report listing packages with available updates (grouped by major/minor/patch) +4. Post the report to #engineering + +Learn more at https://docs.openhands.dev/openhands/usage/use-cases/dependency-upgrades +``` + ## Related Resources - [Vulnerability Remediation](/openhands/usage/use-cases/vulnerability-remediation) - Fix security vulnerabilities @@ -33810,6 +34364,24 @@ Avoid these common incident response mistakes: For production incidents, always follow your organization's incident response procedures. OpenHands is a tool to assist your investigation, not a replacement for proper incident management. +## Automate This + +You can set up continuous health monitoring using [OpenHands Automations](/openhands/usage/automations/overview). +Copy this prompt into a new conversation to set one up: + +``` +Create an automation called "API Health Monitor" that runs every 30 minutes. + +It should check https://api.example.com/health and: +- If the response is not 200 OK, send an alert to #alerts with the status code and response body +- If healthy, just log success without alerting anyone + +Learn more at https://docs.openhands.dev/openhands/usage/use-cases/incident-triage +``` + +For deeper error analysis with Datadog integration, see the +[Datadog debugging workflow](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging). + ## Related Resources - [OpenHands SDK Repository](https://github.com/OpenHands/software-agent-sdk) - Build custom AI agents @@ -33821,6 +34393,8 @@ Source: https://docs.openhands.dev/openhands/usage/use-cases/overview.md OpenHands supports a wide variety of software development tasks. Here are some of the key use cases where OpenHands can help accelerate your work. +Each use case can be implemented in different ways—as a one-off conversation, a scheduled [automation](/openhands/usage/automations/overview), a [plugin](https://github.com/OpenHands/extensions), or through the [SDK](/sdk/index). Pick the approach that fits your workflow. + +## Automate Any Use Case + +Many use cases work best as scheduled automations. Browse ready-to-use automation templates on the [Automations Overview](/openhands/usage/automations/overview) page—just copy a prompt and paste it into OpenHands. + + + + Ready-to-use prompts for vulnerability scans, code reviews, monitoring, and more. + + + Explore plugins in the OpenHands extensions repository for extended capabilities. + + + Build custom workflows and integrations using the Software Agent SDK. + + + ### Spark Migrations Source: https://docs.openhands.dev/openhands/usage/use-cases/spark-migrations.md @@ -34297,6 +34887,27 @@ To build your own vulnerability remediation agent: As agent capabilities continue to evolve, an increasing number of repetitive and time-consuming security tasks can be automated, enabling developers to focus on higher-level design, innovation, and problem-solving rather than routine maintenance. +## Automate This + +You can run vulnerability scans on a schedule using [OpenHands Automations](/openhands/usage/automations/overview). +Copy this prompt into a new conversation to set one up: + +``` +Create an automation called "Security Scan" that runs daily at 3 AM. + +It should run a security audit: +1. Check for known vulnerabilities in dependencies +2. Scan for hardcoded secrets or API keys +3. Look for common security misconfigurations + +Create a detailed report and alert #security if any high or critical issues are found. + +Learn more at https://docs.openhands.dev/openhands/usage/use-cases/vulnerability-remediation +``` + +You can also use the [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation) +for automated fix PRs alongside the scan. + ## Related Resources - [Vulnerability Fixer Example](https://github.com/OpenHands/vulnerability-fixer) - Full implementation example @@ -35146,54 +35757,199 @@ If a webhook is not installed or has failed, you can reinstall it: from the GitLab UI before using the Reinstall button in OpenHands Cloud. -**Important behaviors:** +**Important behaviors:** + +- The Reinstall button is disabled if the webhook is already installed +- Only one reinstall operation can run at a time +- After a successful reinstall, the button remains disabled to prevent duplicate installations +- If a reinstall fails, the error message is displayed below the status badge +- The resources list automatically refreshes after a reinstall completes + +### Constraints and Limitations + +- The webhook management table only displays resources that are accessible with your connected GitLab token +- Webhook installation requires Admin or Owner permissions on the GitLab project or group + +## Next Steps + +- [Learn about the Cloud UI](/openhands/usage/cloud/cloud-ui). +- [Use the Cloud API](/openhands/usage/cloud/cloud-api) to programmatically interact with OpenHands. + +### Getting Started +Source: https://docs.openhands.dev/openhands/usage/cloud/openhands-cloud.md + +## Accessing OpenHands Cloud + +OpenHands Cloud is the hosted cloud version of OpenHands. To get started with OpenHands Cloud, +visit [app.all-hands.dev](https://app.all-hands.dev). + +You'll be prompted to connect with your GitHub, GitLab or Bitbucket account: + +1. Click `Log in with GitHub`, `Log in with GitLab` or `Log in with Bitbucket`. +2. Review the permissions requested by OpenHands and authorize the application. + - OpenHands will require certain permissions from your account. To read more about these permissions, + you can click the `Learn more` link on the authorization page. +3. Review and accept the `terms of service` and select `Continue`. + +## Next Steps + +Once you've connected your account, you can: + +- [Use OpenHands with your GitHub repositories](/openhands/usage/cloud/github-installation). +- [Use OpenHands with your GitLab repositories](/openhands/usage/cloud/gitlab-installation). +- [Use OpenHands with your Bitbucket repositories](/openhands/usage/cloud/bitbucket-installation). +- [Learn about the Cloud UI](/openhands/usage/cloud/cloud-ui). +- [Install the OpenHands Slack app](/openhands/usage/cloud/slack-installation). + +### Plugin Launcher +Source: https://docs.openhands.dev/openhands/usage/cloud/plugin-launcher.md + +The OpenHands Cloud `https://app.all-hands.dev/launch` route lets you create shareable links that open OpenHands with one or more plugins already selected. + +This is useful for: + +- adding a "Try it" link or badge to a plugin README +- sharing a pre-configured plugin in docs, issues, or Slack +- building internal test pages for plugin development + + + `/launch` is a Cloud route, not a standalone REST endpoint. After the user opens the link and confirms the plugin configuration, OpenHands starts a conversation using the normal V1 conversation flow described in the [Cloud API guide](/openhands/usage/cloud/cloud-api). + + +## Before You Start + +You will need: + +- an OpenHands Cloud account +- a plugin or skill stored in a Git repository +- the repository source, and optionally a branch/tag/commit and subdirectory path + + + Only share plugins and skills from sources you trust. The launch flow asks the user to trust the extension before it runs with the agent secrets configured in their account. + + +## Step 1: Define the Plugin + +Create a JSON array of plugin definitions. Each item uses this shape: + +```json +[ + { + "source": "github:OpenHands/extensions", + "ref": "main", + "repo_path": "plugins/pr-review" + } +] +``` + +The fields are: + +- `source` - where the plugin lives, such as `github:owner/repo` or a Git URL +- `ref` - optional branch, tag, or commit +- `repo_path` - optional subdirectory inside the repository +- `parameters` - optional configuration values that OpenHands shows as editable inputs before launch + + + The same format works for skills. For example, a skill in the OpenHands extensions repo would use `"repo_path": "skills/github"`. + + +## Step 2: Encode the Plugin Definition + +The `plugins` query parameter must be a base64-encoded version of your JSON array. + +```json +[ + { + "source": "github:OpenHands/extensions", + "ref": "main", + "repo_path": "plugins/pr-review" + } +] +``` + +Convert that JSON into base64-encoded text, then use the encoded value as the `plugins` query parameter in your `/launch` URL. + +## Step 3: Add an Optional Starting Message + +If you want the launched conversation to start with a prompt, add a `message` query parameter. + +```text +https://app.all-hands.dev/launch?plugins=W3sic291cmNlIjoiZ2l0aHViOk9wZW5IYW5kcy9leHRlbnNpb25zIiwicmVmIjoibWFpbiIsInJlcG9fcGF0aCI6InBsdWdpbnMvcHItcmV2aWV3In1d&message=/pr-review%20https%3A//github.com/OpenHands/OpenHands/pull/12699 +``` + +In this example: + +- `plugins` loads the `pr-review` plugin from `OpenHands/extensions` +- `message` pre-fills the initial task for the conversation + +## Step 4: Open the Launch URL + +When someone opens the link in OpenHands Cloud: + +1. They sign in if needed. +2. OpenHands shows the plugins or skills from the URL. +3. Any `parameters` values are shown as inputs that the user can review or edit. +4. The user confirms they trust the extension. +5. OpenHands starts the conversation with the selected plugin configuration. + +## Simple Format for Development + +For quick local or staging tests, you can use simpler query parameters instead of base64 encoding: + +```text +https://app.all-hands.dev/launch?plugin_source=github:OpenHands/extensions&plugin_ref=main&plugin_repo_path=plugins/pr-review +``` + +This format is convenient for manual testing, but the encoded `plugins` format is better for production links because it also supports multiple plugins in one URL. + +## Next Steps + +- Use the [Cloud API guide](/openhands/usage/cloud/cloud-api) for authentication and conversation lifecycle details. +- See the [REST API (V1) overview](/openhands/usage/api/v1) for the V1 endpoints behind Cloud conversations. -- The Reinstall button is disabled if the webhook is already installed -- Only one reinstall operation can run at a time -- After a successful reinstall, the button remains disabled to prevent duplicate installations -- If a reinstall fails, the error message is displayed below the status badge -- The resources list automatically refreshes after a reinstall completes +### Jira Data Center Integration (Coming soon...) +Source: https://docs.openhands.dev/openhands/usage/cloud/project-management/jira-dc-integration.md -### Constraints and Limitations +# Jira Data Center Integration -- The webhook management table only displays resources that are accessible with your connected GitLab token -- Webhook installation requires Admin or Owner permissions on the GitLab project or group +## Overview -## Next Steps +The Jira Data Center integration enables you to use OpenHands to automatically implement requirements from Jira tickets. When you create a ticket with clear requirements and acceptance criteria, OpenHands can read the ticket, generate an implementation plan, and create a pull request in your linked repository. -- [Learn about the Cloud UI](/openhands/usage/cloud/cloud-ui). -- [Use the Cloud API](/openhands/usage/cloud/cloud-api) to programmatically interact with OpenHands. +### How It Works -### Getting Started -Source: https://docs.openhands.dev/openhands/usage/cloud/openhands-cloud.md +Once configured, you can request OpenHands to work on a Jira ticket by: -## Accessing OpenHands Cloud +1. **Specify the Repository**: Include the repository location in either: + - The ticket body itself, or + - A comment on the ticket + +2. **Trigger OpenHands**: Activate the agent using one of these methods: + - Add an `openhands` label to the ticket + - Comment with: `@openhands please review these requirements, generate a plan, and then proceed with implementation` -OpenHands Cloud is the hosted cloud version of OpenHands. To get started with OpenHands Cloud, -visit [app.all-hands.dev](https://app.all-hands.dev). +OpenHands will then read the ticket, understand the requirements, and generate a conversation that results in a pull request implementing the requested changes. -You'll be prompted to connect with your GitHub, GitLab or Bitbucket account: +### Example Ticket -1. Click `Log in with GitHub`, `Log in with GitLab` or `Log in with Bitbucket`. -2. Review the permissions requested by OpenHands and authorize the application. - - OpenHands will require certain permissions from your account. To read more about these permissions, - you can click the `Learn more` link on the authorization page. -3. Review and accept the `terms of service` and select `Continue`. +Here's an example of how to structure a Jira ticket for OpenHands: -## Next Steps +**Title:** Add SAML Support -Once you've connected your account, you can: +**Body:** +``` +As an administrator for my web app, I want to configure SAML so I can provide secure access to my system. -- [Use OpenHands with your GitHub repositories](/openhands/usage/cloud/github-installation). -- [Use OpenHands with your GitLab repositories](/openhands/usage/cloud/gitlab-installation). -- [Use OpenHands with your Bitbucket repositories](/openhands/usage/cloud/bitbucket-installation). -- [Learn about the Cloud UI](/openhands/usage/cloud/cloud-ui). -- [Install the OpenHands Slack app](/openhands/usage/cloud/slack-installation). +GitHub repository: AcmeCo/WebApp -### Jira Data Center Integration (Coming soon...) -Source: https://docs.openhands.dev/openhands/usage/cloud/project-management/jira-dc-integration.md +AC: +- Verify an administrator can configure SAML settings +- Verify an end user can authenticate via SAML +``` -# Jira Data Center Integration +After creating this ticket, you can either add the `openhands` label or comment with `@openhands please review these requirements, generate a plan, and then proceed with implementation` to start the automation process. + +--- ## Platform Configuration @@ -35320,6 +36076,45 @@ Source: https://docs.openhands.dev/openhands/usage/cloud/project-management/jira # Jira Cloud Integration +## Overview + +The Jira Cloud integration enables you to use OpenHands to automatically implement requirements from Jira tickets. When you create a ticket with clear requirements and acceptance criteria, OpenHands can read the ticket, generate an implementation plan, and create a pull request in your linked repository. + +### How It Works + +Once configured, you can request OpenHands to work on a Jira ticket by: + +1. **Specify the Repository**: Include the repository location in either: + - The ticket body itself, or + - A comment on the ticket + +2. **Trigger OpenHands**: Activate the agent using one of these methods: + - Add an `openhands` label to the ticket + - Comment with: `@openhands please review these requirements, generate a plan, and then proceed with implementation` + +OpenHands will then read the ticket, understand the requirements, and generate a conversation that results in a pull request implementing the requested changes. + +### Example Ticket + +Here's an example of how to structure a Jira ticket for OpenHands: + +**Title:** Add SAML Support + +**Body:** +``` +As an administrator for my web app, I want to configure SAML so I can provide secure access to my system. + +Repository: AcmeCo/WebApp + +AC: +- Verify an administrator can configure SAML settings +- Verify an end user can authenticate via SAML +``` + +After creating this ticket, you can either add the `openhands` label or comment with `@openhands please review these requirements, generate a plan, and then proceed with implementation` to start the automation process. + +--- + ## Platform Configuration ### Step 1: Create Service Account @@ -35846,7 +36641,11 @@ Get familiar with our architecture: - **[Evaluation](https://github.com/OpenHands/benchmarks)** - Testing and benchmarks ### Pull Request Process -We welcome all pull requests! Here's how we evaluate them: +We welcome pull requests across our public repositories! Here's how we evaluate them: + + +**Enterprise Directory Restriction:** We cannot accept pull requests for changes in the `enterprise/` directory of the OpenHands repository at this time, as this part of the codebase is commercially licensed. If you have feedback or suggestions for [OpenHands Enterprise](/enterprise/index), please [create an issue](https://github.com/OpenHands/OpenHands/issues) in the OpenHands repository instead. + #### Small Improvements - Quick review and approval for obvious improvements @@ -35959,7 +36758,7 @@ OpenHands is released under the **MIT License**, which means: *Full license text: [LICENSE](https://github.com/OpenHands/OpenHands/blob/main/LICENSE)* -**Special Note:** Content in the `enterprise/` directory has a separate license. See `enterprise/LICENSE` for details. +**Special Note:** Content in the `enterprise/` directory has a separate license, and we cannot accept external pull requests for changes to this directory at this time. See `enterprise/LICENSE` for details. ## Ready to make your first contribution? @@ -36793,20 +37592,432 @@ Enterprise customers receive: - [SDK Documentation](/sdk/index) — Build custom agents with the OpenHands SDK - [Pricing](https://openhands.dev/pricing) — Compare all OpenHands plans +### Enterprise vs. Open Source +Source: https://docs.openhands.dev/enterprise/enterprise-vs-oss.md + +This page describes the key differences between **OpenHands Local GUI** (open source) for individual developers and small teams running the Local GUI on their own machines, and **OpenHands Enterprise** for organizations that need advanced collaboration, integrations, and management capabilities. + +## Feature Comparison + +The table below highlights the key differences between the OpenHands Local GUI and OpenHands Enterprise offerings: + +| Feature | Local GUI | OpenHands Enterprise | +|---------|-------------------|----------------------| +| **Full breadth of agent functionality (sub-agents, MCP, skills, model agnosticism)** | ✅ | ✅ | +| **Where does the agent run?** | Local dev machines | Scalable, runtime sandboxes | +| **Scalability** *Run multiple concurrent agent conversations* | Limited by machine | Unlimited, on-demand | +| **'@OpenHands' in Slack and Jira** *Important for real-time resolution of bugs and feedback* | ❌ | ✅ | +| **'@OpenHands' in GitHub, GitLab, Bitbucket** *Important for real-time resolution of PR comments and failing tests* | ❌ | ✅ | +| **Multiple agent conversations in one place** *Give users visibility into all agent conversations* | ✅ | ✅ | +| **Share conversations** *Unlock collaboration use cases* | ❌ | ✅ | +| **Remote monitoring of agent conversations** *Enable Human-in-the-Loop operations for running agents* | ❌ Requires access to machine where agent is running | ✅ Monitor remotely from OpenHands Enterprise UI | +| **Multi-user management and RBAC** *Roll out to several users and teams* | ❌ | ✅ | +| **Automations** *Create scheduled and event-based workflows* | ❌ | ✅ | +| **SAML** | ❌ | ✅ | +| **REST APIs** | ❌ | ✅ | + +## When to Choose Each Option + +### OpenHands Local GUI + +The OpenHands Local GUI is ideal for: + +- Individual developers exploring AI-assisted coding +- Small teams with basic requirements +- Self-hosted environments where you manage your own infrastructure +- Running OpenHands locally on your own machine + +### OpenHands Enterprise + +OpenHands Enterprise is the right choice when you need: + +- **Team collaboration** — Share conversations and manage multiple users from a single platform +- **Platform integrations** — Invoke OpenHands directly from Slack, Jira, GitHub, GitLab, or Bitbucket +- **Scalability** — Run unlimited parallel agent conversations without local resource constraints +- **Enterprise security** — SAML authentication, RBAC, and centralized audit logs +- **Remote monitoring** — Track agent progress in real-time from anywhere + +## Getting Started + + + + Get started with OpenHands on your local machine using Docker or the CLI launcher. + + + Discuss your organization's requirements and get a customized deployment plan for OpenHands Enterprise. + + + +### Kubernetes Installation +Source: https://docs.openhands.dev/enterprise/k8s-install.md + +OpenHands Enterprise can be deployed into an existing Kubernetes cluster using Helm. +This approach gives you full control over the deployment and is ideal for teams with +Kubernetes expertise who want to integrate OpenHands into their existing infrastructure. + + + If you prefer a simpler installation, see the [Quick Start](/enterprise/quick-start) + guide for VM-based deployment. + + +## When to Use This Approach + +Choose the Kubernetes installation path when you: + +- Have an existing Kubernetes cluster you want to deploy into +- Need fine-grained control over resource allocation and scaling +- Want to integrate with existing infrastructure (external PostgreSQL, Redis, S3) +- Have a platform team familiar with Helm and Kubernetes operations +- Need to comply with specific infrastructure policies or constraints + +## Architecture Overview + +OpenHands Enterprise consists of several components deployed as Kubernetes workloads: + +![OpenHands Enterprise Architecture](./images/architecture.svg) + +### Core Components + +| Component | Description | +|-----------|-------------| +| **OpenHands Server** | Main application server handling UI, API, and agent orchestration | +| **Runtime API** | Manages sandbox lifecycle—provisioning, scaling, and cleanup | +| **Runtimes (Sandboxes)** | Isolated containers where agents execute code | +| **Keycloak** | Identity and access management | +| **LiteLLM Proxy** | Routes requests to your LLM provider(s) | +| **PostgreSQL** | Persistent storage for application data | +| **Redis** | Caching and session management | + +### Supporting Services + +| Component | Description | +|-----------|-------------| +| **Conversation Bucket** | S3-compatible storage for conversation history | +| **Image Loader** | Pre-loads runtime container images on nodes | + +## Guides + + + Configure memory, CPU, and storage for optimal performance. + + +## Request Access + +Kubernetes-based installation is currently available to select customers on request. +If you're interested in deploying OpenHands Enterprise into your own Kubernetes cluster, +please contact our team to discuss your requirements. + + + Get in touch with our team to request access to Kubernetes installation. + + +### Resource Limits +Source: https://docs.openhands.dev/enterprise/k8s-install/resource-limits.md + +This guide explains how to configure resource limits for OpenHands Enterprise +components. Proper resource configuration ensures stable operation and prevents +issues like OOMKills and pod evictions. + +## Values File Structure + +All configuration examples in this guide show keys that belong in your `site-values.yaml` +file. The examples show the complete path from the root of the file. + + + Create a `site-values.yaml` file to store your custom configuration. Pass it to Helm + with `-f site-values.yaml` when installing or upgrading. + + +## Understanding Kubernetes Resources + +Kubernetes uses two key resource settings: + +- **Requests**: The minimum resources guaranteed to a pod. The scheduler uses this + to place pods on nodes with sufficient capacity. +- **Limits**: The maximum resources a pod can use. Exceeding memory limits causes + an OOMKill; exceeding CPU limits causes throttling. + + + If a pod uses significantly more memory than its request (but below its limit), + it becomes a candidate for eviction during node pressure. Set requests close to + actual usage for production workloads. + + +## Application Server Resources + +The OpenHands application server (deployment name: `openhands`) handles the UI, API, +and agent orchestration. Configure its resources under the `deployment` section in +your values file. + +### Default Configuration + +```yaml +# site-values.yaml + +# ============================================================================ +# Application Server (OpenHands deployment) +# ============================================================================ +# Root-level key: deployment +# Controls the main OpenHands server pod resources +# ============================================================================ +deployment: + replicas: 1 + resources: + requests: + memory: 1200Mi + cpu: 100m + limits: + memory: 3Gi +``` + +### Recommended Production Configuration + +For production workloads, increase memory and add replicas for redundancy: + +```yaml +# site-values.yaml + +deployment: # Root-level key + replicas: 2 + resources: + requests: + memory: 2560Mi # 2.5Gi - aligns with typical usage + cpu: 100m + limits: + memory: 4Gi # Buffer against OOMKill +``` + +### When to Adjust + +Increase resources if you observe: + +| Symptom | Metric to Check | Action | +|---------|----------------|--------| +| Pod restarts | `RESTARTS` column in `kubectl get pods` | Increase `limits.memory` | +| High memory usage | `kubectl top pods` shows >80% of limit | Increase `limits.memory` | +| Evictions during node pressure | Pod events show eviction | Increase `requests.memory` to match actual usage | +| Slow response times | Application latency metrics | Add replicas or increase CPU | + +### Horizontal Pod Autoscaling + +For automatic scaling based on load, enable the HorizontalPodAutoscaler: + +```yaml +# site-values.yaml + +deployment: # Root-level key + replicas: 2 # Minimum baseline + resources: + requests: + memory: 2560Mi + cpu: 200m # Increase for HPA to use as scaling signal + limits: + memory: 4Gi + +autoscaling: # Root-level key (separate from deployment) + enabled: true + minReplicas: 2 + maxReplicas: 5 + targetCPUUtilizationPercentage: 80 + targetMemoryUtilizationPercentage: 80 +``` + +## Sandbox Resources + +Sandboxes (also called runtimes) are the isolated containers where agents execute code. +Each conversation runs in its own sandbox pod. Configure these via environment variables +in the `runtime-api.env` section. + +### Available Settings + +| Variable | Default | Description | +|----------|---------|-------------| +| `MEMORY_REQUEST` | `3072Mi` | Minimum memory guaranteed per sandbox | +| `MEMORY_LIMIT` | `3072Mi` | Maximum memory per sandbox | +| `CPU_REQUEST` | `500m` | Minimum CPU guaranteed (500m = 0.5 cores) | +| `CPU_LIMIT` | (none) | Maximum CPU per sandbox | +| `EPHEMERAL_STORAGE_SIZE` | `10Gi` | Temporary storage per sandbox | + +### Default Configuration + +```yaml +# site-values.yaml + +# ============================================================================ +# Runtime API (Sandbox Manager) +# ============================================================================ +# Root-level key: runtime-api +# This is a subchart that manages sandbox pod lifecycle. +# The env section passes environment variables to the runtime-api container, +# which uses them when creating sandbox pods. +# ============================================================================ +runtime-api: + env: + MEMORY_REQUEST: "3072Mi" + MEMORY_LIMIT: "3072Mi" + CPU_REQUEST: "500m" + EPHEMERAL_STORAGE_SIZE: "10Gi" +``` + +### High-Resource Configuration + +For workloads that require more resources (large codebases, memory-intensive builds): + +```yaml +# site-values.yaml + +runtime-api: # Root-level key (subchart configuration) + env: + MEMORY_REQUEST: "8192Mi" + MEMORY_LIMIT: "8192Mi" + CPU_REQUEST: "2000m" + CPU_LIMIT: "4000m" + EPHEMERAL_STORAGE_SIZE: "50Gi" +``` + +### Resource Format + +- **Memory**: Use `Mi` suffix (mebibytes). Examples: `1024Mi`, `4096Mi`, `8192Mi` +- **CPU**: Use millicores. `1000m` = 1 CPU core. Examples: `500m`, `2000m`, `4000m` +- **Storage**: Use `Gi` suffix (gibibytes). Examples: `10Gi`, `50Gi`, `100Gi` + + + Changes to sandbox resources only affect **new sandboxes**. Existing running + sandboxes keep their original limits until stopped and restarted. + + +## Applying Changes + +### 1. Update your values file + +Edit `site-values.yaml` with your desired configuration: + +```yaml +# site-values.yaml +# +# This file contains your custom overrides for the OpenHands Helm chart. +# All keys shown here are root-level keys in the values hierarchy. + +# ============================================================================ +# Application Server Resources +# ============================================================================ +deployment: + replicas: 2 + resources: + requests: + memory: 2560Mi + cpu: 100m + limits: + memory: 4Gi + +# ============================================================================ +# Sandbox Resources (via Runtime API subchart) +# ============================================================================ +runtime-api: + env: + MEMORY_REQUEST: "8192Mi" + MEMORY_LIMIT: "8192Mi" + CPU_REQUEST: "2000m" + CPU_LIMIT: "4000m" + EPHEMERAL_STORAGE_SIZE: "50Gi" +``` + +### 2. Apply with Helm upgrade + +```bash +helm upgrade openhands \ + oci://ghcr.io/all-hands-ai/helm-charts/openhands \ + -f site-values.yaml \ + -n openhands +``` + +## Verifying Changes + +### Check application server resources + +```bash +kubectl get deployment openhands -n openhands \ + -o jsonpath='{.spec.template.spec.containers[0].resources}' | jq +``` + +### Check replica count + +```bash +kubectl get deployment openhands -n openhands \ + -o jsonpath='{.spec.replicas}' +``` + +### Check runtime-api environment variables + +Verify the sandbox resource settings are configured in the runtime-api deployment: + +```bash +kubectl get deployment runtime-api -n openhands \ + -o jsonpath='{.spec.template.spec.containers[0].env}' | \ + jq '.[] | select(.name | test("MEMORY|CPU|STORAGE"))' +``` + +## Monitoring Resource Usage + +### Current resource consumption + +```bash +kubectl top pods -n openhands +``` + +### Resource usage over time + +For production deployments, we recommend integrating with a monitoring solution +(Prometheus/Grafana, Datadog, etc.) to track: + +- Memory usage vs. limits (to predict OOMKills) +- Memory usage vs. requests (to predict evictions) +- CPU throttling events +- Pod restart counts + +## Next Steps + + + + Return to the Kubernetes installation overview. + + + Learn more about OpenHands Enterprise features. + + + ### Quick Start Source: https://docs.openhands.dev/enterprise/quick-start.md -This guide walks you through trialing OpenHands Enterprise on AWS. You'll provision -infrastructure with Terraform, configure GitHub for user authentication, and set up -Anthropic as your LLM provider. +This guide walks you through trialing OpenHands Enterprise on your own infrastructure. +You'll provision infrastructure (AWS Terraform or a manual VM setup), configure +GitHub for user authentication, and set up Anthropic as your LLM provider. -## Prerequisites +## Who This Is For + +This guide is **not** for single-user local laptop installs. It is for a **30-day trial of OpenHands Enterprise** on a +**dedicated VM/server** on your own infrastructure. The deployment requires DNS records, network, and compute setup before installation. + +If you want to use OpenHands immediately without infrastructure setup: + +- Use OpenHands Cloud (SaaS) +- Run OpenHands open-source locally using Docker, CLI or SDK + +### Accounts and Credentials Before you begin, make sure you have the following ready: - **Anthropic API key** from the [Anthropic Console](https://console.anthropic.com/) - **A GitHub account** with permission to create GitHub Apps -- **An AWS account** with permissions to create EC2, VPC, and Route53 resources +- **An AWS account** with permissions to create EC2, VPC, and Route53 resources (**if using the AWS with Terraform path**) ## Provision Infrastructure @@ -36843,7 +38054,7 @@ You will need a VM to host OpenHands Enterprise. Choose one of the options below | Port | Protocol | Purpose | |------|----------|---------| - | 80 | TCP | HTTP | + | 80 | TCP | HTTP ingress/redirect | | 443 | TCP | HTTPS | | 30000 | TCP | Admin Console | @@ -36860,8 +38071,8 @@ You will need a VM to host OpenHands Enterprise. Choose one of the options below - `charts.r9.all-hands.dev` - `updates.r9.all-hands.dev` - `github.com` - - `docker.io` - - `docker.dev` + - `traefik.github.io` + - `registry-1.docker.io` - `ghcr.io` @@ -36919,11 +38130,105 @@ You will need a VM to host OpenHands Enterprise. Choose one of the options below +## Preflight Validation + +All items below must be completed before running the installer: + +- VM meets CPU, memory, disk, and OS requirements +- DNS records are created and resolve from the VM +- Inbound ports are open: `80`, `443`, and `30000` +- Outbound domains are reachable from the VM +- GitHub App prerequisites are prepared + + + Do not run the installer until preflight checks pass. + + +### DNS checks + +Run the checks below on the target VM before opening the installer dashboard. + +Export your base domain: + +```bash +export BASE_DOMAIN="openhands.example.com" +``` +Test DNS: +```bash +for h in \ + "${BASE_DOMAIN}" \ + "app.${BASE_DOMAIN}" \ + "auth.app.${BASE_DOMAIN}" \ + "llm-proxy.${BASE_DOMAIN}" \ + "runtime-api.${BASE_DOMAIN}"; do + echo "[DNS] $h" + getent hosts "$h" || nslookup "$h" +done +``` + +Expected: each hostname above resolves to your VM's public IP address. + +Test that a runtime wildcard hostname resolves: + +```bash +getent hosts "test.runtime.${BASE_DOMAIN}" || nslookup "test.runtime.${BASE_DOMAIN}" +``` + +Expected: `test.runtime.${BASE_DOMAIN}` resolves to the same target as `${BASE_DOMAIN}`. + +### Outbound connectivity checks + +```bash +urls=( + "https://replicated.app" + "https://proxy.replicated.com/v2/" + "https://images.r9.all-hands.dev/v2/" + "https://install.r9.all-hands.dev" + "https://charts.r9.all-hands.dev" + "https://updates.r9.all-hands.dev" + "https://github.com" + "https://traefik.github.io/charts/index.yaml" + "https://registry-1.docker.io/v2/" + "https://ghcr.io/v2/" +) + +for u in "${urls[@]}"; do + # HTTP 000 means connection failure (DNS failure, timeout, or blocked network path). + code=$(curl -sSIL --max-time 15 -o /dev/null -w "%{http_code}" "$u" || true) + if [ "$code" = "000" ]; then + echo "FAIL $u" + else + echo "OK $u (HTTP $code)" + fi +done +``` + +Any HTTP response code other than `000` is acceptable for reachability checks +(for example `200`, `301`, `302`, `401`, `403`, `405`). + +If any check fails, stop and resolve before continuing: +- DNS failures: Verify records are created, point to the right target, and have finished propagating +- Outbound connectivity failures: Check firewall egress rules, proxy settings, and TLS inspection policies + +## Reasons for Requirements + +| Requirement | Why It Exists | +|------------|----------------| +| `443/TCP` inbound | Primary HTTPS entrypoint for users and service hostnames | +| `30000/TCP` inbound | Replicated/KOTS Admin Console for install and configuration | +| `80/TCP` inbound | HTTP entrypoint used for ingress/redirect behavior | +| `*.runtime.` DNS + cert SAN | Runtime sandboxes are addressed by dynamic runtime-specific hostnames | +| `replicated.app`, `proxy.replicated.com` | Replicated control-plane/license/install paths | +| `images.r9...`, `charts.r9...`, `updates.r9...`, `install.r9...` | Vendor distribution image/chart/update/install endpoints | +| `traefik.github.io` | Embedded cluster ingress chart repository | +| `ghcr.io`, `registry-1.docker.io` | Container image pulls for platform components | +| `github.com` | GitHub App setup/auth/webhooks and downloading public agent skills | + ## Run the Installer ### 1. Access the Installer Dashboard -[Register for a free 30-day trial](https://install.r9.all-hands.dev/openhands/signup), then +After preflight validation checks have passed, [register for a free 30-day trial](https://install.r9.all-hands.dev/openhands/signup), then log in to the installer dashboard. You will see the dashboard below. Click **"View install guide"** in the Install tile. @@ -36945,6 +38250,8 @@ The install guide provides commands to run on your VM. SSH into your VM and exec 3. **Extract the installation assets** -- run the `tar` command shown (this includes your license file) 4. **Install** -- run the install command shown +If the install command fails after preflight checks pass, run `sudo ./openhands support-bundle` and share the resulting bundle with support. + **We recommend providing your TLS certificates during installation.** If you used the Terraform module, the certificates are in your home directory: diff --git a/llms.txt b/llms.txt index d03640a75..bafff44cc 100644 --- a/llms.txt +++ b/llms.txt @@ -109,12 +109,14 @@ from the OpenHands Software Agent SDK. - [API Keys Settings](https://docs.openhands.dev/openhands/usage/settings/api-keys-settings.md): View your OpenHands LLM key and create API keys to work with OpenHands programmatically. - [Application Settings](https://docs.openhands.dev/openhands/usage/settings/application-settings.md): Configure application-level settings for OpenHands. - [Automated Code Review](https://docs.openhands.dev/openhands/usage/use-cases/code-review.md): Set up automated PR reviews using OpenHands and the Software Agent SDK +- [Automations Overview](https://docs.openhands.dev/openhands/usage/automations/overview.md): Create scheduled tasks that run automatically in OpenHands Cloud and Enterprise. - [AWS Bedrock](https://docs.openhands.dev/openhands/usage/llms/aws-bedrock.md): OpenHands uses LiteLLM to make calls to AWS Bedrock models. You can find their documentation on using Bedrock as a provider [here](https://docs.litellm.ai/docs/providers/bedrock). - [Azure](https://docs.openhands.dev/openhands/usage/llms/azure-llms.md): OpenHands uses LiteLLM to make calls to Azure's chat models. You can find their documentation on using Azure as a provider [here](https://docs.litellm.ai/docs/providers/azure). - [Backend Architecture](https://docs.openhands.dev/openhands/usage/architecture/backend.md) - [COBOL Modernization](https://docs.openhands.dev/openhands/usage/use-cases/cobol-modernization.md): Modernizing legacy COBOL systems with OpenHands - [Configuration Options](https://docs.openhands.dev/openhands/usage/advanced/configuration-options.md): How to configure OpenHands V1 (Web UI, env vars, and sandbox settings). - [Configure](https://docs.openhands.dev/openhands/usage/run-openhands/gui-mode.md): High level overview of configuring the OpenHands Web interface. +- [Creating Automations](https://docs.openhands.dev/openhands/usage/automations/creating-automations.md): Learn how to create scheduled automations using the Automation Skill. - [Custom LLM Configurations](https://docs.openhands.dev/openhands/usage/llms/custom-llm-configs.md): OpenHands supports defining multiple named LLM configurations in your `config.toml` file. This feature allows you to use different LLM configurations for different purposes, such as using a cheaper model for tasks that don't require high-quality responses, or using different models with different parameters for specific agents. - [Custom Sandbox](https://docs.openhands.dev/openhands/usage/advanced/custom-sandbox-guide.md): This guide is for users that would like to use their own custom Docker image for the runtime. - [Debugging](https://docs.openhands.dev/openhands/usage/developers/debugging.md) @@ -134,6 +136,7 @@ from the OpenHands Software Agent SDK. - [LiteLLM Proxy](https://docs.openhands.dev/openhands/usage/llms/litellm-proxy.md): OpenHands supports using the [LiteLLM proxy](https://docs.litellm.ai/docs/proxy/quick_start) to access various LLM providers. - [Local LLMs](https://docs.openhands.dev/openhands/usage/llms/local-llms.md): When using a Local LLM, OpenHands may have limited functionality. It is highly recommended that you use GPUs to serve local models for optimal experience. - [Main Agent and Capabilities](https://docs.openhands.dev/openhands/usage/agents.md) +- [Managing Automations](https://docs.openhands.dev/openhands/usage/automations/managing-automations.md): List, update, enable, disable, and delete your automations. - [Model Context Protocol (MCP)](https://docs.openhands.dev/openhands/usage/settings/mcp-settings.md): This page outlines how to configure and use the Model Context Protocol (MCP) in OpenHands, allowing you - [Moonshot AI](https://docs.openhands.dev/openhands/usage/llms/moonshot.md): How to use Moonshot AI models with OpenHands - [OpenAI](https://docs.openhands.dev/openhands/usage/llms/openai-llms.md): OpenHands uses LiteLLM to make calls to OpenAI's chat models. You can find their documentation on using OpenAI as a provider [here](https://docs.litellm.ai/docs/providers/openai). @@ -171,6 +174,7 @@ from the OpenHands Software Agent SDK. - [Jira Cloud Integration](https://docs.openhands.dev/openhands/usage/cloud/project-management/jira-integration.md): Complete guide for setting up Jira Cloud integration with OpenHands Cloud, including service account creation, API token generation, webhook configuration, and workspace integration setup. - [Jira Data Center Integration (Coming soon...)](https://docs.openhands.dev/openhands/usage/cloud/project-management/jira-dc-integration.md): Complete guide for setting up Jira Data Center integration with OpenHands Cloud, including service account creation, personal access token generation, webhook configuration, and workspace integration setup. - [Linear Integration (Coming soon...)](https://docs.openhands.dev/openhands/usage/cloud/project-management/linear-integration.md): Complete guide for setting up Linear integration with OpenHands Cloud, including service account creation, API key generation, webhook configuration, and workspace integration setup. +- [Plugin Launcher](https://docs.openhands.dev/openhands/usage/cloud/plugin-launcher.md): Use the OpenHands Cloud `/launch` route to open a conversation with plugins or skills pre-configured from a Git repository. - [Project Management Tool Integrations (Coming soon...)](https://docs.openhands.dev/openhands/usage/cloud/project-management/overview.md): Overview of OpenHands Cloud integrations with project management platforms including Jira Cloud, Jira Data Center, and Linear. Learn about setup requirements, usage methods, and troubleshooting. - [Slack Integration](https://docs.openhands.dev/openhands/usage/cloud/slack-installation.md): This guide walks you through installing the OpenHands Slack app. @@ -191,5 +195,8 @@ from the OpenHands Software Agent SDK. ## Other +- [Enterprise vs. Open Source](https://docs.openhands.dev/enterprise/enterprise-vs-oss.md): Compare OpenHands Enterprise and Open Source offerings to choose the right option for your team +- [Kubernetes Installation](https://docs.openhands.dev/enterprise/k8s-install.md): Deploy OpenHands Enterprise into your own Kubernetes cluster using Helm - [OpenHands Enterprise](https://docs.openhands.dev/enterprise.md): Run AI coding agents on your own infrastructure with complete control - [Quick Start](https://docs.openhands.dev/enterprise/quick-start.md): Get started with a 30-day trial of OpenHands Enterprise. +- [Resource Limits](https://docs.openhands.dev/enterprise/k8s-install/resource-limits.md): Configure memory, CPU, and storage for OpenHands Enterprise components