From 50052d403699f3509ed53fe3f724330ea87b0e32 Mon Sep 17 00:00:00 2001 From: Rajiv Shah Date: Fri, 2 Oct 2026 22:33:52 -0500 Subject: [PATCH 1/7] docs: add tested Google Cloud Replicated quick start --- docs.json | 1 + enterprise/quick-start.mdx | 2 + enterprise/vm-install/google.mdx | 349 +++++++++++++++++++++++++++++++ 3 files changed, 352 insertions(+) create mode 100644 enterprise/vm-install/google.mdx diff --git a/docs.json b/docs.json index 9babff37f..75f677384 100644 --- a/docs.json +++ b/docs.json @@ -529,6 +529,7 @@ "enterprise/enterprise-vs-oss", "enterprise/sizing-guide", "enterprise/quick-start", + "enterprise/vm-install/google", { "group": "Custom Sandbox Images", "icon": "box", diff --git a/enterprise/quick-start.mdx b/enterprise/quick-start.mdx index 57d398478..8d42cc0d8 100644 --- a/enterprise/quick-start.mdx +++ b/enterprise/quick-start.mdx @@ -35,6 +35,8 @@ Before you begin, make sure you have the following ready: 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. diff --git a/enterprise/vm-install/google.mdx b/enterprise/vm-install/google.mdx new file mode 100644 index 000000000..a6627d8d5 --- /dev/null +++ b/enterprise/vm-install/google.mdx @@ -0,0 +1,349 @@ +--- +title: Google Cloud Quick Start +description: Install OpenHands Enterprise on Google Compute Engine with Replicated Embedded Cluster and configure Vertex AI. +icon: google +--- + +Install OpenHands Enterprise on a dedicated Google Compute Engine VM using +Replicated Embedded Cluster. The installer manages Kubernetes on the VM. + +For an existing Kubernetes cluster, see [Install with Helm](/enterprise/k8s-install/installation). +This guide covers provisioning, DNS and TLS, installation, Vertex AI configuration +and a completed conversation. Use the +[Admin Console Configuration reference](/enterprise/vm-install/admin-console-configuration) +for optional settings. + +## Prerequisites + +- An Enterprise trial or licensed installer account. +- Google Cloud CLI authenticated to a project with Compute Engine and Cloud DNS enabled. +- Permission to create a VM, persistent disk, VPC, subnet, firewall rules and static external IP. +- Regional N2 vCPU, SSD and external-IP quota for the resources below. +- A dedicated SSH key pair and the public IPv4 /32 of your workstation or VPN. +- A base domain you control, a wildcard DNS record and a publicly trusted wildcard certificate. +- Credentials for your LLM provider and a GitHub account that can create and install a GitHub App. + +## Plan the Google Cloud Resources + +| Resource | Purpose | +| --- | --- | +| Dedicated VPC and subnet | Isolate the VM's network and firewall rules | +| Regional static external IPv4 | Stable address for DNS and inbound access | +| VM-specific network tag | Target firewall rules to this installation | +| Ubuntu 24.04 LTS x86-64 VM | Run the installer and embedded cluster | +| Persistent SSD boot disk | Store cluster, database and sandbox data | +| Wildcard DNS and trusted TLS | Secure services and dynamic sandbox hostnames | + +The evaluated VM uses `n2-standard-16` (16 vCPUs, 64 GiB RAM) and a 500 GiB +`pd-ssd` boot disk. The public trial baseline is 16 vCPUs, 64 GB RAM and +200 GB storage, with disk P99 write latency no higher than 10 ms. Provisioned +storage capacity alone does not establish latency: the installer preflight +must pass. Use the [Sizing Guide](/enterprise/sizing-guide) for larger deployments. + +The example uses persistent storage rather than Local SSD. The VM has no attached +Google Cloud service account; provider credentials are configured separately +through the Admin Console. A VM's infrastructure identity and its model-inference +identity are separate decisions. + +## Provision Infrastructure + +Use a dedicated resource name and pass the target project explicitly to each +command. Inspect existing resources before creating new ones. + +```bash +export PROJECT="" +export ZONE="us-central1-a" +export REGION="us-central1" +export VM="openhands-replicated-eval" +export NETWORK="$VM" +export ADMIN_CIDR="/32" +export SSH_PUBLIC_KEY_FILE="$HOME/.ssh/openhands-google.pub" +export BASE_DOMAIN="google.openhands.example.com" + +gcloud auth login +gcloud compute regions describe "$REGION" --project="$PROJECT" +gcloud compute machine-types describe n2-standard-16 \ + --project="$PROJECT" --zone="$ZONE" +gcloud compute images describe-from-family ubuntu-2404-lts-amd64 \ + --project=ubuntu-os-cloud +gcloud compute instances list --project="$PROJECT" +``` + +Generate a dedicated SSH key without replacing an existing file: + +```bash +ssh-keygen -t ed25519 -f "$HOME/.ssh/openhands-google" -C openhands-google +``` + +### Create Networking and Ingress Rules + +```bash +gcloud compute networks create "$NETWORK" --project="$PROJECT" --subnet-mode=custom +gcloud compute networks subnets create "$NETWORK" --project="$PROJECT" \ + --region="$REGION" --network="$NETWORK" --range=10.90.0.0/24 +gcloud compute addresses create "$VM" --project="$PROJECT" \ + --region="$REGION" --network-tier=PREMIUM +export VM_IP=$(gcloud compute addresses describe "$VM" --project="$PROJECT" \ + --region="$REGION" --format='value(address)') +gcloud compute firewall-rules create "$VM-web" --project="$PROJECT" \ + --network="$NETWORK" --direction=INGRESS --allow=tcp:80,tcp:443 \ + --source-ranges=0.0.0.0/0 --target-tags="$VM" +gcloud compute firewall-rules create "$VM-admin" --project="$PROJECT" \ + --network="$NETWORK" --direction=INGRESS --allow=tcp:22,tcp:30000 \ + --source-ranges="$ADMIN_CIDR" --target-tags="$VM" +``` + +Keep SSH and the Admin Console restricted to an administrator address or approved +network. Application HTTPS must be reachable by users and configured OAuth or +webhook providers. Choose a subnet range that does not overlap your connected networks. + +### Create the VM + +Resolve and review the current Ubuntu image, then pin the chosen image name. + +```bash +export IMAGE="" +KEY_METADATA=$(mktemp) +printf 'openhands:%s\n' "$(cat "$SSH_PUBLIC_KEY_FILE")" > "$KEY_METADATA" +gcloud compute instances create "$VM" --project="$PROJECT" --zone="$ZONE" \ + --machine-type=n2-standard-16 --image="$IMAGE" --image-project=ubuntu-os-cloud \ + --boot-disk-type=pd-ssd --boot-disk-size=500GB \ + --subnet="$NETWORK" --address="$VM_IP" --tags="$VM" \ + --no-service-account --no-scopes --metadata=block-project-ssh-keys=true \ + --metadata-from-file=ssh-keys="$KEY_METADATA" +rm "$KEY_METADATA" +ssh -i "$HOME/.ssh/openhands-google" "openhands@$VM_IP" +``` + +### Verify the OS and Kernel + +```bash +cat /etc/os-release +uname -r +nproc +free -h +df -h / /var/lib +sudo -n true +``` + +Ubuntu 24.04 images can use different kernel families. The evaluated Google image +`ubuntu-2404-noble-amd64-v20260918` booted kernel `7.0.0-1011-gcp`. The public +Quick Start cautions that very new kernels may not work with Sysbox; the evaluation +selected Ubuntu's generic 6.8 LTS kernel before installation. This observation +does not establish that kernel 7.0 fails with Sysbox. + +If your selected image needs the same change, refresh package indexes and install +the supported LTS kernel: + +```bash +sudo apt-get update +sudo apt-get install -y linux-generic +sudo grep -E 'submenu |menuentry ' /boot/grub/grub.cfg +``` + +Use the actual generated GRUB entry to select the installed kernel. See +[Ubuntu's GRUB configuration guide](https://help.ubuntu.com/community/Grub2/Setup). +Retain the previous kernel for rollback, reboot, and verify `uname -r`. Package +versions change; do not assume the evaluation's exact version is current. + +## Configure DNS and TLS + +Create a wildcard A record in your domain's managed zone: + +```bash +export DNS_PROJECT="" +export DNS_ZONE="" +gcloud dns record-sets create "*.${BASE_DOMAIN}." --project="$DNS_PROJECT" \ + --zone="$DNS_ZONE" --type=A --ttl=300 --rrdatas="$VM_IP" +``` + +Obtain a publicly trusted certificate for `*.${BASE_DOMAIN}`. Let's Encrypt wildcard +issuance uses DNS-01 validation. Follow the +[Certbot manual DNS instructions](https://eff-certbot.readthedocs.io/en/stable/using.html#manual) +or your certificate authority's procedure. Keep private keys outside source control, +copy the full chain and key securely to the VM, and record how renewal and certificate +replacement will be handled. Manual issuance does not configure automatic renewal. + +Run the shared Quick Start's DNS and outbound checks **from the VM**, and confirm +all service names and a test runtime name resolve to its static IP. Verify the +certificate chain, wildcard SAN, key match and expiration before installation. + +## Prepare Vertex AI Access + +Use a Google Cloud project with billing enabled, the Vertex AI API enabled and +access to your chosen model in the selected location. The inference project can +be different from the project hosting the VM. + +```bash +export VERTEX_PROJECT="" +export VERTEX_LOCATION="us-central1" +gcloud services enable aiplatform.googleapis.com --project="$VERTEX_PROJECT" +``` + +Have your Google Cloud administrator provide a service-account JSON key for the +inference project with permission to invoke the selected model. The +[Vertex AI User role](https://cloud.google.com/vertex-ai/docs/general/access-control) +(`roles/aiplatform.user`) provides model-use permissions; an administrator can +choose a narrower custom role under your organization's access policy. +Follow Google's [service-account key procedure](https://cloud.google.com/iam/docs/keys-create-delete) +if a new key is needed. Keep the JSON file outside source control, restrict access +and follow your organization's key rotation policy. If organization policy +prevents JSON keys, resolve the supported authentication path with OpenHands +Support before proceeding. + +The tested Replicated configuration uploads this JSON file through the Admin +Console. Signing in to `gcloud` on your workstation or attaching a service account +to the VM does not configure that field. Check +[model and location availability](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations) +before choosing your model. The validated combination was `gemini-2.5-flash` in +`us-central1`; other models and locations require their own validation. + +## Preflight Validation + +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. +- 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) +on the VM. An HTTP response establishes network reachability; authenticate and +run a conversation after deployment to validate inference. + +## Run the Installer + +### 1. Open the Installer Dashboard + +[Register for an Enterprise trial](https://install.r9.all-hands.dev/openhands/signup) +or log in with your licensed account. Select **View install guide**, name the +instance and choose **Outbound requests allowed** for this connected deployment. + +### 2. Download and Run the Installation Commands + +SSH into the Google VM. Select a release, then copy the instance-specific download, +extract and install commands from the dashboard. The extracted assets include +your license. Use the current dashboard commands rather than commands from a +previous installation. + +Run the interactive installer in a real terminal. Supply the trusted full-chain +certificate and matching private key already copied to the VM: + +```bash +sudo ./openhands install --license license.yaml \ + --hostname "admin.${BASE_DOMAIN}" \ + --tls-cert /path/to/fullchain.pem \ + --tls-key /path/to/privkey.pem +``` + +Set `BASE_DOMAIN` in this VM shell before running the command. Replace the file +paths with your actual certificate files. Set the Admin Console password when +prompted and require the host and storage-latency preflights to pass. + +If installation fails after preflights pass, follow +[Troubleshooting](/enterprise/troubleshooting) to generate a support bundle. + +### 3. Open the Admin Console + +Open `https://admin.:30000` from your administrator network and +log in with the password created during installation. For a single-node install, +continue past the additional-node screen. + +The tested installer printed an HTTP URL despite being invoked with TLS options. +Use the HTTPS endpoint and confirm that the browser trusts the supplied certificate. + +## Configure OpenHands + +Select **Config** in the Admin Console. The +[Admin Console Configuration reference](/enterprise/vm-install/admin-console-configuration) +describes all available fields for the installed release. + +### Domain and Certificates + +Keep **Hostname Configuration Mode** set to **Simple (default)** and enter your +base domain. Upload the trusted full-chain **TLS Certificate** and matching +**TLS Private Key** for the application. The certificate supplied to the installer +and the certificate configured for the application serve different setup steps. + +### Vertex AI Models + +In **LLM Configuration**, configure the administrator-managed provider: + +| Setting | Value | +| --- | --- | +| Provider | Google | +| Google API type | Google Cloud Platform (Vertex AI) | +| Project | Your Vertex inference project ID | +| Location | Your model's supported location; tested with `us-central1` | +| Service-account credentials | Upload your service-account JSON file | +| Models | One model ID per line; tested with `gemini-2.5-flash` | + +Leave **Allow users to configure their own LLM providers (BYOK)** disabled when +users should use the administrator-managed models. Save and deploy these values +through the Admin Console. The deployment configures the bundled gateway and +makes the model available in OpenHands. + +### Database and Sandbox Configuration + +The tested configuration uses bundled PostgreSQL, the default Sysbox isolation +runtime and subdomain routing. For an external database, follow +[External PostgreSQL](/enterprise/external-postgres). Size storage for your +workload and establish backup and recovery procedures for the persistent data. + +### GitHub Authentication + +Enable GitHub Authentication and run the +[official GitHub App helper](https://github.com/OpenHands/OpenHands-Cloud/tree/main/scripts/create_github_app) +with your instance's base domain. Use the default flat DNS layout for Simple mode. +Create a dedicated GitHub App and install it on the repositories you want this +instance to access. + +Map the helper's output to **GitHub App Client ID**, **Client Secret**, **App ID**, +**App Slug** and **Webhook Secret**. Upload the generated private key in +**GitHub App Private Key**. Keep the generated secrets outside source control. +See [GitHub integration](/enterprise/integrations/github) for repository and +webhook configuration. + +Configure optional integrations after the baseline workflow passes. + +## Deploy and Verify + +Save the configuration, review application preflights and deploy the new sequence. +Wait for **Ready** on the Admin Console dashboard. + +1. Open `https://app.` and sign in with GitHub. +2. Check that the administrator-managed model appears in the model selector. The tested default profile displayed `openhands/gemini-2.5-flash`. +3. Start a small conversation that asks the agent to print its working directory and write and read a temporary marker file. Confirm terminal output and a completed response. +4. Open **Open Repository**, select an installed repository and branch, and run a read-only conversation that reads its README and reports `git status`. +5. Verify persistent database storage and record the installation versions and test results. + +Deployment readiness and an HTTP response are useful checks. The completed +conversations verify that authentication, model inference, sandbox startup, +terminal tools and repository access work together. + +## Agent-Assisted Installation + +The [Replicated installation skill proposal](https://github.com/OpenHands/extensions/pull/458) +provides an agent workflow for resource planning, preflights, installation and +end-to-end checks. Its publication to the main skill registry is pending. Use +these public instructions as the installation reference and review the proposed +skill before using it with cloud credentials. + +## Validation Scope + +Infrastructure, SSH, Ubuntu generic kernel `6.8.0-146`, DNS, certificate files and +outbound reachability were checked on the evaluation VM. Replicated release `0.74.0` installation completed with installer +`v2.19.2+k8s-1.36` and Kubernetes `v1.36.1+k0s.0`; host preflights passed without +overrides, and the Admin Console returned HTTP 200 over trusted HTTPS. Application sequence 0 reached Ready, all workloads including a warm Sysbox runtime +became ready, service TLS checks passed, and the persistent-storage guard passed. +GitHub login, administrator-managed Vertex Gemini 2.5 Flash inference, sandbox +startup and terminal file operations passed in a completed conversation. GitHub +repository discovery, branch selection and a read-only repository conversation +also passed: the sandbox checked out the selected main branch, read its README +and reported a clean working tree. +The boot filesystem is persistent storage; +backup, restore, upgrades, additional nodes and automatic certificate renewal have +not yet been tested in this evaluation. From 148659c33bc57c060cad9be5ad48d9cdc1736de9 Mon Sep 17 00:00:00 2001 From: Rajiv Shah Date: Fri, 2 Oct 2026 22:36:25 -0500 Subject: [PATCH 2/7] docs: split Enterprise quick start into AWS and Generic VM guides --- docs.json | 2 + enterprise/quick-start.mdx | 473 +++++---------------------- enterprise/vm-install/aws.mdx | 336 +++++++++++++++++++ enterprise/vm-install/generic-vm.mdx | 438 +++++++++++++++++++++++++ enterprise/vm-install/google.mdx | 6 +- 5 files changed, 858 insertions(+), 397 deletions(-) create mode 100644 enterprise/vm-install/aws.mdx create mode 100644 enterprise/vm-install/generic-vm.mdx diff --git a/docs.json b/docs.json index 75f677384..c9cd4b0fe 100644 --- a/docs.json +++ b/docs.json @@ -529,7 +529,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/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/vm-install/aws.mdx b/enterprise/vm-install/aws.mdx new file mode 100644 index 000000000..2444659f9 --- /dev/null +++ b/enterprise/vm-install/aws.mdx @@ -0,0 +1,336 @@ +--- +title: AWS Quick Start +description: Get started with a 30-day trial of OpenHands Enterprise. +icon: rocket +--- + +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 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. + + + +## 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 + ``` + + 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. + + 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..7e06a4404 --- /dev/null +++ b/enterprise/vm-install/generic-vm.mdx @@ -0,0 +1,438 @@ +--- +title: Generic VM Quick Start +description: Get started with a 30-day trial of OpenHands Enterprise. +icon: rocket +--- + +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 a6627d8d5..397416779 100644 --- a/enterprise/vm-install/google.mdx +++ b/enterprise/vm-install/google.mdx @@ -205,12 +205,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. From baafb9e31db8537bb295a05c456ac46ee407c0d0 Mon Sep 17 00:00:00 2001 From: Rajiv Shah Date: Fri, 2 Oct 2026 22:45:37 -0500 Subject: [PATCH 3/7] docs: add Azure Replicated quick start --- docs.json | 1 + enterprise/quick-start.mdx | 3 + enterprise/vm-install/azure.mdx | 735 ++++++++++++++++++++++++++++++++ llms-full.txt | 733 +++++++++++++++++++++++++++++++ llms.txt | 1 + 5 files changed, 1473 insertions(+) create mode 100644 enterprise/vm-install/azure.mdx diff --git a/docs.json b/docs.json index c9cd4b0fe..ed405abd8 100644 --- a/docs.json +++ b/docs.json @@ -531,6 +531,7 @@ "enterprise/quick-start", "enterprise/vm-install/aws", "enterprise/vm-install/google", + "enterprise/vm-install/azure", "enterprise/vm-install/generic-vm", { "group": "Custom Sandbox Images", diff --git a/enterprise/quick-start.mdx b/enterprise/quick-start.mdx index 737e84d54..c08035cc7 100644 --- a/enterprise/quick-start.mdx +++ b/enterprise/quick-start.mdx @@ -14,6 +14,9 @@ Choose the guide for your infrastructure: Provision a Compute Engine VM and configure administrator-managed Vertex AI models. + + Provision an Azure VM, start with Anthropic and optionally configure administrator-managed Azure OpenAI models. + Prepare a Linux VM on-premises or on another cloud provider, then install and configure OpenHands. diff --git a/enterprise/vm-install/azure.mdx b/enterprise/vm-install/azure.mdx new file mode 100644 index 000000000..3de223846 --- /dev/null +++ b/enterprise/vm-install/azure.mdx @@ -0,0 +1,735 @@ +--- +title: Azure Quick Start +description: Provision an Azure Linux VM and install OpenHands Enterprise with Replicated, starting with Anthropic inference. +icon: microsoft +--- + +Install OpenHands Enterprise on a dedicated Azure VM using Replicated Embedded +Cluster. The installer manages Kubernetes on the VM. Start with an Anthropic API +key, then optionally configure Azure OpenAI through the bundled LLM gateway. + +For an AKS deployment, use [Install with Helm](/enterprise/k8s-install/installation). +AKS node pools, Helm values, and Kubernetes storage classes do not configure this +VM installation. + +## Prerequisites + +- [Register for an Enterprise trial](https://install.r9.all-hands.dev/openhands/signup), or use an existing licensed installer account. +- Azure CLI and an Azure subscription with permission to create a resource group, + VM, managed disk, virtual network, subnet, NIC, network security group, and public IP. +- Regional total-vCPU and VM-family quota for a VM with at least 16 vCPUs and 64 GB RAM. +- An SSH key pair and the public IPv4 CIDR of the administrator's workstation or VPN. +- A base domain you control and permission to change its DNS records. +- A publicly trusted wildcard certificate and its private key. +- An Anthropic API key and a GitHub account with permission to create/install a GitHub App. + +Subscription `Contributor` normally covers the infrastructure in this guide. +Azure RBAC assignments and model inference permissions are separate. If you +choose Microsoft Entra authentication for Azure OpenAI, have an authorized +administrator grant the required inference role. + +## Plan the Azure Resources + +| Resource | Purpose | +| --- | --- | +| Dedicated resource group | Scope the evaluation resources and cleanup | +| VNet and subnet | Private network for the VM and embedded cluster | +| Network security group | Permit HTTP/HTTPS and restrict SSH/Admin Console access | +| Standard static IPv4 public IP and NIC | Stable inbound address and explicit outbound connectivity | +| Ubuntu 24.04 LTS x86-64 VM | Run the Replicated installer and embedded Kubernetes cluster | +| Premium SSD managed OS disk | Persist embedded-cluster, database, and sandbox data | +| Wildcard DNS and TLS | Route and secure application services and dynamic sandbox hostnames | +| Optional Azure OpenAI resource and deployment | Provide inference through the bundled LLM gateway | + +The example uses `Standard_D16s_v3` (16 vCPUs, 64 GB RAM) and a 1,024 GiB +Premium SSD OS disk. The larger disk selects the P30 performance tier; it is not +a new capacity requirement. The trial baseline is 200 GB and P99 write latency +below 10 ms. A disk's provisioned IOPS do not guarantee that latency: run the +installer's host preflights. See [Premium storage performance](https://learn.microsoft.com/en-us/azure/virtual-machines/premium-storage-performance) +and the [Sizing Guide](/enterprise/sizing-guide) for larger deployments. + +Use persistent managed storage for installation data. Azure temporary/resource +disks can be lost during host maintenance or redeployment. This example keeps +installation data on the managed OS disk rather than adding a temporary disk. + +## Provision Infrastructure + +Run these commands from your administrator workstation using Bash. + +### 1. Select the Subscription and Check Capacity + +```bash +az login +export SUBSCRIPTION_ID="" +export LOCATION="eastus2" +export RG="openhands-replicated-eval-rg" +export VM="openhands-replicated-eval" +export VM_SIZE="Standard_D16s_v3" +export ADMIN_CIDR="/32" +export SSH_PUBLIC_KEY_FILE="$HOME/.ssh/openhands-azure.pub" +export BASE_DOMAIN="azure.openhands.example.com" + +az account set --subscription "$SUBSCRIPTION_ID" +az account show --query '{name:name,id:id,tenant:tenantId}' --output table +az vm list-usage --location "$LOCATION" --output table +az vm list-skus --location "$LOCATION" --size "$VM_SIZE" --all \ + --query '[?resourceType==`virtualMachines`].{name:name,restrictions:restrictions}' \ + --output json +az vm image show --location "$LOCATION" \ + --urn Canonical:ubuntu-24_04-lts:server:latest --output table +``` + +Verify available total and VM-family vCPU quota and SKU restrictions before +creating resources. A VM family can have zero quota even when total regional +quota is available. Request a quota increase or choose another supported +x86-64 size with at least 16 vCPUs and 64 GB RAM. Avoid a zonal deployment if +that zone is restricted for your subscription. + +Ensure `Microsoft.Compute`, `Microsoft.Network`, and `Microsoft.Storage` are +registered under **Subscriptions → Resource providers**. Registration may need +a subscription administrator. This deployment does not require AKS or the +`Microsoft.ContainerService` provider. + +Use an existing SSH public key, or generate a dedicated key pair without +replacing an existing file: + +```bash +ssh-keygen -t ed25519 -f "$HOME/.ssh/openhands-azure" -C openhands-azure +``` + +### 2. Create Networking and Ingress Rules + +Use a new, dedicated resource group. Check that its name is unused before +proceeding; do not place evaluation resources in a shared production group. + +```bash +az group exists --name "$RG" +az group create --name "$RG" --location "$LOCATION" + +az network vnet create --resource-group "$RG" --name "$VM-vnet" \ + --address-prefixes 10.82.0.0/16 \ + --subnet-name openhands --subnet-prefixes 10.82.1.0/24 +az network nsg create --resource-group "$RG" --name "$VM-nsg" + +az network nsg rule create --resource-group "$RG" --nsg-name "$VM-nsg" \ + --name admin --priority 100 --source-address-prefixes "$ADMIN_CIDR" \ + --destination-port-ranges 22 30000 --protocol Tcp --access Allow +az network nsg rule create --resource-group "$RG" --nsg-name "$VM-nsg" \ + --name web --priority 110 --source-address-prefixes Internet \ + --destination-port-ranges 80 443 --protocol Tcp --access Allow + +az network public-ip create --resource-group "$RG" --name "$VM-ip" \ + --sku Standard --allocation-method Static --version IPv4 +az network nic create --resource-group "$RG" --name "$VM-nic" \ + --vnet-name "$VM-vnet" --subnet openhands \ + --network-security-group "$VM-nsg" --public-ip-address "$VM-ip" +``` + +Choose non-overlapping VNet/subnet address ranges for your environment. The +example exposes ports 80/443 so GitHub callbacks and users can reach OpenHands. +Ports 22/30000 are restricted to your administrator CIDR. Corporate firewalls, +subnet NSGs, and host firewall rules must also permit the required traffic. +Do not expose Kubernetes or etcd ports publicly. + +The NIC's public IP provides explicit VM outbound connectivity. If you use a +private VM instead, provide a NAT gateway or your organization's approved egress +path and a supported ingress path with DNS/TLS and integration reachability. + +### 3. Create the VM and Persistent Disk + +```bash +az vm create --resource-group "$RG" --name "$VM" \ + --nics "$VM-nic" \ + --image Canonical:ubuntu-24_04-lts:server:latest \ + --size "$VM_SIZE" --admin-username azureuser \ + --authentication-type ssh --ssh-key-values "$SSH_PUBLIC_KEY_FILE" \ + --storage-sku Premium_LRS --os-disk-size-gb 1024 \ + --os-disk-name "$VM-os" + +export VM_IP=$(az network public-ip show --resource-group "$RG" \ + --name "$VM-ip" --query ipAddress --output tsv) +ssh -i "$HOME/.ssh/openhands-azure" "azureuser@$VM_IP" +``` + +Local embedded-cluster ports must be available: `2379`, `7443`, `9099`, +`10248`, `10257`, and `10259` (TCP). These do not need public NSG rules. + +On the VM, verify the OS, kernel, memory, disk space, and sudo access: + +```bash +cat /etc/os-release +uname -m +uname -r +nproc +free -h +lsblk +findmnt /var/lib +sudo -v +``` + +Use Ubuntu 24.04 LTS and check the actual kernel against the +[Sysbox requirements](/enterprise/docker-in-sandbox). Do not infer compatibility +from the Azure image name alone. The Replicated host preflight must pass before +installation; do not bypass a failed storage or runtime check. + +### 4. Configure DNS + +Create a wildcard A record for `*.` pointing to the static `VM_IP`. +You can keep DNS with your existing provider; Azure hosting does not require +Azure DNS. + +If your authoritative zone is already hosted in Azure DNS, run from your +workstation using the existing zone's resource group: + +```bash +export DNS_RG="" +export DNS_ZONE="example.com" +# Relative name for *.azure.openhands.example.com in example.com: +export DNS_RECORD="*.azure.openhands" +az network dns record-set a add-record --resource-group "$DNS_RG" \ + --zone-name "$DNS_ZONE" --record-set-name "$DNS_RECORD" \ + --ipv4-address "$VM_IP" +``` + +Do not append an IP to an existing record set that serves another deployment. +If you create a new Azure DNS zone, delegate it at its parent or registrar to +its assigned name servers before expecting public resolution. DNS zone access +may require a separate role or DNS administrator. + +### 5. Obtain and Copy TLS Files + +Obtain a publicly trusted wildcard certificate for `*.`. For +Let's Encrypt, use a DNS-01 challenge with your authoritative DNS provider. +HTTP-01 cannot issue a wildcard certificate. Keep provider credentials and +private keys out of repositories and command output. + +If you do not already have a certificate, install Certbot using its +[official instructions](https://certbot.eff.org/instructions). For an evaluation, +run a manual DNS-01 challenge on your administrator workstation: + +```bash +sudo certbot certonly --manual --preferred-challenges dns \ + --cert-name openhands-azure -d "*.${BASE_DOMAIN}" +``` + +Enter your ACME contact email and review the certificate authority's terms when +prompted. Certbot displays a TXT value to publish at +`_acme-challenge.`. Create it with the authoritative DNS provider, +wait for public resolution, and then continue the challenge. For Azure DNS, +the TXT record's relative name for this example is +`_acme-challenge.azure.openhands` in the `example.com` zone. + +```bash +dig +short TXT "_acme-challenge.${BASE_DOMAIN}" +``` + +After issuance, Certbot saves the full chain and private key under +`/etc/letsencrypt/live/openhands-azure/`. Transfer those files through your +approved private channel, or substitute existing certificate files below. See +[Certbot's manual challenge guide](https://eff-certbot.readthedocs.io/en/stable/using.html#manual). +Manual challenges need to be repeated for renewal unless you configure an +authentication hook; choose a DNS plugin for unattended certificate issuance. + +Copy the full certificate chain and private key to a private directory on the +VM using your existing certificate files: + +```bash +ssh -i "$HOME/.ssh/openhands-azure" "azureuser@$VM_IP" \ + 'mkdir -p ~/tls && chmod 700 ~/tls' +scp -i "$HOME/.ssh/openhands-azure" /path/to/fullchain.pem \ + "azureuser@$VM_IP:tls/certificate.pem" +scp -i "$HOME/.ssh/openhands-azure" /path/to/privkey.pem \ + "azureuser@$VM_IP:tls/private-key.pem" +ssh -i "$HOME/.ssh/openhands-azure" "azureuser@$VM_IP" \ + 'chmod 600 ~/tls/*.pem' +``` + +Plan certificate renewal and upload the renewed certificate through the supported +Admin Console workflow. Initial issuance does not configure automatic renewal. + +For a Simple-mode install, one wildcard covers `admin`, `app`, `auth`, +`analytics`, `llm-proxy`, `runtime-api`, and dynamic `-runtime` hostnames under +the base domain. If wildcard certificates are unavailable, follow the +[VM DNS/TLS alternative](/enterprise/vm-install/generic-vm#dns-and-tls-setup) and select +path-based sandbox routing. + +## Azure Disk Latency Preflight + +The installer measures write latency at its etcd data directory. Nominal disk +capacity, a Premium SSD label, and provisioned IOPS do not prove that this check +will pass. In an evaluation of this example's 1,024 GiB P30 disk, the first +measurement was `10.027008 ms` P99 against the required `<10 ms`, and the installer +stopped before cluster deployment. A repeat with the disk unchanged measured +`9.633792 ms` and passed. Both measurements were close to the threshold; +validate your own host and plan performance headroom for production. + +If your disk fails this check, review the measured result, VM storage limits, +and disk performance tier with your Azure administrator. Azure supports +[increasing a Premium SSD performance tier](https://learn.microsoft.com/en-us/azure/virtual-machines/disks-performance-tiers) +without increasing disk capacity. Higher tiers change disk billing and still +require a passing latency preflight. Do not bypass the check or use the temporary +resource disk for persistent installation data. + +## 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 +- HTTPS egress to `api.anthropic.com` is available +- 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="azure.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/" + "https://api.anthropic.com" +) + +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. + + + **Provide your TLS certificates during installation.** For this Azure VM, + use the certificate paths prepared above: + + ```bash + sudo ./openhands install --license license.yaml \ + --tls-cert ~/tls/certificate.pem \ + --tls-key ~/tls/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) +- The URL printed by the installer (if you did not provide TLS files) + +If the installer uses a self-signed certificate, the browser displays a security +warning. Verify that you are connecting to the intended VM, then follow your +organization's policy for accessing the initial Admin Console. Upload a trusted +certificate before configuring external callbacks. + +![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 + + +Configure managed models in the Replicated Admin Console under `Config → LLM +Configuration`, then save and deploy the configuration. Select those models in +OpenHands. This Quick Start does not require signing into LiteLLM or calling its +API directly. If a configured model is missing, use +[Troubleshooting](/enterprise/troubleshooting) and contact OpenHands Support; +do not register it directly in LiteLLM to bypass the problem. + + +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 the initial installation, select `Anthropic (Claude)` and enter your key in +`Anthropic API Key`. If your release exposes `Anthropic Models`, enter model IDs +that your account can access, one per line. Confirm the model selected in +OpenHands can complete a request before changing providers. + +Permit HTTPS egress to `api.anthropic.com` in addition to the installer and +image endpoints listed above. Azure OpenAI resources and keys are not required +for this baseline. + +### 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 + +For a new base domain, create a dedicated GitHub App so existing installations +keep their webhook routing. A retired installation's app can be reused after +updating its homepage, OAuth callback, and webhook to the new domain and +verifying its repository scope and credentials. A GitHub App has one webhook +URL, so sharing it across simultaneous installations requires a separate routing +solution. + +For Simple mode, the callback is +`https://auth./realms/allhands/broker/github/endpoint` and the webhook +is `https://app./integration/github/events`. + +Run our [script](https://github.com/OpenHands/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) + +Start a new conversation without a repository. Ask it to run `pwd`, write +`OPENHANDS_INSTALL_PASS` to `/tmp/openhands-install-smoke.txt`, and read the file +back with `cat`. Expand the terminal tool result and verify the actual workspace +path and marker output, rather than relying only on the model's summary. The +Agent Canvas server status should show **Running**; API clients should verify +that the sandbox reaches `READY`. Then verify repository discovery and a +repository-backed conversation. + +Deployment readiness alone does not prove that inference and sandbox startup work. +If the first conversation fails, use [Troubleshooting](/enterprise/troubleshooting) +to collect evidence before adding optional integrations. + +![OpenHands is ready](/enterprise/images/openhands-ready.png) + +## Optional: Use Azure OpenAI Through the Bundled Gateway + + +Replicated Stable release `0.74.0` can remove configured Azure routes during +background model reconciliation. We reproduced an absent `azure-gpt-4.1-mini` +alias and HTTP 400 `Invalid model name` after a clean Azure VM install. + +The test package for [OpenHands-Cloud PR #1337](https://github.com/OpenHands/OpenHands-Cloud/pull/1337), +release `1749` / OpenHands `0.75.0`, fixes this by rendering the configured API +version directly into each route. On the same Azure installation, model +discovery persisted across background refreshes, and an Azure-backed conversation +and automation both completed real terminal commands successfully. + +This validation applies to that test package, not Stable `0.74.0`. Ask support +for a release containing the fix before using Azure inference. Do not register +models directly in LiteLLM to bypass Replicated configuration. Keep a working +provider available through the Admin Console while upgrading. + + +Complete the Anthropic login and first-conversation checks before switching +providers. Azure hosting and Azure inference are separate: an Azure VM can use +Anthropic, and OpenHands on another cloud can use Azure OpenAI. + +### 1. Prepare the Azure Model Deployment + +In the Azure portal or Azure AI Foundry portal: + +1. Create a dedicated **Azure OpenAI** resource in a region that supports your + chosen model, or obtain access to an existing resource from its owner. +2. Deploy a model that supports agent tool use. Record the **deployment name**, + which can differ from the model name. Confirm regional model quota and the + requested deployment's availability before creating it. +3. Record the resource endpoint, such as + `https://.openai.azure.com/`, and an API version supported by + the model and request API mode. Obtain a resource API key through your + approved secret channel. An OpenHands application API key is a different + credential and cannot authenticate Azure model inference. +4. Permit HTTPS egress from the VM to the resource endpoint. If it uses a private + endpoint, configure VNet connectivity and private DNS resolution from this + VM. Verify these before configuring OpenHands. + +For example, GPT-4.1-mini can use API version `2025-04-01-preview` for +Responses. Choose the API version for your actual deployment/API mode and +verify compatibility with your installed OpenHands release. + +### 2. Configure the Replicated Admin Console + +1. Open **Config → LLM Configuration** in the Admin Console. +2. Select `Azure` as the LLM provider. If `Azure Providers` is shown, select + `Azure OpenAI` for this example. +3. Select `API Key` under `Azure Authentication Method` and enter the resource + key in `Azure OpenAI API Key`. +4. Enter the resource endpoint in `Azure OpenAI Endpoint`. +5. Enter your supported API version in `Azure OpenAI API Version`. The displayed + `2024-10-21` default does not support the Responses example above. +6. If your release exposes `Azure OpenAI Deployments`, enter one deployment name + per line without an `azure/` prefix. Older releases may expose only a single + deployment-name field; follow the fields in your installed release. +7. Save the configuration and deploy the updated version. Wait for `Ready`. +8. In OpenHands, open `Settings → LLM` and add an LLM profile. Select `OpenHands` + as the provider to access this installation's administrator-managed models, + then select the configured Azure model and save the profile. You do not need + to enter the Azure resource key again in the user profile. +9. Select that profile for a new conversation and repeat the no-repository + terminal and file-readback check. + +If the Azure model is absent from the OpenHands selector, stop and collect +troubleshooting evidence for OpenHands Support. A model added directly to LiteLLM +and a successful direct gateway request do not validate the Replicated Azure +provider configuration. + +This selects Azure as the managed provider. Do not assume the dropdown preserves +Anthropic and Azure as simultaneous managed routes. If you need both, use the +[External LLM Gateways](/enterprise/integrations/external-llm-gateways) guide or +ask OpenHands Support for the supported configuration for your release. + +For Microsoft Entra authentication, select `Microsoft Entra ID — Service +Principal` and provide the tenant ID, client ID, and client secret. An authorized +Azure administrator must grant that principal `Cognitive Services OpenAI User` +on the Azure OpenAI resource. Subscription Contributor does not itself grant +inference permissions or permission to assign roles. + +The tested package also exposes `Azure AI Foundry` under `Azure Providers`. +Foundry endpoints use their own Admin Console fields and were not validated in +this evaluation. Follow the fields and supported endpoint format for your +installed release; do not substitute a Foundry endpoint into the Azure OpenAI +fields. See [Azure LLMs](/openhands/usage/llms/azure-llms) for the distinction +between Azure endpoint families. Configure managed models through the Admin +Console rather than copying Helm values or editing installer-managed Kubernetes +resources. + +## Operations and Cleanup + +- Back up the database and required persistent application data before upgrades + or removal. A single VM and bundled PostgreSQL do not provide high availability. +- Keep the static IP, DNS record, and certificate renewal process together. + Expired TLS can break login and external callbacks even while pods are healthy. +- Use the Admin Console for supported updates and deployment settings. If host + or first-conversation validation fails, collect a + [support bundle](/enterprise/troubleshooting) before changing workloads. +- Stopping the VM is not complete cleanup: managed disks and public IPs can + continue to incur charges. + +To remove a disposable evaluation, first inspect the dedicated resource group: + +```bash +az resource list --resource-group "$RG" \ + --query '[].{name:name,type:type}' --output table +``` + +After confirming that every resource belongs to this evaluation and saving any +required data, delete only that group: + +```bash +az group delete --name "$RG" +``` + +Delete the evaluation wildcard DNS record separately if its zone is outside the +group. Retain a reused GitHub App if it is needed for another installation; +otherwise remove its repository installation and app through GitHub settings. +An Azure OpenAI resource in a separate group requires separate cleanup. Preserve +shared DNS zones and model resources. + +## Validation Scope + +Validated on a dedicated Azure VM using `Standard_D16s_v3`, Ubuntu 24.04 LTS +and a 1,024 GiB Premium SSD OS disk. Host and application preflights passed +without overrides. Trusted HTTPS, GitHub login, persistent PostgreSQL storage, +an Anthropic-backed conversation and automation, and a read-only repository +conversation passed on the clean installation. + +After upgrading to the PR #1337 test package (release `1749`, OpenHands `0.75.0`, +Enterprise server `1.68.0`), the `gpt-4.1-mini` Azure OpenAI deployment with API +version `2025-04-01-preview` remained discoverable across background refreshes. +A conversation and a manually dispatched automation using +`openhands/azure-gpt-4.1-mini` both completed terminal commands with exit code 0. +All managed-provider configuration used the Replicated Admin Console; validation +used OpenHands surfaces. The automation schedule was disabled. + +Backup and restore, multiple nodes, automatic certificate renewal, Microsoft +Entra inference authentication and other Azure model families have not been +validated in this evaluation. Select a model available to your account for the +initial profile; an unavailable prior Claude model produced an initial error +before the explicitly selected Azure profile completed successfully. + +## 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/llms-full.txt b/llms-full.txt index e5697256d..176c127f9 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -56379,3 +56379,736 @@ Add machines with the `app` role to increase capacity for the OpenHands applicat - [Admin Console Configuration](/enterprise/vm-install/admin-console-configuration) - [Conversations and Sandboxes](/enterprise/conversations-and-sandboxes) + +### Azure Quick Start +Source: https://docs.openhands.dev/enterprise/vm-install/azure.md + +Install OpenHands Enterprise on a dedicated Azure VM using Replicated Embedded +Cluster. The installer manages Kubernetes on the VM. Start with an Anthropic API +key, then optionally configure Azure OpenAI through the bundled LLM gateway. + +For an AKS deployment, use [Install with Helm](/enterprise/k8s-install/installation). +AKS node pools, Helm values, and Kubernetes storage classes do not configure this +VM installation. + +## Prerequisites + +- [Register for an Enterprise trial](https://install.r9.all-hands.dev/openhands/signup), or use an existing licensed installer account. +- Azure CLI and an Azure subscription with permission to create a resource group, + VM, managed disk, virtual network, subnet, NIC, network security group, and public IP. +- Regional total-vCPU and VM-family quota for a VM with at least 16 vCPUs and 64 GB RAM. +- An SSH key pair and the public IPv4 CIDR of the administrator's workstation or VPN. +- A base domain you control and permission to change its DNS records. +- A publicly trusted wildcard certificate and its private key. +- An Anthropic API key and a GitHub account with permission to create/install a GitHub App. + +Subscription `Contributor` normally covers the infrastructure in this guide. +Azure RBAC assignments and model inference permissions are separate. If you +choose Microsoft Entra authentication for Azure OpenAI, have an authorized +administrator grant the required inference role. + +## Plan the Azure Resources + +| Resource | Purpose | +| --- | --- | +| Dedicated resource group | Scope the evaluation resources and cleanup | +| VNet and subnet | Private network for the VM and embedded cluster | +| Network security group | Permit HTTP/HTTPS and restrict SSH/Admin Console access | +| Standard static IPv4 public IP and NIC | Stable inbound address and explicit outbound connectivity | +| Ubuntu 24.04 LTS x86-64 VM | Run the Replicated installer and embedded Kubernetes cluster | +| Premium SSD managed OS disk | Persist embedded-cluster, database, and sandbox data | +| Wildcard DNS and TLS | Route and secure application services and dynamic sandbox hostnames | +| Optional Azure OpenAI resource and deployment | Provide inference through the bundled LLM gateway | + +The example uses `Standard_D16s_v3` (16 vCPUs, 64 GB RAM) and a 1,024 GiB +Premium SSD OS disk. The larger disk selects the P30 performance tier; it is not +a new capacity requirement. The trial baseline is 200 GB and P99 write latency +below 10 ms. A disk's provisioned IOPS do not guarantee that latency: run the +installer's host preflights. See [Premium storage performance](https://learn.microsoft.com/en-us/azure/virtual-machines/premium-storage-performance) +and the [Sizing Guide](/enterprise/sizing-guide) for larger deployments. + +Use persistent managed storage for installation data. Azure temporary/resource +disks can be lost during host maintenance or redeployment. This example keeps +installation data on the managed OS disk rather than adding a temporary disk. + +## Provision Infrastructure + +Run these commands from your administrator workstation using Bash. + +### 1. Select the Subscription and Check Capacity + +```bash +az login +export SUBSCRIPTION_ID="" +export LOCATION="eastus2" +export RG="openhands-replicated-eval-rg" +export VM="openhands-replicated-eval" +export VM_SIZE="Standard_D16s_v3" +export ADMIN_CIDR="/32" +export SSH_PUBLIC_KEY_FILE="$HOME/.ssh/openhands-azure.pub" +export BASE_DOMAIN="azure.openhands.example.com" + +az account set --subscription "$SUBSCRIPTION_ID" +az account show --query '{name:name,id:id,tenant:tenantId}' --output table +az vm list-usage --location "$LOCATION" --output table +az vm list-skus --location "$LOCATION" --size "$VM_SIZE" --all \ + --query '[?resourceType==`virtualMachines`].{name:name,restrictions:restrictions}' \ + --output json +az vm image show --location "$LOCATION" \ + --urn Canonical:ubuntu-24_04-lts:server:latest --output table +``` + +Verify available total and VM-family vCPU quota and SKU restrictions before +creating resources. A VM family can have zero quota even when total regional +quota is available. Request a quota increase or choose another supported +x86-64 size with at least 16 vCPUs and 64 GB RAM. Avoid a zonal deployment if +that zone is restricted for your subscription. + +Ensure `Microsoft.Compute`, `Microsoft.Network`, and `Microsoft.Storage` are +registered under **Subscriptions → Resource providers**. Registration may need +a subscription administrator. This deployment does not require AKS or the +`Microsoft.ContainerService` provider. + +Use an existing SSH public key, or generate a dedicated key pair without +replacing an existing file: + +```bash +ssh-keygen -t ed25519 -f "$HOME/.ssh/openhands-azure" -C openhands-azure +``` + +### 2. Create Networking and Ingress Rules + +Use a new, dedicated resource group. Check that its name is unused before +proceeding; do not place evaluation resources in a shared production group. + +```bash +az group exists --name "$RG" +az group create --name "$RG" --location "$LOCATION" + +az network vnet create --resource-group "$RG" --name "$VM-vnet" \ + --address-prefixes 10.82.0.0/16 \ + --subnet-name openhands --subnet-prefixes 10.82.1.0/24 +az network nsg create --resource-group "$RG" --name "$VM-nsg" + +az network nsg rule create --resource-group "$RG" --nsg-name "$VM-nsg" \ + --name admin --priority 100 --source-address-prefixes "$ADMIN_CIDR" \ + --destination-port-ranges 22 30000 --protocol Tcp --access Allow +az network nsg rule create --resource-group "$RG" --nsg-name "$VM-nsg" \ + --name web --priority 110 --source-address-prefixes Internet \ + --destination-port-ranges 80 443 --protocol Tcp --access Allow + +az network public-ip create --resource-group "$RG" --name "$VM-ip" \ + --sku Standard --allocation-method Static --version IPv4 +az network nic create --resource-group "$RG" --name "$VM-nic" \ + --vnet-name "$VM-vnet" --subnet openhands \ + --network-security-group "$VM-nsg" --public-ip-address "$VM-ip" +``` + +Choose non-overlapping VNet/subnet address ranges for your environment. The +example exposes ports 80/443 so GitHub callbacks and users can reach OpenHands. +Ports 22/30000 are restricted to your administrator CIDR. Corporate firewalls, +subnet NSGs, and host firewall rules must also permit the required traffic. +Do not expose Kubernetes or etcd ports publicly. + +The NIC's public IP provides explicit VM outbound connectivity. If you use a +private VM instead, provide a NAT gateway or your organization's approved egress +path and a supported ingress path with DNS/TLS and integration reachability. + +### 3. Create the VM and Persistent Disk + +```bash +az vm create --resource-group "$RG" --name "$VM" \ + --nics "$VM-nic" \ + --image Canonical:ubuntu-24_04-lts:server:latest \ + --size "$VM_SIZE" --admin-username azureuser \ + --authentication-type ssh --ssh-key-values "$SSH_PUBLIC_KEY_FILE" \ + --storage-sku Premium_LRS --os-disk-size-gb 1024 \ + --os-disk-name "$VM-os" + +export VM_IP=$(az network public-ip show --resource-group "$RG" \ + --name "$VM-ip" --query ipAddress --output tsv) +ssh -i "$HOME/.ssh/openhands-azure" "azureuser@$VM_IP" +``` + +Local embedded-cluster ports must be available: `2379`, `7443`, `9099`, +`10248`, `10257`, and `10259` (TCP). These do not need public NSG rules. + +On the VM, verify the OS, kernel, memory, disk space, and sudo access: + +```bash +cat /etc/os-release +uname -m +uname -r +nproc +free -h +lsblk +findmnt /var/lib +sudo -v +``` + +Use Ubuntu 24.04 LTS and check the actual kernel against the +[Sysbox requirements](/enterprise/docker-in-sandbox). Do not infer compatibility +from the Azure image name alone. The Replicated host preflight must pass before +installation; do not bypass a failed storage or runtime check. + +### 4. Configure DNS + +Create a wildcard A record for `*.` pointing to the static `VM_IP`. +You can keep DNS with your existing provider; Azure hosting does not require +Azure DNS. + +If your authoritative zone is already hosted in Azure DNS, run from your +workstation using the existing zone's resource group: + +```bash +export DNS_RG="" +export DNS_ZONE="example.com" +# Relative name for *.azure.openhands.example.com in example.com: +export DNS_RECORD="*.azure.openhands" +az network dns record-set a add-record --resource-group "$DNS_RG" \ + --zone-name "$DNS_ZONE" --record-set-name "$DNS_RECORD" \ + --ipv4-address "$VM_IP" +``` + +Do not append an IP to an existing record set that serves another deployment. +If you create a new Azure DNS zone, delegate it at its parent or registrar to +its assigned name servers before expecting public resolution. DNS zone access +may require a separate role or DNS administrator. + +### 5. Obtain and Copy TLS Files + +Obtain a publicly trusted wildcard certificate for `*.`. For +Let's Encrypt, use a DNS-01 challenge with your authoritative DNS provider. +HTTP-01 cannot issue a wildcard certificate. Keep provider credentials and +private keys out of repositories and command output. + +If you do not already have a certificate, install Certbot using its +[official instructions](https://certbot.eff.org/instructions). For an evaluation, +run a manual DNS-01 challenge on your administrator workstation: + +```bash +sudo certbot certonly --manual --preferred-challenges dns \ + --cert-name openhands-azure -d "*.${BASE_DOMAIN}" +``` + +Enter your ACME contact email and review the certificate authority's terms when +prompted. Certbot displays a TXT value to publish at +`_acme-challenge.`. Create it with the authoritative DNS provider, +wait for public resolution, and then continue the challenge. For Azure DNS, +the TXT record's relative name for this example is +`_acme-challenge.azure.openhands` in the `example.com` zone. + +```bash +dig +short TXT "_acme-challenge.${BASE_DOMAIN}" +``` + +After issuance, Certbot saves the full chain and private key under +`/etc/letsencrypt/live/openhands-azure/`. Transfer those files through your +approved private channel, or substitute existing certificate files below. See +[Certbot's manual challenge guide](https://eff-certbot.readthedocs.io/en/stable/using.html#manual). +Manual challenges need to be repeated for renewal unless you configure an +authentication hook; choose a DNS plugin for unattended certificate issuance. + +Copy the full certificate chain and private key to a private directory on the +VM using your existing certificate files: + +```bash +ssh -i "$HOME/.ssh/openhands-azure" "azureuser@$VM_IP" \ + 'mkdir -p ~/tls && chmod 700 ~/tls' +scp -i "$HOME/.ssh/openhands-azure" /path/to/fullchain.pem \ + "azureuser@$VM_IP:tls/certificate.pem" +scp -i "$HOME/.ssh/openhands-azure" /path/to/privkey.pem \ + "azureuser@$VM_IP:tls/private-key.pem" +ssh -i "$HOME/.ssh/openhands-azure" "azureuser@$VM_IP" \ + 'chmod 600 ~/tls/*.pem' +``` + +Plan certificate renewal and upload the renewed certificate through the supported +Admin Console workflow. Initial issuance does not configure automatic renewal. + +For a Simple-mode install, one wildcard covers `admin`, `app`, `auth`, +`analytics`, `llm-proxy`, `runtime-api`, and dynamic `-runtime` hostnames under +the base domain. If wildcard certificates are unavailable, follow the +[VM DNS/TLS alternative](/enterprise/vm-install/generic-vm#dns-and-tls-setup) and select +path-based sandbox routing. + +## Azure Disk Latency Preflight + +The installer measures write latency at its etcd data directory. Nominal disk +capacity, a Premium SSD label, and provisioned IOPS do not prove that this check +will pass. In an evaluation of this example's 1,024 GiB P30 disk, the first +measurement was `10.027008 ms` P99 against the required `<10 ms`, and the installer +stopped before cluster deployment. A repeat with the disk unchanged measured +`9.633792 ms` and passed. Both measurements were close to the threshold; +validate your own host and plan performance headroom for production. + +If your disk fails this check, review the measured result, VM storage limits, +and disk performance tier with your Azure administrator. Azure supports +[increasing a Premium SSD performance tier](https://learn.microsoft.com/en-us/azure/virtual-machines/disks-performance-tiers) +without increasing disk capacity. Higher tiers change disk billing and still +require a passing latency preflight. Do not bypass the check or use the temporary +resource disk for persistent installation data. + +## 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 +- HTTPS egress to `api.anthropic.com` is available +- 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="azure.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/" + "https://api.anthropic.com" +) + +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. + + + **Provide your TLS certificates during installation.** For this Azure VM, + use the certificate paths prepared above: + + ```bash + sudo ./openhands install --license license.yaml \ + --tls-cert ~/tls/certificate.pem \ + --tls-key ~/tls/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) +- The URL printed by the installer (if you did not provide TLS files) + +If the installer uses a self-signed certificate, the browser displays a security +warning. Verify that you are connecting to the intended VM, then follow your +organization's policy for accessing the initial Admin Console. Upload a trusted +certificate before configuring external callbacks. + +![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 + + +Configure managed models in the Replicated Admin Console under `Config → LLM +Configuration`, then save and deploy the configuration. Select those models in +OpenHands. This Quick Start does not require signing into LiteLLM or calling its +API directly. If a configured model is missing, use +[Troubleshooting](/enterprise/troubleshooting) and contact OpenHands Support; +do not register it directly in LiteLLM to bypass the problem. + + +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 the initial installation, select `Anthropic (Claude)` and enter your key in +`Anthropic API Key`. If your release exposes `Anthropic Models`, enter model IDs +that your account can access, one per line. Confirm the model selected in +OpenHands can complete a request before changing providers. + +Permit HTTPS egress to `api.anthropic.com` in addition to the installer and +image endpoints listed above. Azure OpenAI resources and keys are not required +for this baseline. + +### 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 + +For a new base domain, create a dedicated GitHub App so existing installations +keep their webhook routing. A retired installation's app can be reused after +updating its homepage, OAuth callback, and webhook to the new domain and +verifying its repository scope and credentials. A GitHub App has one webhook +URL, so sharing it across simultaneous installations requires a separate routing +solution. + +For Simple mode, the callback is +`https://auth./realms/allhands/broker/github/endpoint` and the webhook +is `https://app./integration/github/events`. + +Run our [script](https://github.com/OpenHands/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) + +Start a new conversation without a repository. Ask it to run `pwd`, write +`OPENHANDS_INSTALL_PASS` to `/tmp/openhands-install-smoke.txt`, and read the file +back with `cat`. Expand the terminal tool result and verify the actual workspace +path and marker output, rather than relying only on the model's summary. The +Agent Canvas server status should show **Running**; API clients should verify +that the sandbox reaches `READY`. Then verify repository discovery and a +repository-backed conversation. + +Deployment readiness alone does not prove that inference and sandbox startup work. +If the first conversation fails, use [Troubleshooting](/enterprise/troubleshooting) +to collect evidence before adding optional integrations. + +![OpenHands is ready](/enterprise/images/openhands-ready.png) + +## Optional: Use Azure OpenAI Through the Bundled Gateway + + +Replicated Stable release `0.74.0` can remove configured Azure routes during +background model reconciliation. We reproduced an absent `azure-gpt-4.1-mini` +alias and HTTP 400 `Invalid model name` after a clean Azure VM install. + +The test package for [OpenHands-Cloud PR #1337](https://github.com/OpenHands/OpenHands-Cloud/pull/1337), +release `1749` / OpenHands `0.75.0`, fixes this by rendering the configured API +version directly into each route. On the same Azure installation, model +discovery persisted across background refreshes, and an Azure-backed conversation +and automation both completed real terminal commands successfully. + +This validation applies to that test package, not Stable `0.74.0`. Ask support +for a release containing the fix before using Azure inference. Do not register +models directly in LiteLLM to bypass Replicated configuration. Keep a working +provider available through the Admin Console while upgrading. + + +Complete the Anthropic login and first-conversation checks before switching +providers. Azure hosting and Azure inference are separate: an Azure VM can use +Anthropic, and OpenHands on another cloud can use Azure OpenAI. + +### 1. Prepare the Azure Model Deployment + +In the Azure portal or Azure AI Foundry portal: + +1. Create a dedicated **Azure OpenAI** resource in a region that supports your + chosen model, or obtain access to an existing resource from its owner. +2. Deploy a model that supports agent tool use. Record the **deployment name**, + which can differ from the model name. Confirm regional model quota and the + requested deployment's availability before creating it. +3. Record the resource endpoint, such as + `https://.openai.azure.com/`, and an API version supported by + the model and request API mode. Obtain a resource API key through your + approved secret channel. An OpenHands application API key is a different + credential and cannot authenticate Azure model inference. +4. Permit HTTPS egress from the VM to the resource endpoint. If it uses a private + endpoint, configure VNet connectivity and private DNS resolution from this + VM. Verify these before configuring OpenHands. + +For example, GPT-4.1-mini can use API version `2025-04-01-preview` for +Responses. Choose the API version for your actual deployment/API mode and +verify compatibility with your installed OpenHands release. + +### 2. Configure the Replicated Admin Console + +1. Open **Config → LLM Configuration** in the Admin Console. +2. Select `Azure` as the LLM provider. If `Azure Providers` is shown, select + `Azure OpenAI` for this example. +3. Select `API Key` under `Azure Authentication Method` and enter the resource + key in `Azure OpenAI API Key`. +4. Enter the resource endpoint in `Azure OpenAI Endpoint`. +5. Enter your supported API version in `Azure OpenAI API Version`. The displayed + `2024-10-21` default does not support the Responses example above. +6. If your release exposes `Azure OpenAI Deployments`, enter one deployment name + per line without an `azure/` prefix. Older releases may expose only a single + deployment-name field; follow the fields in your installed release. +7. Save the configuration and deploy the updated version. Wait for `Ready`. +8. In OpenHands, open `Settings → LLM` and add an LLM profile. Select `OpenHands` + as the provider to access this installation's administrator-managed models, + then select the configured Azure model and save the profile. You do not need + to enter the Azure resource key again in the user profile. +9. Select that profile for a new conversation and repeat the no-repository + terminal and file-readback check. + +If the Azure model is absent from the OpenHands selector, stop and collect +troubleshooting evidence for OpenHands Support. A model added directly to LiteLLM +and a successful direct gateway request do not validate the Replicated Azure +provider configuration. + +This selects Azure as the managed provider. Do not assume the dropdown preserves +Anthropic and Azure as simultaneous managed routes. If you need both, use the +[External LLM Gateways](/enterprise/integrations/external-llm-gateways) guide or +ask OpenHands Support for the supported configuration for your release. + +For Microsoft Entra authentication, select `Microsoft Entra ID — Service +Principal` and provide the tenant ID, client ID, and client secret. An authorized +Azure administrator must grant that principal `Cognitive Services OpenAI User` +on the Azure OpenAI resource. Subscription Contributor does not itself grant +inference permissions or permission to assign roles. + +The tested package also exposes `Azure AI Foundry` under `Azure Providers`. +Foundry endpoints use their own Admin Console fields and were not validated in +this evaluation. Follow the fields and supported endpoint format for your +installed release; do not substitute a Foundry endpoint into the Azure OpenAI +fields. See [Azure LLMs](/openhands/usage/llms/azure-llms) for the distinction +between Azure endpoint families. Configure managed models through the Admin +Console rather than copying Helm values or editing installer-managed Kubernetes +resources. + +## Operations and Cleanup + +- Back up the database and required persistent application data before upgrades + or removal. A single VM and bundled PostgreSQL do not provide high availability. +- Keep the static IP, DNS record, and certificate renewal process together. + Expired TLS can break login and external callbacks even while pods are healthy. +- Use the Admin Console for supported updates and deployment settings. If host + or first-conversation validation fails, collect a + [support bundle](/enterprise/troubleshooting) before changing workloads. +- Stopping the VM is not complete cleanup: managed disks and public IPs can + continue to incur charges. + +To remove a disposable evaluation, first inspect the dedicated resource group: + +```bash +az resource list --resource-group "$RG" \ + --query '[].{name:name,type:type}' --output table +``` + +After confirming that every resource belongs to this evaluation and saving any +required data, delete only that group: + +```bash +az group delete --name "$RG" +``` + +Delete the evaluation wildcard DNS record separately if its zone is outside the +group. Retain a reused GitHub App if it is needed for another installation; +otherwise remove its repository installation and app through GitHub settings. +An Azure OpenAI resource in a separate group requires separate cleanup. Preserve +shared DNS zones and model resources. + +## Validation Scope + +Validated on a dedicated Azure VM using `Standard_D16s_v3`, Ubuntu 24.04 LTS +and a 1,024 GiB Premium SSD OS disk. Host and application preflights passed +without overrides. Trusted HTTPS, GitHub login, persistent PostgreSQL storage, +an Anthropic-backed conversation and automation, and a read-only repository +conversation passed on the clean installation. + +After upgrading to the PR #1337 test package (release `1749`, OpenHands `0.75.0`, +Enterprise server `1.68.0`), the `gpt-4.1-mini` Azure OpenAI deployment with API +version `2025-04-01-preview` remained discoverable across background refreshes. +A conversation and a manually dispatched automation using +`openhands/azure-gpt-4.1-mini` both completed terminal commands with exit code 0. +All managed-provider configuration used the Replicated Admin Console; validation +used OpenHands surfaces. The automation schedule was disabled. + +Backup and restore, multiple nodes, automatic certificate renewal, Microsoft +Entra inference authentication and other Azure model families have not been +validated in this evaluation. Select a model available to your account for the +initial profile; an unavailable prior Claude model produced an initial error +before the explicitly selected Azure profile completed successfully. + +## 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/llms.txt b/llms.txt index 638b3c95d..75ab0e985 100644 --- a/llms.txt +++ b/llms.txt @@ -280,6 +280,7 @@ from the OpenHands Software Agent SDK. - [OpenHands Enterprise](https://docs.openhands.dev/enterprise.md): Run AI coding agents on your own infrastructure with complete control - [Plugin Marketplace](https://docs.openhands.dev/enterprise/plugin-marketplace.md): Enable and configure the Plugin Marketplace to browse and install community-built OpenHands plugins. - [Quick Start](https://docs.openhands.dev/enterprise/quick-start.md): Get started with a 30-day trial of OpenHands Enterprise. +- [Azure Quick Start](https://docs.openhands.dev/enterprise/vm-install/azure.md): Provision an Azure Linux VM and install OpenHands Enterprise with Replicated, starting with Anthropic inference. - [Release Notes](https://docs.openhands.dev/enterprise/release-notes.md): Release notes for OpenHands Enterprise - [Resource Limits](https://docs.openhands.dev/enterprise/k8s-install/resource-limits.md): Configure memory, CPU, and storage for OpenHands Enterprise components - [Running Docker in the Agent Sandbox](https://docs.openhands.dev/enterprise/docker-in-sandbox.md): Let agents run containers, Docker Compose, and image builds inside their isolated sandbox—safely, without privileged access to your cluster. From 3c189ba8e92912be54a3e65593fb852f9a948a10 Mon Sep 17 00:00:00 2001 From: Rajiv Shah Date: Sun, 4 Oct 2026 17:39:44 -0500 Subject: [PATCH 4/7] Correct quick-start sizing references and direct installation links --- enterprise/k8s-install/installation.mdx | 4 ++-- enterprise/sizing-guide.mdx | 2 +- enterprise/vm-install/aws.mdx | 7 +++---- enterprise/vm-install/generic-vm.mdx | 4 ++-- 4 files changed, 8 insertions(+), 9 deletions(-) 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/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 index 2444659f9..71dbcdf2f 100644 --- a/enterprise/vm-install/aws.mdx +++ b/enterprise/vm-install/aws.mdx @@ -1,7 +1,7 @@ --- title: AWS Quick Start -description: Get started with a 30-day trial of OpenHands Enterprise. -icon: rocket +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. @@ -37,7 +37,7 @@ 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. + 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 @@ -178,7 +178,6 @@ bundle and open a support ticket. --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. diff --git a/enterprise/vm-install/generic-vm.mdx b/enterprise/vm-install/generic-vm.mdx index 7e06a4404..5f00b1a99 100644 --- a/enterprise/vm-install/generic-vm.mdx +++ b/enterprise/vm-install/generic-vm.mdx @@ -1,7 +1,7 @@ --- title: Generic VM Quick Start -description: Get started with a 30-day trial of OpenHands Enterprise. -icon: rocket +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. From 7d91605c7b3d15824884b5d4c27f23ec90a22e3f Mon Sep 17 00:00:00 2001 From: Rajiv Shah Date: Sun, 4 Oct 2026 17:43:52 -0500 Subject: [PATCH 5/7] Link directly to the Replicated installation skill --- enterprise/vm-install/google.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/enterprise/vm-install/google.mdx b/enterprise/vm-install/google.mdx index ceb75cc43..cffb119b0 100644 --- a/enterprise/vm-install/google.mdx +++ b/enterprise/vm-install/google.mdx @@ -319,11 +319,10 @@ terminal tools and repository access work together. ## Agent-Assisted Installation -The [Replicated installation skill proposal](https://github.com/OpenHands/extensions/pull/458) +The [Replicated installation skill](https://github.com/OpenHands/extensions/blob/e945ed649aa78500c393bccee4390e72e6add991/skills/install-openhands-replicated/SKILL.md) provides an agent workflow for resource planning, preflights, installation and -end-to-end checks. Its publication to the main skill registry is pending. Use -these public instructions as the installation reference and review the proposed -skill before using it with cloud credentials. +end-to-end checks. Use this guide and the Replicated Admin Console as the +reference for release-specific requirements and configuration fields. ## Validation Scope From d0bcd90e30f2ae79a202fb2dbd720e9222483eb8 Mon Sep 17 00:00:00 2001 From: Rajiv Shah Date: Mon, 5 Oct 2026 15:42:55 -0500 Subject: [PATCH 6/7] Clarify validated Azure VM path after independent review --- enterprise/quick-start.mdx | 2 +- enterprise/vm-install/azure.mdx | 36 +++++++++++++++++++++++---------- 2 files changed, 26 insertions(+), 12 deletions(-) diff --git a/enterprise/quick-start.mdx b/enterprise/quick-start.mdx index c08035cc7..159fdcdfc 100644 --- a/enterprise/quick-start.mdx +++ b/enterprise/quick-start.mdx @@ -15,7 +15,7 @@ Choose the guide for your infrastructure: Provision a Compute Engine VM and configure administrator-managed Vertex AI models. - Provision an Azure VM, start with Anthropic and optionally configure administrator-managed Azure OpenAI models. + Provision an Azure VM and install OpenHands Enterprise with Anthropic inference. Prepare a Linux VM on-premises or on another cloud provider, then install and configure OpenHands. diff --git a/enterprise/vm-install/azure.mdx b/enterprise/vm-install/azure.mdx index e048cacf1..afcfff6de 100644 --- a/enterprise/vm-install/azure.mdx +++ b/enterprise/vm-install/azure.mdx @@ -25,7 +25,6 @@ VM installation. - An Anthropic API key and a GitHub account with permission to create/install a GitHub App. Subscription `Contributor` normally covers the infrastructure in this guide. -Azure RBAC assignments may require an authorized subscription administrator. ## Plan the Azure Resources @@ -49,6 +48,9 @@ and the [Sizing Guide](/enterprise/sizing-guide) for larger deployments. Use persistent managed storage for installation data. Azure temporary/resource disks can be lost during host maintenance or redeployment. This example keeps installation data on the managed OS disk rather than adding a temporary disk. +This single-disk layout was used for the validation below. For a deployment that +needs to grow, follow the [Sizing Guide](/enterprise/sizing-guide) recommendation +to use a separate expandable data volume. ## Provision Infrastructure @@ -206,7 +208,12 @@ If you do not already have a certificate, install Certbot using its run a manual DNS-01 challenge on your administrator workstation: ```bash -sudo certbot certonly --manual --preferred-challenges dns \ +umask 077 +mkdir -p "$HOME/letsencrypt" +certbot certonly --manual --preferred-challenges dns \ + --config-dir "$HOME/letsencrypt" \ + --work-dir "$HOME/letsencrypt/work" \ + --logs-dir "$HOME/letsencrypt/logs" \ --cert-name openhands-azure -d "*.${BASE_DOMAIN}" ``` @@ -222,7 +229,8 @@ dig +short TXT "_acme-challenge.${BASE_DOMAIN}" ``` After issuance, Certbot saves the full chain and private key under -`/etc/letsencrypt/live/openhands-azure/`. Transfer those files through your +`$HOME/letsencrypt/live/openhands-azure/`, owned by the user who ran Certbot. +Transfer those files through your approved private channel, or substitute existing certificate files below. See [Certbot's manual challenge guide](https://eff-certbot.readthedocs.io/en/stable/using.html#manual). Manual challenges need to be repeated for renewal unless you configure an @@ -352,6 +360,7 @@ If any check fails, stop and resolve before continuing: | `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 | +| `api.anthropic.com` | Anthropic inference for the initial model configuration | ## Run the Installer @@ -374,7 +383,10 @@ Select **"Outbound requests allowed"** for Network Availability, then click **Co 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 +1. **Select a version** -- select `0.74.0` to reproduce the validated installation + below. The dashboard pre-selects the latest release; later releases were not + tested for this guide. If `0.74.0` is unavailable, ask OpenHands Support for a + supported release and repeat the preflight and first-conversation checks. 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 @@ -449,7 +461,7 @@ You should now see the application configuration page. ### Domain Configuration - Keep the Hostname Configuration Mode set to **"Simple (default)"** -- Enter your base domain (e.g., `openhands.example.com`) +- Enter your base domain (e.g., `azure.openhands.example.com`) ### Certificate Configuration @@ -474,7 +486,7 @@ from that provider. ![LLM Configuration provider dropdown](/enterprise/images/llm-configuration-provider-dropdown.png) For the initial installation, select `Anthropic (Claude)` and enter your key in -`Anthropic API Key`. If your release exposes `Anthropic Models`, enter model IDs +`Anthropic API Key`. Keep or replace the default `Anthropic Models` entries with model IDs that your account can access, one per line. Confirm the model selected in OpenHands can complete a request before changing providers. @@ -560,8 +572,7 @@ Start a new conversation without a repository. Ask it to run `pwd`, write `OPENHANDS_INSTALL_PASS` to `/tmp/openhands-install-smoke.txt`, and read the file back with `cat`. Expand the terminal tool result and verify the actual workspace path and marker output, rather than relying only on the model's summary. The -Agent Canvas server status should show **Running**; API clients should verify -that the sandbox reaches `READY`. Then verify repository discovery and a +Agent Canvas server status should show **Running**. Then verify repository discovery and a repository-backed conversation. Deployment readiness alone does not prove that inference and sandbox startup work. @@ -573,8 +584,10 @@ to collect evidence before adding optional integrations. Azure hosting and Azure model inference are separate. The Azure VM installation and Anthropic workflow in this guide were validated on Replicated `0.74.0`. -Azure OpenAI gateway setup is deferred until a release contains the required -provider fix and that released package has been validated. +Keep **Anthropic (Claude)** selected for this installation. Do not select +**Azure** in **LLM Configuration** for this validated path. Azure OpenAI gateway +setup is deferred until a release contains the required provider fix and that +released package has been validated. ## Operations and Cleanup @@ -613,7 +626,8 @@ Preserve shared DNS zones and resources outside the dedicated installation group Validated with Replicated `0.74.0` on a dedicated Azure VM using `Standard_D16s_v3`, Ubuntu 24.04 LTS and a 1,024 GiB Premium SSD OS disk: -host and application preflights without overrides, trusted HTTPS, GitHub login, +host preflight passed on rerun without overrides, application preflights passed, +trusted HTTPS, GitHub login, persistent PostgreSQL storage, an Anthropic-backed conversation and a manually dispatched automation, and a read-only repository conversation. The automation schedule was disabled after testing. From bebcb34f5385fd19d3015143d5bbe886d02acbb5 Mon Sep 17 00:00:00 2001 From: Rajiv Shah Date: Fri, 16 Oct 2026 12:51:12 -0500 Subject: [PATCH 7/7] docs: group Enterprise quick starts under VM Install --- docs.json | 11 ++- enterprise/quick-start.mdx | 145 ------------------------------------- 2 files changed, 7 insertions(+), 149 deletions(-) delete mode 100644 enterprise/quick-start.mdx diff --git a/docs.json b/docs.json index 02ccca309..932d529c0 100644 --- a/docs.json +++ b/docs.json @@ -541,10 +541,6 @@ "enterprise/enterprise-vs-oss", "enterprise/architecture", "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", @@ -629,6 +625,9 @@ { "group": "VM Install", "pages": [ + "enterprise/vm-install/generic-vm", + "enterprise/vm-install/aws", + "enterprise/vm-install/google", "enterprise/vm-install/admin-console-configuration", "enterprise/vm-install/log-collection", "enterprise/vm-install/scaling" @@ -805,6 +804,10 @@ ] }, "redirects": [ + { + "source": "/enterprise/quick-start", + "destination": "/enterprise/vm-install/generic-vm" + }, { "source": "/openhands/usage/agent-canvas/self-hosting", "destination": "/openhands/usage/agent-canvas/backend-setup/vm" diff --git a/enterprise/quick-start.mdx b/enterprise/quick-start.mdx deleted file mode 100644 index 737e84d54..000000000 --- a/enterprise/quick-start.mdx +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: Quick Start -description: Choose an installation guide for OpenHands Enterprise on your infrastructure. -icon: rocket ---- - -Install OpenHands Enterprise with Replicated Embedded Cluster on a dedicated VM. -Choose the guide for your infrastructure: - - - - 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. - - - -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). - -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. - -## Existing Quick Start Links - -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. - - - -[Who This Is For](/enterprise/vm-install/generic-vm#who-this-is-for) - - - -[Accounts and Credentials](/enterprise/vm-install/generic-vm#accounts-and-credentials) - - - -[Provision Infrastructure](/enterprise/vm-install/generic-vm#provision-infrastructure) - - - -[Preflight Validation](/enterprise/vm-install/generic-vm#preflight-validation) - - - -[DNS checks](/enterprise/vm-install/generic-vm#dns-checks) - - - -[Outbound connectivity checks](/enterprise/vm-install/generic-vm#outbound-connectivity-checks) - - - -[Reasons for Requirements](/enterprise/vm-install/generic-vm#reasons-for-requirements) - - - -[Run the Installer](/enterprise/vm-install/generic-vm#run-the-installer) - - - -[1. Access the Installer Dashboard](/enterprise/vm-install/generic-vm#1-access-the-installer-dashboard) - - - -[2. Name your instance](/enterprise/vm-install/generic-vm#2-name-your-instance) - - - -[3. Run the installation commands](/enterprise/vm-install/generic-vm#3-run-the-installation-commands) - - - -[4. Access the Admin Console](/enterprise/vm-install/generic-vm#4-access-the-admin-console) - - - -[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) - - - -[6. Log in to the Admin Console](/enterprise/vm-install/generic-vm#6-log-in-to-the-admin-console) - - - -[7. Configure the cluster](/enterprise/vm-install/generic-vm#7-configure-the-cluster) - - - -[Configure OpenHands](/enterprise/vm-install/generic-vm#configure-openhands) - - - -[Domain Configuration](/enterprise/vm-install/generic-vm#domain-configuration) - - - -[Certificate Configuration](/enterprise/vm-install/generic-vm#certificate-configuration) - - - -[LLM Configuration](/enterprise/vm-install/generic-vm#llm-configuration) - - - -[Database Configuration](/enterprise/vm-install/generic-vm#database-configuration) - - - -[GitHub Authentication](/enterprise/vm-install/generic-vm#github-authentication) - - - -[Create a GitHub App](/enterprise/vm-install/generic-vm#create-a-github-app) - - - -[Map GitHub App values to Admin Console](/enterprise/vm-install/generic-vm#map-github-app-values-to-admin-console) - - - -[Additional Integrations](/enterprise/vm-install/generic-vm#additional-integrations) - - - -[Deploy and Verify](/enterprise/vm-install/generic-vm#deploy-and-verify) - - - -[First Login](/enterprise/vm-install/generic-vm#first-login) - - - -[Next Steps](/enterprise/vm-install/generic-vm#next-steps) - - - -[DNS and TLS Setup](/enterprise/vm-install/generic-vm#dns-and-tls-setup)