Quick Start

Get started with a 30-day trial of OpenHands Enterprise.

This guide walks you through trialing OpenHands Enterprise on your own infrastructure. You’ll provision infrastructure (AWS Terraform or a manual VM setup), configure GitHub for user authentication, and set up Anthropic as your LLM provider.

Who This Is For

This guide is not for single-user local laptop installs. It is for a 30-day trial of OpenHands Enterprise on a dedicated VM/server on your own infrastructure. The deployment requires DNS records, network, and compute setup before installation.

If you want to use OpenHands immediately without infrastructure setup:

• Use OpenHands Cloud (SaaS)
• Run OpenHands open-source locally using Docker, CLI or SDK

Accounts and Credentials

Before you begin, make sure you have the following ready:

• Anthropic API key from the Anthropic Console
• 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.

AWS with Terraform (Recommended)

We provide a Terraform module that provisions a properly configured environment for OpenHands Enterprise, including the EC2 instance, DNS records, and TLS certificates.

OpenHands AWS Terraform Module

Follow the README instructions to configure and apply the Terraform configuration.

Manual VM Setup

If you are provisioning a VM manually (on-premises or on another cloud provider), it must meet the requirements below.

System requirements

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

Network requirements

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

System directories created by the installer

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 DNS A records pointing to your VM’s public IP address:

Record	Example
<your-domain>	openhands.example.com
app.<your-domain>	app.openhands.example.com
auth.app.<your-domain>	auth.app.openhands.example.com
llm-proxy.<your-domain>	llm-proxy.openhands.example.com
runtime-api.<your-domain>	runtime-api.openhands.example.com
*.runtime.<your-domain>	*.runtime.openhands.example.com

Obtain a TLS certificate with SANs (Subject Alternative Names) for all of the above domains, then copy the certificate (.pem or .crt) and private key (.pem or .key) to the VM.

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

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:

export BASE_DOMAIN="openhands.example.com"

Test DNS:

for h in \
  "${BASE_DOMAIN}" \
  "app.${BASE_DOMAIN}" \
  "auth.app.${BASE_DOMAIN}" \
  "llm-proxy.${BASE_DOMAIN}" \
  "runtime-api.${BASE_DOMAIN}"; do
  echo "[DNS] $h"
  getent hosts "$h" || nslookup "$h"
done

Expected: each hostname above resolves to your VM’s public IP address.

Test that a runtime wildcard hostname resolves:

getent hosts "test.runtime.${BASE_DOMAIN}" || nslookup "test.runtime.${BASE_DOMAIN}"

Expected: test.runtime.${BASE_DOMAIN} resolves to the same target as ${BASE_DOMAIN}.

Outbound connectivity checks

urls=(
  "https://replicated.app"
  "https://proxy.replicated.com/v2/"
  "https://images.r9.all-hands.dev/v2/"
  "https://install.r9.all-hands.dev"
  "https://charts.r9.all-hands.dev"
  "https://updates.r9.all-hands.dev"
  "https://github.com"
  "https://traefik.github.io/charts/index.yaml"
  "https://registry-1.docker.io/v2/"
  "https://ghcr.io/v2/"
)

for u in "${urls[@]}"; do
  # HTTP 000 means connection failure (DNS failure, timeout, or blocked network path).
  code=$(curl -sSIL --max-time 15 -o /dev/null -w "%{http_code}" "$u" || true)
  if [ "$code" = "000" ]; then
    echo "FAIL $u"
  else
    echo "OK   $u (HTTP $code)"
  fi
done

Any HTTP response code other than 000 is acceptable for reachability checks (for example 200, 301, 302, 401, 403, 405).

If any check fails, stop and resolve before continuing:

• DNS failures: Verify records are created, point to the right target, and have finished propagating
• Outbound connectivity failures: Check firewall egress rules, proxy settings, and TLS inspection policies

Reasons for Requirements

Requirement	Why It Exists
443/TCP inbound	Primary HTTPS entrypoint for users and service hostnames
30000/TCP inbound	Replicated/KOTS Admin Console for install and configuration
80/TCP inbound	HTTP entrypoint used for ingress/redirect behavior
*.runtime.<domain> DNS + cert SAN	Runtime sandboxes are addressed by dynamic runtime-specific hostnames
replicated.app, proxy.replicated.com	Replicated control-plane/license/install paths
images.r9..., charts.r9..., updates.r9..., install.r9...	Vendor distribution image/chart/update/install endpoints
traefik.github.io	Embedded cluster ingress chart repository
ghcr.io, registry-1.docker.io	Container image pulls for platform components
github.com	GitHub App setup/auth/webhooks and downloading public agent skills

Run the Installer

1. Access the Installer Dashboard

After preflight validation checks have passed, register for a free 30-day trial, then log in to the installer dashboard. You will see the dashboard below. Click “View install guide” in the Install tile.

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.

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, run sudo ./openhands support-bundle and share the resulting bundle with support.

We recommend providing your TLS certificates during installation. If you used the Terraform module, the certificates are in your home directory:

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.

4. Access the Admin Console

Once the install command completes, the Admin Console is available at:

• https://<your-base-domain>:30000 (if you provided TLS certificates)
• http://<your-vm-ip>: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.

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 your base domain under Hostname, upload your private key and SSL certificate, then click Continue.

6. Log in to the Admin Console

Enter the password you set during installation and click Log in.

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 OpenHands

You should now see the application configuration page.

Domain Configuration

• Select “Derive hostnames from domain (recommended)”
• 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

Enter your Anthropic API key from the Anthropic Console.

GitHub Authentication

Enable GitHub Authentication in the Admin Console, then follow these steps to create and configure a GitHub App.

Create a GitHub App

1. Go to github.com/settings/apps and click New GitHub App.

2. Set a unique GitHub App name (e.g., ACME Corp OpenHands).

3. Set the Homepage URL to https://app.<YOUR_BASE_DOMAIN>.

4. Under Identifying and authorizing users:

   • Set the Callback URL to:
     https://auth.app.<YOUR_BASE_DOMAIN>/realms/allhands/broker/github/endpoint
     
   • Check the box for Request user authorization (OAuth) during installation

5. Under Webhook:

   • Set the Webhook URL to:
     https://app.<YOUR_BASE_DOMAIN>/integration/github/events
     
   • Generate a webhook secret:
     export WEBHOOK_SECRET=$(openssl rand -base64 32 | tr -dc A-Za-z0-9 | head -c 32)
     echo $WEBHOOK_SECRET
     
   • Paste the generated value into the Secret field
   Save the webhook secret value — you will need to enter it in the Admin Console configuration.

6. Under Permissions, configure the following:

   Repository permissions:

   Permission	Access
   Actions	Read and write
   Commit statuses	Read and write
   Contents	Read and write
   Issues	Read and write
   Pull requests	Read and write
   Webhooks	Read and write
   Workflows	Read and write

   Organization permissions:

   Permission	Access
   Events	Read-only

   Account permissions:

   Permission	Access
   Email addresses	Read-only

7. Click Create GitHub App.

8. On the GitHub App page, under Client secrets, click Generate a new client secret. Save this value.

9. Under Private keys, click Generate a private key. The .pem file downloads automatically — note its location.

Map GitHub App values to Admin Console

Go back to the Installer Admin Console in your browser and enter the following values:

GitHub App Value	Admin Console Field
Client ID (shown on app page)	GitHub OAuth Client ID
Client secret (from step 8)	GitHub OAuth Client Secret
App ID (shown on app page)	GitHub App ID
Webhook secret (from step 5)	GitHub App Webhook Secret
Private key file (from step 9)	GitHub App Private Key (file upload)

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.

Click Details next to the deployment status to monitor individual resources. Resources shown in orange are still deploying — wait until all resources are ready.

First Login

Once the deployment status shows Ready, navigate to https://app.<your-base-domain> and click the Login with GitHub tile.

Accept the Terms of Service and click Continue.

OpenHands Enterprise is now running. You can open a repository or start a new conversation.

Next Steps

Enterprise Overview

Learn about OpenHands Enterprise features, integrations, and deployment options.

Prompting Best Practices

Get the most out of your AI coding agents with effective prompting techniques.

Contact Support

Reach out to the OpenHands team for deployment assistance or questions.

OpenHands Documentation

Explore the full OpenHands documentation for usage guides and features.