OpenHands on GCP - Developer Guide

Welcome to the Meetrix OpenHands developer guide for Google Cloud Platform! OpenHands is an open-source platform for AI software development agents that can write and modify code, run shell commands, browse the web, and call APIs, much like a human developer working through a described task. It works with a range of LLM providers, connects directly to your GitHub, GitLab, or Bitbucket repositories, and gives you a self-hosted foundation for AI-assisted software engineering without sending your codebase through a third-party SaaS tool.

With the Meetrix pre-configured GCP image, you can deploy a production-ready OpenHands instance on your own Google Cloud project in minutes. This guide walks you through finding the product on GCP Marketplace, configuring the deployment, pointing DNS and issuing SSL, configuring an LLM provider, and connecting your first repository. If you run your infrastructure on AWS instead, the OpenHands on AWS developer guide covers the same product as a CloudFormation stack.

Launch the Product

Step 1: Find the Product

1. Log in to your Google account.
2. Go directly to the product page: OpenHands: Open Source Devin Alternative AI Coding Agent on GCP Marketplace.
3. You can also browse all Meetrix products at the Meetrix Solutions Page.

Step 2: Launch the Product

1. Select your GCP project from the project selector at the top.
2. Review the product description and pricing details.
3. Review the terms and agreements, tick the acknowledgement checkbox, and click AGREE.

Free Trial

This product includes a 5-day free trial with up to USD 50.00 in licence fee credits. To activate it, tick I accept the solution trial Terms and Conditions before proceeding.

Step 3: Configure the Deployment

You will see the deployment configuration form. Fill in the fields across the following sections.

General

• Deployment name - A unique name for this deployment (a default is pre-filled).
• Deployment Service Account - Select an existing service account that has the roles/config.agent, roles/compute.admin, and roles/iam.serviceAccountUser roles, or let GCP create a new one for you.
• Zone - Select the GCP zone closest to your users (for example us-central1-a).

Machine Type

• Series - The General purpose tab is preselected.
• Machine type - Choose an instance sized for how many concurrent agent sessions you expect to run. A larger machine type helps when working on large codebases or running multiple sessions at once.

GCP shows an estimated monthly cost, made up of the Meetrix licence fee and the underlying infrastructure fee, based on your selected machine type and disk size before you deploy.

Step 4: Configure Networking

• Network and Subnetwork - Leave as default unless you have a custom VPC.
• External IP - Leave as Ephemeral. Select None only if you do not need public internet access (not recommended, since you access the dashboard over HTTPS).
• Allow SSH (TCP port 22) from the Internet - Enabled by default. Restrict the source IP range if you want to limit SSH access to specific IPs.

Step 5: Application Settings

Scroll down to the API Access and Application Settings sections and provide:

• Allow full access to all of Google Cloud Platform APIs on the VM - Leave unticked unless your workflow specifically needs it.
• Domain name - The public domain for your OpenHands dashboard (for example openhands.yourdomain.com). Point your DNS A record to the instance IP before or shortly after deploying.
• Admin email - The email address used when requesting the Let's Encrypt SSL certificate.

Tick I accept the solution trial Terms and Conditions, then click Deploy and wait a few minutes for the deployment to complete.

Point DNS to Your OpenHands Server

Skip this section if you plan to access the instance by its external IP address instead of a real domain.

Step 1: Get the External IP

1. Once deployment is complete, open the VM instance from the deployment details.
2. Copy the External IP from the Network interfaces section.

Step 2: Create a DNS A Record

1. Go to your DNS provider.
2. Add an A record pointing your OpenHands domain (for example openhands.yourdomain.com) to the copied external IP.
3. Wait for DNS propagation before proceeding (typically a few minutes to 1 hour).

Access OpenHands

Once DNS has propagated and SSL has issued, visit your domain. The first time you open the dashboard, OpenHands prompts you to configure an LLM provider before you can start a conversation.

1. Choose an "LLM Provider" - either the built-in OpenHands hosted option, or a provider you already have an API key for, such as Anthropic or OpenAI.
2. Select an "LLM Model".
3. Paste in your "API Key".
4. Click "Save".

Once a provider is configured, open "Integrations" from the dashboard and connect a Git provider, such as GitHub, GitLab, or Bitbucket. OpenHands uses this connection to see your repositories and suggest tasks based on them.

If you'd rather point an AI coding agent at a self-hosted model instead of a third-party API key, our vLLM on GCP developer guide covers serving an OpenAI-compatible model yourself, and the best open source LLMs for self-hosting rundown is a reasonable place to pick one.

Generate an SSL Certificate Manually

OpenHands will automatically try to issue SSL for the domain name you provided as the Domain name field. If it's unsuccessful, for example if DNS hadn't propagated yet, you can generate it manually.

Step 1: SSH into the Server

1. Go to the VM instance page in the GCP console.
2. Click SSH to open a browser-based terminal and authorize access.

Step 2: Generate SSL

Run the following command and follow the prompts:

sudo bash /root/certificate_generate_standalone.sh

This script runs certbot using the domain name and admin email you provided as deployment parameters.

Manage the Deployment

Stop the VM

To stop the VM without deleting it, go to Compute Engine → VM Instances in the GCP console, select your instance, and click Stop. You can restart it later with your data intact. If the external IP is ephemeral it may change on restart, so update your DNS A record afterward, or reserve a static IP if you stop and start the VM often.

Remove OpenHands

To fully remove the deployment and stop all billing:

1. Go to Solution deployments in the GCP console.
2. Find your OpenHands deployment.
3. Click Delete to remove all associated resources.

Back up any conversation history or workspace files you need before deleting the deployment.

Upgrades

When a new image version is available in the GCP Marketplace, back up any data you need, remove the previous deployment, and relaunch with the new version.

Troubleshoot

Quota or Capacity Errors

GCP enforces regional CPU quotas. If you hit a quota error when deploying, request a Compute Engine CPU quota increase for that region, or choose a different region or zone with available capacity.

502 Bad Gateway

If the dashboard is temporarily inaccessible, wait 5-10 minutes and retry. The application is likely still starting up.

SSL Did Not Issue

Confirm your DNS record points at the external IP and has propagated, then re-run the certificate script from the "Generate an SSL Certificate Manually" section.

Disk Space

If OpenHands becomes unresponsive, check whether the boot disk is full:

df -h

If the root volume is between 90-100% full, resize the persistent disk in the GCP console, then reboot the instance and restart the service.

Conclusion

The Meetrix OpenHands Deployment Guide helps you get a self-hosted AI software engineering agent running on your own GCP project in minutes. Whether you're automating routine coding tasks, reviewing pull requests, or exploring what an AI agent can do against your own repositories, this guide gives you a secure, working starting point.

Deploying on AWS Instead?

The same product is available as a CloudFormation stack on AWS Marketplace.

OpenHands on AWS - Developer Guide

Deploy OpenHands, the open-source AI software engineering agent platform, on AWS with our step-by-step CloudFormation guide. Learn how to launch, secure with SSL, configure an LLM provider, and connect your Git repositories.

By Binuka Ranatunga • Meetrix.io

Technical Support

Reach out to Meetrix Support (support@meetrix.io) for assistance with OpenHands issues.