Quick Start

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

This guide walks you through trialing OpenHands Enterprise on AWS. You’ll provision infrastructure with Terraform, configure GitHub for user authentication, and set up Anthropic as your LLM provider.

Prerequisites

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 instances, Route53 records, and ACM certificates

Provision 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
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
• docker.io
• docker.dev
• 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.

Run the Installer

1. Access the Installer Dashboard

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 — 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 using self-signed certificates)

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 the GitHub App name (e.g., 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

Enter the following values in the Admin Console configuration:

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 Save config in the Admin Console, then click Continue.

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.