diff --git a/llms-full.txt b/llms-full.txt index e77a8dbc..9757524a 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 ``` @@ -27800,6 +27806,515 @@ 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 +### Creating Automations +Source: https://docs.openhands.dev/openhands/usage/automations/creating-automations.md + + +**Beta Feature**: Automations is currently in beta and available for **OpenHands Cloud** and **OpenHands Enterprise** users only. + + +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. + +## Prompt vs Plugin Automations + +There are two types of automations: + + + + Most automations are prompt-based. Just describe the task in natural language: + + ``` + 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. + ``` + + 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): + + ``` + 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. + ``` + + Plugins provide additional skills, MCP configurations, or custom commands that extend what the automation can do. + + + +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) + +Once created, it runs automatically on schedule. + +## What to Include in Your Request + +When asking OpenHands to create an automation, include: + +- **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 + +## Writing Good Automation Prompts + +The prompt is what the AI agent executes each time the automation runs. Write it like you're giving instructions to a capable assistant. + +### Be Specific + + + + ``` + 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 + ``` + + + +### Include Where to Send Results + +Tell the automation what to do with its output: + +- "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" + + +Git providers you logged in with (GitHub, GitLab, Bitbucket) are automatically available. Other services like Slack require [MCP configuration](/openhands/usage/settings/mcp-settings). + + +### Specify Error Handling + +For monitoring tasks, explain what should happen when things go wrong: + +``` +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. +``` + +## What Your Automation Can Access + +Each automation runs in a full OpenHands sandbox with: + +- **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 + +## Schedules + +Tell OpenHands when you want the automation to run in plain language: + +- "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" + +The agent converts this to the appropriate cron schedule. + + +If you're familiar with cron expressions, you can specify them directly: "Run on cron schedule `0 9 * * 1-5`" + + +## After Creation + +Once your automation is created: + +- **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)) + +## Next Steps + +- [View example automations](/openhands/usage/automations/examples) +- [Manage your automations](/openhands/usage/automations/managing-automations) + +### Automation Examples +Source: https://docs.openhands.dev/openhands/usage/automations/examples.md + + +**Beta Feature**: Automations is currently in beta and available for **OpenHands Cloud** and **OpenHands Enterprise** users only. + + +Copy and adapt these examples to create your own automations. Just paste the prompt into a conversation with OpenHands. + + +These examples reference services like Slack and GitHub. Git providers you logged in with are automatically available, but other services like Slack require [MCP configuration](/openhands/usage/settings/mcp-settings). + + +## Reporting + +### 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. +``` + +## Monitoring + +### API Health Check + +``` +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 +``` + +### 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. +``` + +## Maintenance + +### 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. +``` + +## Data Sync + +### 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 +``` + +## Code Quality + +### Dependency Checker + +``` +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 +``` + +### Security Scan + +``` +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. +``` + +## Tips for Writing Good Prompts + +### Be Specific About Actions + +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" + +### Include Error Handling + +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" + +### Define Where Results Go + +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 + +### Managing Automations +Source: https://docs.openhands.dev/openhands/usage/automations/managing-automations.md + + +**Beta Feature**: Automations is currently in beta and available for **OpenHands Cloud** and **OpenHands Enterprise** users only. + + +You can manage your automations by asking OpenHands directly—just like you created them. + +## Viewing Your Automations + +``` +List my automations +``` + +``` +Show me the details of the "Daily Report" automation +``` + +## Enabling and Disabling + +Pause an automation without deleting it: + +``` +Disable the "Daily Report" automation +``` + +Turn it back on: + +``` +Enable the "Daily Report" automation +``` + + +Disabling an automation keeps all its settings intact. Use this when you want to temporarily stop runs without losing your configuration. + + +## Changing the Schedule + +``` +Change the "Daily Report" automation to run at 10 AM instead of 9 AM +``` + +``` +Update the "Weekly Cleanup" automation to run on Sundays at 2 AM UTC +``` + +## Running Manually + +Test an automation or run it outside its normal schedule: + +``` +Trigger the "Daily Report" automation now +``` + +``` +Run the "Health Check" automation immediately +``` + +This is useful for: +- Testing a newly created automation +- Running a report on-demand +- Debugging issues + +## Viewing Past Runs + +``` +Show me recent runs of the "Daily Report" automation +``` + +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 + + +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. + + +### 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 + +- [View example automations](/openhands/usage/automations/examples) +- [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) + +## Next Steps + +- [Creating Automations](/openhands/usage/automations/creating-automations) — Detailed guide with prompt tips +- [Examples](/openhands/usage/automations/examples) — Common automation patterns + ### Hooks Source: https://docs.openhands.dev/openhands/usage/customization/hooks.md @@ -35190,6 +35705,112 @@ Once you've connected your account, you can: - [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. + ### Jira Data Center Integration (Coming soon...) Source: https://docs.openhands.dev/openhands/usage/cloud/project-management/jira-dc-integration.md @@ -36793,20 +37414,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 +37876,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 +37893,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 +37952,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 +38072,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 d03640a7..15b8ff8d 100644 --- a/llms.txt +++ b/llms.txt @@ -109,12 +109,15 @@ 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 +- [Automation Examples](https://docs.openhands.dev/openhands/usage/automations/examples.md): Practical examples for common automation use cases. +- [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 +137,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 +175,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 +196,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