diff --git a/docs.json b/docs.json index fb7a5ffe2..51fef9e3c 100644 --- a/docs.json +++ b/docs.json @@ -537,7 +537,9 @@ "enterprise/enterprise-vs-oss", "enterprise/sizing-guide", "enterprise/quick-start", + "enterprise/vm-install/aws", "enterprise/vm-install/google", + "enterprise/vm-install/generic-vm", { "group": "Custom Sandbox Images", "icon": "box", diff --git a/enterprise/k8s-install/installation.mdx b/enterprise/k8s-install/installation.mdx index e84ac3f77..bc602c2bd 100644 --- a/enterprise/k8s-install/installation.mdx +++ b/enterprise/k8s-install/installation.mdx @@ -39,7 +39,7 @@ license automatically at install time. - A **wildcard TLS certificate** for `*.openhands.example.com`, which you provide. - An **authentication method** for user login — GitLab, Bitbucket Data Center, and more are supported; this guide uses a **GitHub App**. See - [Creating a GitHub App](/enterprise/quick-start#create-a-github-app). + [Creating a GitHub App](/enterprise/vm-install/generic-vm#create-a-github-app). ## Step 1: Log in to the registry @@ -118,7 +118,7 @@ unset OH_RUNTIME_SHARED_KEY Then create the secret for user authentication. Other providers (GitLab, Bitbucket Data Center, and more) are supported, but this guide uses GitHub throughout. If you don't have a GitHub App yet, run our -[script](/enterprise/quick-start#create-a-github-app) — its output provides +[script](/enterprise/vm-install/generic-vm#create-a-github-app) — its output provides every value below, and the private key file is written to its `keys` directory: diff --git a/enterprise/quick-start.mdx b/enterprise/quick-start.mdx index 8d42cc0d8..737e84d54 100644 --- a/enterprise/quick-start.mdx +++ b/enterprise/quick-start.mdx @@ -1,460 +1,145 @@ --- title: Quick Start -description: Get started with a 30-day trial of OpenHands Enterprise. +description: Choose an installation guide for OpenHands Enterprise on your infrastructure. icon: rocket --- -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 configure your LLM provider. - -## 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: - - - Sign up for a free 30-day OpenHands Enterprise trial account. You'll need this to access the installer dashboard. - - -- **LLM credentials** from your chosen provider, for example an 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 (**if using the AWS with Terraform path**) - -## Provision Infrastructure - -You will need a VM to host OpenHands Enterprise. Choose one of the options below to provision your infrastructure. - -For Google Compute Engine with Vertex AI, follow the [Google Cloud Quick Start](/enterprise/vm-install/google). - - - The requirements below are the trial baseline, which comfortably supports about 15 concurrent sandboxes. For a larger rollout, pick your VM from the [Sizing Guide](/enterprise/sizing-guide) before provisioning. - - - - - We provide a [Terraform module](https://github.com/All-Hands-AI/OpenHands-Cloud/tree/main/terraform/aws) that provisions a properly configured environment - for OpenHands Enterprise, including the EC2 instance, DNS records, and TLS certificates. - - - Follow the README instructions to configure and apply the Terraform configuration. - - - - The recommended Terraform path provisions a publicly trusted TLS certificate. If you bring - your own certificate instead, use a publicly trusted CA whenever possible. Private CA - certificates require every external webhook or OAuth provider that calls OpenHands to trust - your CA. - - - - - If you are provisioning a VM manually (on-premises or on another cloud provider), - it must meet the requirements below. - - - | Resource | Requirement | - |----------|-------------| - | **vCPUs** | 16 | - | **Memory** | 64 GB | - | **Disk** | 200 GB | - | **Disk P99 write latency** | 10 ms maximum | - | **OS** | Linux (x86-64 architecture) | - | **Init system** | systemd | - | **Access** | Root access (sudo) required | - - - We recommend **Ubuntu 24.04 LTS**. The default **Sandbox Isolation** runtime - (Sysbox) is best supported on Ubuntu and requires **Linux kernel 6.3 or newer**, - which Ubuntu 24.04 provides. Very new, non-LTS releases (for example, Ubuntu 25.10 - or later) may ship kernels that are not yet supported by Sysbox and can cause - sandbox containers to fail during startup. If you do not need Docker inside the - sandbox, you can instead select the standard runtime under **Sandbox Isolation** in - the installer, which does not require a Sysbox-compatible kernel. See - [Docker in Sandbox](/enterprise/docker-in-sandbox) for details. - - - - - **Firewall inbound rules** -- the following ports must be open: - - | Port | Protocol | Purpose | - |------|----------|---------| - | 80 | TCP | HTTP ingress/redirect | - | 443 | TCP | HTTPS | - | 30000 | TCP | Admin Console | - - **Local ports** -- the following ports must be available for local processes (no firewall rules needed): - - `2379/TCP`, `7443/TCP`, `9099/TCP`, `10248/TCP`, `10257/TCP`, `10259/TCP` - - **Outbound access** -- the VM must be able to reach: - - - `replicated.app` - - `proxy.replicated.com` - - `images.r9.all-hands.dev` - - `install.r9.all-hands.dev` - - `charts.r9.all-hands.dev` - - `updates.r9.all-hands.dev` - - `github.com` - - `traefik.github.io` - - `registry-1.docker.io` - - `ghcr.io` - - - - The installation creates directories and files in the following locations: - - ``` - /etc/cni - /etc/k0s - /opt/cni - /opt/containerd - /run/calico - /run/containerd - /run/k0s - /sys/fs/cgroup/kubepods - /sys/fs/cgroup/system.slice/containerd.service - /sys/fs/cgroup/system.slice/k0scontroller.service - /usr/libexec/k0s - /usr/local/bin/k0s - /var/lib/calico - /var/lib/cni - /var/lib/containers - /var/lib/embedded-cluster - /var/lib/kubelet - /var/log/calico - /var/log/containers - /var/log/embedded-cluster - /var/log/pods - ``` - - - ### DNS and TLS Setup - - Once your VM is running, configure DNS and TLS before starting the installer. - - **Create a wildcard DNS A record** pointing to your VM's public IP address: - - | Record | Example | - |--------|---------| - | `*.` | `*.openhands.example.com` | - - **Obtain a wildcard TLS certificate signed by a well-known certificate authority (CA) such as Let's Encrypt** - for `*.`, then copy the certificate - (`.pem` or `.crt`) and private key (`.pem` or `.key`) to the VM. Self-signed certificates - are not supported for the OpenHands application. - - - Obtain a certificate with SANs (Subject Alternative Names) for each of these hostnames: - - - `admin.` - - `app.` - - `auth.` - - `analytics.` - - `llm-proxy.` - - `runtime-api.` - - `runtime.` - - By default, each sandbox runtime gets its own dynamic hostname, which only a wildcard - certificate can cover. When you configure OpenHands, set **Sandbox Routing Mode** to - **Path-based** so all sandboxes are served under `runtime.` instead. - - - - If you don't provide TLS certificates during installation, the Admin Console will use a - self-signed certificate and your browser will display a security warning. You can still - upload your certificate afterward through the Admin Console. - - - - -## 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 -- (Optional) [External PostgreSQL](/enterprise/external-postgres) instance provisioned if using your own database - - - 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 "admin.${BASE_DOMAIN}" "app.${BASE_DOMAIN}" "test-runtime.${BASE_DOMAIN}"; do - echo "[DNS] $h" - getent hosts "$h" || nslookup "$h" -done -``` - -Expected: each hostname resolves to your VM's public IP address through the -wildcard record. - -### 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 -``` +Install OpenHands Enterprise with Replicated Embedded Cluster on a dedicated VM. +Choose the guide for your infrastructure: -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 | -| `*.` DNS + cert SAN | Application services and sandboxes are addressed by hostnames under the base domain | -| `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 - -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. - -![Installer Dashboard](./images/admin-dashboard.png) - -### 2. Name your instance - -Enter a name for your instance (e.g., your company name or environment identifier). -Select **"Outbound requests allowed"** for Network Availability, then click **Continue**. - -![Instance name and network availability](./images/install-instance-name.png) - -### 3. Run the installation commands + + + Provision AWS infrastructure with the official Terraform module, then install and configure OpenHands. + + + Provision a Compute Engine VM and configure administrator-managed Vertex AI models. + + + Prepare a Linux VM on-premises or on another cloud provider, then install and configure OpenHands. + + -The install guide provides commands to run on your VM. SSH into your VM and execute them in order: +Each guide covers prerequisites, infrastructure, preflights, installation, +application configuration and first-login checks. For an existing Kubernetes +cluster, see [Install with Helm](/enterprise/k8s-install/installation). -1. **Select a version** -- the latest version is pre-selected -2. **Download the installation assets** -- copy and run the `curl` command shown -3. **Extract the installation assets** -- run the `tar` command shown (this includes your license file) -4. **Install** -- run the install command shown +The [Sizing Guide](/enterprise/sizing-guide) helps you choose resources for your +workload. The [Admin Console Configuration reference](/enterprise/vm-install/admin-console-configuration) +covers deployment settings and optional integrations. -If the install command fails after preflight checks pass, see -[Troubleshooting](/enterprise/troubleshooting) to generate a support -bundle and open a support ticket. +## Existing Quick Start Links - - **We recommend providing your TLS certificates during installation.** If you used the - Terraform module, the certificates are in your home directory: +The previous combined guide is now available as the AWS and Generic VM guides. +Use the links below to continue from a previously bookmarked section. - ```bash - sudo ./openhands install --license license.yaml \ - --tls-cert ~/certificate.pem \ - --tls-key ~/private-key.pem - ``` + - If you provisioned manually and have your own certificates on the VM, pass them the same way. - You can also omit the `--tls-cert` and `--tls-key` flags and upload certificates later through - the Admin Console. +[Who This Is For](/enterprise/vm-install/generic-vm#who-this-is-for) - For trials and production deployments, use a publicly trusted TLS certificate whenever possible. - Private CA certificates may work for users after manual trust setup, but external integrations - such as GitHub, GitLab, Slack, Jira, and Bitbucket must also trust the certificate chain. If they - do not, webhook or OAuth callbacks can fail TLS verification and repeatedly retry. - + -![Installation commands](./images/install-commands.png) +[Accounts and Credentials](/enterprise/vm-install/generic-vm#accounts-and-credentials) -### 4. Access the Admin Console + -Once the install command completes, the Admin Console is available at: -- `https://admin.:30000` (if you provided TLS certificates) -- `http://:30000` (if you did not use the `--tls-cert` and `--tls-key` flags on the `install` command) +[Provision Infrastructure](/enterprise/vm-install/generic-vm#provision-infrastructure) -If you did not provide TLS certificates with the `install` command, your browser will display a security warning. -Click **Advanced**, then **Proceed** to continue to the Admin Console. + -![Self-signed certificate warning](./images/self-signed-cert-warning.png) +[Preflight Validation](/enterprise/vm-install/generic-vm#preflight-validation) -### 5. Upload TLS certificate (if not provided with the install command) + -If you did not provide certificates with the `install` command, select **"Upload your own"**, -enter `admin.` under **Hostname**, upload your private key and SSL certificate, then click **Continue**. +[DNS checks](/enterprise/vm-install/generic-vm#dns-checks) -If you upload a private CA certificate, make sure any external webhook or OAuth provider that -calls OpenHands also trusts that CA. + -![Upload TLS certificate](./images/upload-tls-certificate.png) +[Outbound connectivity checks](/enterprise/vm-install/generic-vm#outbound-connectivity-checks) -### 6. Log in to the Admin Console + -Enter the password you set during installation and click **Log in**. +[Reasons for Requirements](/enterprise/vm-install/generic-vm#reasons-for-requirements) -![Admin Console login](./images/admin-console-login.png) + -### 7. Configure the cluster +[Run the Installer](/enterprise/vm-install/generic-vm#run-the-installer) -You will be prompted to add additional nodes to the cluster. -For a single-node deployment, click **Continue** to skip this step. + -![Configure cluster nodes](./images/configure-cluster-nodes.png) +[1. Access the Installer Dashboard](/enterprise/vm-install/generic-vm#1-access-the-installer-dashboard) -## Configure OpenHands + -You should now see the application configuration page. +[2. Name your instance](/enterprise/vm-install/generic-vm#2-name-your-instance) -![Configure OpenHands](./images/configure-openhands.png) + -### Domain Configuration +[3. Run the installation commands](/enterprise/vm-install/generic-vm#3-run-the-installation-commands) -- Keep the Hostname Configuration Mode set to **"Simple (default)"** -- Enter your base domain (e.g., `openhands.example.com`) + -### Certificate Configuration +[4. Access the Admin Console](/enterprise/vm-install/generic-vm#4-access-the-admin-console) -- Upload your **TLS Certificate** (`.crt` or `.pem`) -- Upload your **TLS Private Key** (`.key` or `.pem`) -- Optionally upload the root **CA Certificate** for your TLS certificates + -### LLM Configuration +[5. Upload TLS certificate (if not provided with the install command)](/enterprise/vm-install/generic-vm#5-upload-tls-certificate-if-not-provided-with-the-install-command) -Choose an LLM provider from the LLM Configuration dropdown and enter the details -from that provider. + -![LLM Configuration provider dropdown](./images/llm-configuration-provider-dropdown.png) +[6. Log in to the Admin Console](/enterprise/vm-install/generic-vm#6-log-in-to-the-admin-console) -For example, if you use Anthropic, enter your API key from the -[Anthropic Console](https://console.anthropic.com/). + -### Database Configuration +[7. Configure the cluster](/enterprise/vm-install/generic-vm#7-configure-the-cluster) -By default, OpenHands Enterprise uses a bundled PostgreSQL database. If you need to use your -own PostgreSQL instance (for example, to integrate with existing database infrastructure or -meet specific backup/HA requirements), see [External PostgreSQL](/enterprise/external-postgres) -for setup instructions. + -### GitHub Authentication +[Configure OpenHands](/enterprise/vm-install/generic-vm#configure-openhands) -Enable GitHub Authentication in the Admin Console, then follow these steps to create and -configure a GitHub App. + -#### Create a GitHub App +[Domain Configuration](/enterprise/vm-install/generic-vm#domain-configuration) -Run our [script](https://github.com/All-Hands-AI/OpenHands-Cloud/tree/main/scripts/create_github_app) to create a GitHub App configured for your install. + -#### Map GitHub App values to Admin Console +[Certificate Configuration](/enterprise/vm-install/generic-vm#certificate-configuration) -Go back to the Installer Admin Console in your browser and enter the values from the Create GitHub App script output. For the private key, upload the file from the `keys` directory of the script location. + -See [GitHub](/enterprise/integrations/github) for GitHub App installation, -`@openhands` resolver behavior, pull request review identity, and repository-level -review controls. +[LLM Configuration](/enterprise/vm-install/generic-vm#llm-configuration) -### Additional Integrations + -If your team uses Jira Data Center or Bitbucket Data Center, follow these guides -to configure Admin Console values before deployment and complete webhook setup -inside OpenHands after deployment. +[Database Configuration](/enterprise/vm-install/generic-vm#database-configuration) - - - Configure Bitbucket Data Center login, repository access, bot identity, and pull request webhooks. - - - Configure Jira issue triggers, OAuth account linking, service account credentials, and Jira webhooks. - - + -After filling in all fields, click **Continue** at the bottom of the page. +[GitHub Authentication](/enterprise/vm-install/generic-vm#github-authentication) -## Deploy and Verify + -OpenHands will begin deploying. You can expect the deployment status to transition from -**Missing** to **Unavailable** to **Ready**. This typically takes 5-10 minutes. +[Create a GitHub App](/enterprise/vm-install/generic-vm#create-a-github-app) -![Deployment in progress](./images/deployment-in-progress.png) + -Click **Details** next to the deployment status to monitor individual resources. Resources -shown in orange are still deploying -- wait until all resources are ready. +[Map GitHub App values to Admin Console](/enterprise/vm-install/generic-vm#map-github-app-values-to-admin-console) -![Deployment status details](./images/deployment-status-details.png) + -## First Login +[Additional Integrations](/enterprise/vm-install/generic-vm#additional-integrations) -Once the deployment status shows **Ready**, navigate to `https://app.` -and click the **Login with GitHub** tile. + +[Deploy and Verify](/enterprise/vm-install/generic-vm#deploy-and-verify) -Accept the Terms of Service and click **Continue**. + -![Accept Terms of Service](./images/accept-terms-of-service.png) +[First Login](/enterprise/vm-install/generic-vm#first-login) -OpenHands Enterprise is now running. You can open a repository or start a new conversation. + -![OpenHands is ready](./images/openhands-ready.png) +[Next Steps](/enterprise/vm-install/generic-vm#next-steps) -## Next Steps + - - - Learn about OpenHands Enterprise features, integrations, and deployment options. - - - Get the most out of your AI coding agents with effective prompting techniques. - - - Collect diagnostics, inspect workloads, and contact OpenHands Support. - - - Explore the full OpenHands documentation for usage guides and features. - - +[DNS and TLS Setup](/enterprise/vm-install/generic-vm#dns-and-tls-setup) diff --git a/enterprise/sizing-guide.mdx b/enterprise/sizing-guide.mdx index 38cb1f090..de7da7f78 100644 --- a/enterprise/sizing-guide.mdx +++ b/enterprise/sizing-guide.mdx @@ -49,7 +49,7 @@ Machine sizes below are based on the peak sandboxes, so feel free to size up or | **100** | ~400 | 96 vCPU / 384 GiB | `n2-standard-96`, `m6i.24xlarge`, `D96s_v5` | 4 TiB SSD | | **Above 100** | — | Use a Kubernetes install, or contact us for a sizing consultation | — | — | -The 16 vCPU / 64 GiB row matches the minimum VM in the [Quick Start](/enterprise/quick-start) system requirements. Trials that stay below roughly 15 concurrent sandboxes are well served by that baseline. +The 16 vCPU / 64 GiB row matches the minimum VM in the [Linux VM Quick Start](/enterprise/vm-install/generic-vm#system-requirements) system requirements. Trials that stay below roughly 15 concurrent sandboxes are well served by that baseline. **Put the data disk on a separate expandable volume, not the boot disk.** Sandbox volumes on a single VM are host directories that consume actual bytes rather than preallocating, so the disk grows with real usage and is meant to be resized in place as demand increases. diff --git a/enterprise/vm-install/aws.mdx b/enterprise/vm-install/aws.mdx new file mode 100644 index 000000000..71dbcdf2f --- /dev/null +++ b/enterprise/vm-install/aws.mdx @@ -0,0 +1,335 @@ +--- +title: AWS Quick Start +description: Install OpenHands Enterprise on AWS using Terraform and the Replicated Admin Console. +icon: aws +--- + +This guide walks you through trialing OpenHands Enterprise on your own infrastructure. +You'll provision AWS infrastructure with Terraform, configure +GitHub for user authentication, and configure your LLM provider. + +## 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: + + + Sign up for a free 30-day OpenHands Enterprise trial account. You'll need this to access the installer dashboard. + + +- **LLM credentials** from your chosen provider, for example an 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 + +## Provision Infrastructure + +Provision a dedicated VM for OpenHands Enterprise. + + + + The Terraform module defaults to an `m6i.4xlarge` instance (16 vCPU and 64 GiB RAM) with a 200 GB root volume. Choose capacity for your workload using the [Sizing Guide](/enterprise/sizing-guide) before provisioning. + + +We provide a [Terraform module](https://github.com/All-Hands-AI/OpenHands-Cloud/tree/main/terraform/aws) that provisions a properly configured environment +for OpenHands Enterprise, including the EC2 instance, DNS records, and TLS certificates. + + + Follow the README instructions to configure and apply the Terraform configuration. + + + + The recommended Terraform path provisions a publicly trusted TLS certificate. If you bring + your own certificate instead, use a publicly trusted CA whenever possible. Private CA + certificates require every external webhook or OAuth provider that calls OpenHands to trust + your CA. + + + +## 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 +- (Optional) [External PostgreSQL](/enterprise/external-postgres) instance provisioned if using your own database + + + 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 "admin.${BASE_DOMAIN}" "app.${BASE_DOMAIN}" "test-runtime.${BASE_DOMAIN}"; do + echo "[DNS] $h" + getent hosts "$h" || nslookup "$h" +done +``` + +Expected: each hostname resolves to your VM's public IP address through the +wildcard record. + +### 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 | +| `*.` DNS + cert SAN | Application services and sandboxes are addressed by hostnames under the base domain | +| `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 + +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. + +![Installer Dashboard](/enterprise/images/admin-dashboard.png) + +### 2. Name your instance + +Enter a name for your instance (e.g., your company name or environment identifier). +Select **"Outbound requests allowed"** for Network Availability, then click **Continue**. + +![Instance name and network availability](/enterprise/images/install-instance-name.png) + +### 3. Run the installation commands + +The install guide provides commands to run on your VM. SSH into your VM and execute them in order: + +1. **Select a version** -- the latest version is pre-selected +2. **Download the installation assets** -- copy and run the `curl` command shown +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, see +[Troubleshooting](/enterprise/troubleshooting) to generate a support +bundle and open a support ticket. + + + **We recommend providing your TLS certificates during installation.** If you used the + Terraform module, the certificates are in your home directory: + + ```bash + sudo ./openhands install --license license.yaml \ + --tls-cert ~/certificate.pem \ + --tls-key ~/private-key.pem + ``` + + You can also omit the `--tls-cert` and `--tls-key` flags and upload certificates later through + the Admin Console. + + For trials and production deployments, use a publicly trusted TLS certificate whenever possible. + Private CA certificates may work for users after manual trust setup, but external integrations + such as GitHub, GitLab, Slack, Jira, and Bitbucket must also trust the certificate chain. If they + do not, webhook or OAuth callbacks can fail TLS verification and repeatedly retry. + + +![Installation commands](/enterprise/images/install-commands.png) + +### 4. Access the Admin Console + +Once the install command completes, the Admin Console is available at: +- `https://admin.:30000` (if you provided TLS certificates) +- `http://:30000` (if you did not use the `--tls-cert` and `--tls-key` flags on the `install` command) + +If you did not provide TLS certificates with the `install` command, your browser will display a security warning. +Click **Advanced**, then **Proceed** to continue to the Admin Console. + +![Self-signed certificate warning](/enterprise/images/self-signed-cert-warning.png) + +### 5. Upload TLS certificate (if not provided with the install command) + +If you did not provide certificates with the `install` command, select **"Upload your own"**, +enter `admin.` under **Hostname**, upload your private key and SSL certificate, then click **Continue**. + +If you upload a private CA certificate, make sure any external webhook or OAuth provider that +calls OpenHands also trusts that CA. + +![Upload TLS certificate](/enterprise/images/upload-tls-certificate.png) + +### 6. Log in to the Admin Console + +Enter the password you set during installation and click **Log in**. + +![Admin Console login](/enterprise/images/admin-console-login.png) + +### 7. Configure the cluster + +You will be prompted to add additional nodes to the cluster. +For a single-node deployment, click **Continue** to skip this step. + +![Configure cluster nodes](/enterprise/images/configure-cluster-nodes.png) + +## Configure OpenHands + +You should now see the application configuration page. + +![Configure OpenHands](/enterprise/images/configure-openhands.png) + +### Domain Configuration + +- Keep the Hostname Configuration Mode set to **"Simple (default)"** +- Enter your base domain (e.g., `openhands.example.com`) + +### Certificate Configuration + +- Upload your **TLS Certificate** (`.crt` or `.pem`) +- Upload your **TLS Private Key** (`.key` or `.pem`) +- Optionally upload the root **CA Certificate** for your TLS certificates + +### LLM Configuration + +Choose an LLM provider from the LLM Configuration dropdown and enter the details +from that provider. + +![LLM Configuration provider dropdown](/enterprise/images/llm-configuration-provider-dropdown.png) + +For example, if you use Anthropic, enter your API key from the +[Anthropic Console](https://console.anthropic.com/). + +### Database Configuration + +By default, OpenHands Enterprise uses a bundled PostgreSQL database. If you need to use your +own PostgreSQL instance (for example, to integrate with existing database infrastructure or +meet specific backup/HA requirements), see [External PostgreSQL](/enterprise/external-postgres) +for setup instructions. + +### GitHub Authentication + +Enable GitHub Authentication in the Admin Console, then follow these steps to create and +configure a GitHub App. + +#### Create a GitHub App + +Run our [script](https://github.com/All-Hands-AI/OpenHands-Cloud/tree/main/scripts/create_github_app) to create a GitHub App configured for your install. + +#### Map GitHub App values to Admin Console + +Go back to the Installer Admin Console in your browser and enter the values from the Create GitHub App script output. For the private key, upload the file from the `keys` directory of the script location. + +See [GitHub](/enterprise/integrations/github) for GitHub App installation, +`@openhands` resolver behavior, pull request review identity, and repository-level +review controls. + +### Additional Integrations + +If your team uses Jira Data Center or Bitbucket Data Center, follow these guides +to configure Admin Console values before deployment and complete webhook setup +inside OpenHands after deployment. + + + + Configure Bitbucket Data Center login, repository access, bot identity, and pull request webhooks. + + + Configure Jira issue triggers, OAuth account linking, service account credentials, and Jira webhooks. + + + +After filling in all fields, click **Continue** at the bottom of the page. + +## Deploy and Verify + +OpenHands will begin deploying. You can expect the deployment status to transition from +**Missing** to **Unavailable** to **Ready**. This typically takes 5-10 minutes. + +![Deployment in progress](/enterprise/images/deployment-in-progress.png) + +Click **Details** next to the deployment status to monitor individual resources. Resources +shown in orange are still deploying -- wait until all resources are ready. + +![Deployment status details](/enterprise/images/deployment-status-details.png) + +## First Login + +Once the deployment status shows **Ready**, navigate to `https://app.` +and click the **Login with GitHub** tile. + + +Accept the Terms of Service and click **Continue**. + +![Accept Terms of Service](/enterprise/images/accept-terms-of-service.png) + +OpenHands Enterprise is now running. You can open a repository or start a new conversation. + +![OpenHands is ready](/enterprise/images/openhands-ready.png) + +## Next Steps + + + + Learn about OpenHands Enterprise features, integrations, and deployment options. + + + Get the most out of your AI coding agents with effective prompting techniques. + + + Collect diagnostics, inspect workloads, and contact OpenHands Support. + + + Explore the full OpenHands documentation for usage guides and features. + + diff --git a/enterprise/vm-install/generic-vm.mdx b/enterprise/vm-install/generic-vm.mdx new file mode 100644 index 000000000..5f00b1a99 --- /dev/null +++ b/enterprise/vm-install/generic-vm.mdx @@ -0,0 +1,438 @@ +--- +title: Generic VM Quick Start +description: Install OpenHands Enterprise on a Linux VM using the Replicated installer and Admin Console. +icon: server +--- + +This guide walks you through trialing OpenHands Enterprise on your own infrastructure. +You'll prepare a Linux VM on your cloud or on-premises infrastructure, configure +GitHub for user authentication, and configure your LLM provider. + +## 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: + + + Sign up for a free 30-day OpenHands Enterprise trial account. You'll need this to access the installer dashboard. + + +- **LLM credentials** from your chosen provider, for example an Anthropic API + key from the [Anthropic Console](https://console.anthropic.com/) +- **A GitHub account** with permission to create GitHub Apps + +## Provision Infrastructure + +Provision a dedicated VM for OpenHands Enterprise. + + + + The requirements below are the trial baseline, which comfortably supports about 15 concurrent sandboxes. For a larger rollout, pick your VM from the [Sizing Guide](/enterprise/sizing-guide) before provisioning. + + +If you are provisioning a VM manually (on-premises or on another cloud provider), +it must meet the requirements below. + + + | Resource | Requirement | + |----------|-------------| + | **vCPUs** | 16 | + | **Memory** | 64 GB | + | **Disk** | 200 GB | + | **Disk P99 write latency** | 10 ms maximum | + | **OS** | Linux (x86-64 architecture) | + | **Init system** | systemd | + | **Access** | Root access (sudo) required | + + + We recommend **Ubuntu 24.04 LTS**. The default **Sandbox Isolation** runtime + (Sysbox) is best supported on Ubuntu and requires **Linux kernel 6.3 or newer**, + which Ubuntu 24.04 provides. Very new, non-LTS releases (for example, Ubuntu 25.10 + or later) may ship kernels that are not yet supported by Sysbox and can cause + sandbox containers to fail during startup. If you do not need Docker inside the + sandbox, you can instead select the standard runtime under **Sandbox Isolation** in + the installer, which does not require a Sysbox-compatible kernel. See + [Docker in Sandbox](/enterprise/docker-in-sandbox) for details. + + + + + **Firewall inbound rules** -- the following ports must be open: + + | Port | Protocol | Purpose | + |------|----------|---------| + | 80 | TCP | HTTP ingress/redirect | + | 443 | TCP | HTTPS | + | 30000 | TCP | Admin Console | + + **Local ports** -- the following ports must be available for local processes (no firewall rules needed): + + `2379/TCP`, `7443/TCP`, `9099/TCP`, `10248/TCP`, `10257/TCP`, `10259/TCP` + + **Outbound access** -- the VM must be able to reach: + + - `replicated.app` + - `proxy.replicated.com` + - `images.r9.all-hands.dev` + - `install.r9.all-hands.dev` + - `charts.r9.all-hands.dev` + - `updates.r9.all-hands.dev` + - `github.com` + - `traefik.github.io` + - `registry-1.docker.io` + - `ghcr.io` + + + + The installation creates directories and files in the following locations: + + ``` + /etc/cni + /etc/k0s + /opt/cni + /opt/containerd + /run/calico + /run/containerd + /run/k0s + /sys/fs/cgroup/kubepods + /sys/fs/cgroup/system.slice/containerd.service + /sys/fs/cgroup/system.slice/k0scontroller.service + /usr/libexec/k0s + /usr/local/bin/k0s + /var/lib/calico + /var/lib/cni + /var/lib/containers + /var/lib/embedded-cluster + /var/lib/kubelet + /var/log/calico + /var/log/containers + /var/log/embedded-cluster + /var/log/pods + ``` + + +### DNS and TLS Setup + +Once your VM is running, configure DNS and TLS before starting the installer. + +**Create a wildcard DNS A record** pointing to your VM's public IP address: + +| Record | Example | +|--------|---------| +| `*.` | `*.openhands.example.com` | + +**Obtain a wildcard TLS certificate signed by a well-known certificate authority (CA) such as Let's Encrypt** +for `*.`, then copy the certificate +(`.pem` or `.crt`) and private key (`.pem` or `.key`) to the VM. Self-signed certificates +are not supported for the OpenHands application. + + + Obtain a certificate with SANs (Subject Alternative Names) for each of these hostnames: + + - `admin.` + - `app.` + - `auth.` + - `analytics.` + - `llm-proxy.` + - `runtime-api.` + - `runtime.` + + By default, each sandbox runtime gets its own dynamic hostname, which only a wildcard + certificate can cover. When you configure OpenHands, set **Sandbox Routing Mode** to + **Path-based** so all sandboxes are served under `runtime.` instead. + + + + If you don't provide TLS certificates during installation, the Admin Console will use a + self-signed certificate and your browser will display a security warning. You can still + upload your certificate afterward through the Admin Console. + + + +## 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 +- (Optional) [External PostgreSQL](/enterprise/external-postgres) instance provisioned if using your own database + + + 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 "admin.${BASE_DOMAIN}" "app.${BASE_DOMAIN}" "test-runtime.${BASE_DOMAIN}"; do + echo "[DNS] $h" + getent hosts "$h" || nslookup "$h" +done +``` + +Expected: each hostname resolves to your VM's public IP address through the +wildcard record. + +### 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 | +| `*.` DNS + cert SAN | Application services and sandboxes are addressed by hostnames under the base domain | +| `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 + +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. + +![Installer Dashboard](/enterprise/images/admin-dashboard.png) + +### 2. Name your instance + +Enter a name for your instance (e.g., your company name or environment identifier). +Select **"Outbound requests allowed"** for Network Availability, then click **Continue**. + +![Instance name and network availability](/enterprise/images/install-instance-name.png) + +### 3. Run the installation commands + +The install guide provides commands to run on your VM. SSH into your VM and execute them in order: + +1. **Select a version** -- the latest version is pre-selected +2. **Download the installation assets** -- copy and run the `curl` command shown +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, see +[Troubleshooting](/enterprise/troubleshooting) to generate a support +bundle and open a support ticket. + + + **We recommend providing your TLS certificates during installation.** Pass the full-chain certificate and matching private key stored on your VM: + + ```bash + sudo ./openhands install --license license.yaml \ + --tls-cert ~/certificate.pem \ + --tls-key ~/private-key.pem + ``` + + Replace the example paths with your actual certificate paths. + You can also omit the `--tls-cert` and `--tls-key` flags and upload certificates later through + the Admin Console. + + For trials and production deployments, use a publicly trusted TLS certificate whenever possible. + Private CA certificates may work for users after manual trust setup, but external integrations + such as GitHub, GitLab, Slack, Jira, and Bitbucket must also trust the certificate chain. If they + do not, webhook or OAuth callbacks can fail TLS verification and repeatedly retry. + + +![Installation commands](/enterprise/images/install-commands.png) + +### 4. Access the Admin Console + +Once the install command completes, the Admin Console is available at: +- `https://admin.:30000` (if you provided TLS certificates) +- `http://:30000` (if you did not use the `--tls-cert` and `--tls-key` flags on the `install` command) + +If you did not provide TLS certificates with the `install` command, your browser will display a security warning. +Click **Advanced**, then **Proceed** to continue to the Admin Console. + +![Self-signed certificate warning](/enterprise/images/self-signed-cert-warning.png) + +### 5. Upload TLS certificate (if not provided with the install command) + +If you did not provide certificates with the `install` command, select **"Upload your own"**, +enter `admin.` under **Hostname**, upload your private key and SSL certificate, then click **Continue**. + +If you upload a private CA certificate, make sure any external webhook or OAuth provider that +calls OpenHands also trusts that CA. + +![Upload TLS certificate](/enterprise/images/upload-tls-certificate.png) + +### 6. Log in to the Admin Console + +Enter the password you set during installation and click **Log in**. + +![Admin Console login](/enterprise/images/admin-console-login.png) + +### 7. Configure the cluster + +You will be prompted to add additional nodes to the cluster. +For a single-node deployment, click **Continue** to skip this step. + +![Configure cluster nodes](/enterprise/images/configure-cluster-nodes.png) + +## Configure OpenHands + +You should now see the application configuration page. + +![Configure OpenHands](/enterprise/images/configure-openhands.png) + +### Domain Configuration + +- Keep the Hostname Configuration Mode set to **"Simple (default)"** +- Enter your base domain (e.g., `openhands.example.com`) + +### Certificate Configuration + +- Upload your **TLS Certificate** (`.crt` or `.pem`) +- Upload your **TLS Private Key** (`.key` or `.pem`) +- Optionally upload the root **CA Certificate** for your TLS certificates + +### LLM Configuration + +Choose an LLM provider from the LLM Configuration dropdown and enter the details +from that provider. + +![LLM Configuration provider dropdown](/enterprise/images/llm-configuration-provider-dropdown.png) + +For example, if you use Anthropic, enter your API key from the +[Anthropic Console](https://console.anthropic.com/). + +### Database Configuration + +By default, OpenHands Enterprise uses a bundled PostgreSQL database. If you need to use your +own PostgreSQL instance (for example, to integrate with existing database infrastructure or +meet specific backup/HA requirements), see [External PostgreSQL](/enterprise/external-postgres) +for setup instructions. + +### GitHub Authentication + +Enable GitHub Authentication in the Admin Console, then follow these steps to create and +configure a GitHub App. + +#### Create a GitHub App + +Run our [script](https://github.com/All-Hands-AI/OpenHands-Cloud/tree/main/scripts/create_github_app) to create a GitHub App configured for your install. + +#### Map GitHub App values to Admin Console + +Go back to the Installer Admin Console in your browser and enter the values from the Create GitHub App script output. For the private key, upload the file from the `keys` directory of the script location. + +See [GitHub](/enterprise/integrations/github) for GitHub App installation, +`@openhands` resolver behavior, pull request review identity, and repository-level +review controls. + +### Additional Integrations + +If your team uses Jira Data Center or Bitbucket Data Center, follow these guides +to configure Admin Console values before deployment and complete webhook setup +inside OpenHands after deployment. + + + + Configure Bitbucket Data Center login, repository access, bot identity, and pull request webhooks. + + + Configure Jira issue triggers, OAuth account linking, service account credentials, and Jira webhooks. + + + +After filling in all fields, click **Continue** at the bottom of the page. + +## Deploy and Verify + +OpenHands will begin deploying. You can expect the deployment status to transition from +**Missing** to **Unavailable** to **Ready**. This typically takes 5-10 minutes. + +![Deployment in progress](/enterprise/images/deployment-in-progress.png) + +Click **Details** next to the deployment status to monitor individual resources. Resources +shown in orange are still deploying -- wait until all resources are ready. + +![Deployment status details](/enterprise/images/deployment-status-details.png) + +## First Login + +Once the deployment status shows **Ready**, navigate to `https://app.` +and click the **Login with GitHub** tile. + + +Accept the Terms of Service and click **Continue**. + +![Accept Terms of Service](/enterprise/images/accept-terms-of-service.png) + +OpenHands Enterprise is now running. You can open a repository or start a new conversation. + +![OpenHands is ready](/enterprise/images/openhands-ready.png) + +## Next Steps + + + + Learn about OpenHands Enterprise features, integrations, and deployment options. + + + Get the most out of your AI coding agents with effective prompting techniques. + + + Collect diagnostics, inspect workloads, and contact OpenHands Support. + + + Explore the full OpenHands documentation for usage guides and features. + + diff --git a/enterprise/vm-install/google.mdx b/enterprise/vm-install/google.mdx index cffb119b0..2cc34ff85 100644 --- a/enterprise/vm-install/google.mdx +++ b/enterprise/vm-install/google.mdx @@ -198,12 +198,12 @@ Before opening the installer dashboard, confirm that: - The VM meets the CPU, memory, storage, OS and kernel requirements. - Wildcard DNS resolves to the static external IP from the VM. - Ports 80 and 443 are reachable by application clients, and port 30000 is reachable from your administrator network. -- The VM can reach the [distribution endpoints](/enterprise/quick-start#outbound-connectivity-checks), GitHub, `oauth2.googleapis.com` and the Vertex endpoint for your selected location. +- The VM can reach the [distribution endpoints](/enterprise/vm-install/generic-vm#outbound-connectivity-checks), GitHub, `oauth2.googleapis.com` and the Vertex endpoint for your selected location. - Your trusted certificate covers service and dynamic sandbox hostnames, and its private key matches. - Vertex credentials and GitHub App prerequisites are ready. -Run the shared [DNS checks](/enterprise/quick-start#dns-checks) and -[outbound connectivity checks](/enterprise/quick-start#outbound-connectivity-checks) +Run the shared [DNS checks](/enterprise/vm-install/generic-vm#dns-checks) and +[outbound connectivity checks](/enterprise/vm-install/generic-vm#outbound-connectivity-checks) on the VM. An HTTP response establishes network reachability; authenticate and run a conversation after deployment to validate inference.