Google Cloud Quick Start

Install OpenHands Enterprise on Google Compute Engine with Replicated Embedded Cluster and configure Vertex AI.

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. This guide covers provisioning, DNS and TLS, installation, Vertex AI configuration and a completed conversation. Use the Admin Console Configuration reference 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 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.

export PROJECT="<google-cloud-project>"
export ZONE="us-central1-a"
export REGION="us-central1"
export VM="openhands-replicated-eval"
export NETWORK="$VM"
export ADMIN_CIDR="<your-public-ip>/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:

ssh-keygen -t ed25519 -f "$HOME/.ssh/openhands-google" -C openhands-google

Create Networking and Ingress Rules

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.

export IMAGE="<reviewed-ubuntu-24.04-x86-64-image-name>"
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

cat /etc/os-release
uname -r
nproc
free -h
df -h / /var/lib
sudo -n true

Sysbox requires Linux kernel 6.3 or newer. Verify your image’s actual kernel against the sandbox requirements and run the installer’s host preflights before proceeding. Do not change the kernel solely because its version differs from the tested configuration.

The validated installation used Ubuntu’s generic kernel 6.8.0-146. The Google image initially booted 7.0.0-1011-gcp, which was not tested with Sysbox; this does not establish that it is incompatible. If you encounter a compatibility failure, use the documented troubleshooting process and OpenHands Support to select a supported kernel.

Configure DNS and TLS

Create a wildcard A record in your domain’s managed zone:

export DNS_PROJECT="<dns-project>"
export DNS_ZONE="<managed-zone-name>"
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 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.

export VERTEX_PROJECT="<vertex-project-id>"
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 (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 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 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, 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 and 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 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:

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 to generate a support bundle.

3. Open the Admin Console

Open https://admin.<your-base-domain>: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 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
LLM Provider	Google
Google API Type	Google Cloud Platform (Vertex AI)
Google Cloud Project ID	Your Vertex inference project ID
Google Cloud Location	Your model’s supported location; tested with us-central1
Google Cloud Service Account JSON file	Upload your service-account JSON file
Vertex AI 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. 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 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 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.<your-base-domain> 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 provides an agent workflow for resource planning, preflights, installation and end-to-end checks. Use this guide and the Replicated Admin Console as the reference for release-specific requirements and configuration fields.

Validation Scope

Validated with Replicated 0.74.0, installer v2.19.2+k8s-1.36 and Ubuntu 24.04 with generic kernel 6.8.0-146: host and application preflights, trusted HTTPS, GitHub login, persistent PostgreSQL storage, administrator-managed Vertex Gemini 2.5 Flash inference, sandbox terminal file operations, and a read-only GitHub repository conversation.

Backup/restore, upgrades, additional nodes and automatic certificate renewal were not covered by these checks.