OpenHands Enterprise: how do I deploy it in our VPC on Kubernetes (prereqs and architecture)?

Most platform teams evaluating OpenHands Enterprise ask the same first question: what does a secure, production-ready deployment in our own VPC on Kubernetes actually look like? This guide walks through the concrete prerequisites, recommended architecture, and cluster-level patterns so you can plan a deployment that’s auditable, scalable, and aligned with your existing controls.

Quick Answer: You deploy OpenHands Enterprise into your VPC as a containerized, sandboxed runtime running on Kubernetes, fronted by your usual ingress, identity, and secrets management stack. At minimum, you’ll need a managed or self-hosted Kubernetes cluster, private networking, an external database and object store (or managed equivalents), and connectivity to your source control and LLM providers—plus RBAC, SSO/SAML, and audit logging wired through your existing infra.

Why This Matters

If you’re considering OpenHands Enterprise, you’re not looking for a toy copilot. You’re trying to run autonomous coding agents that can touch real repos, CI/CD, and production-adjacent systems—without punching holes in your governance model. That means:

• Agents must execute in a secure, sandboxed runtime you control.
• Every run needs visibility: what executed, what changed, and how to replay it.
• The platform must deploy cleanly into your VPC, respecting your Kubernetes, networking, and identity standards.

Getting the deployment architecture right up front determines whether OpenHands becomes a central, auditable automation layer—or another silo you have to work around.

Key Benefits:

• Security aligned with your VPC model: OpenHands runs in your Kubernetes cluster, inside your VPC, with fine-grained access control and auditability instead of a black-box SaaS endpoint.
• Scalable agent runtime: The same deployment scales from a single developer-triggered task to thousands of parallel agent runs for repo-wide upgrades, all inside containerized sandboxes.
• Model and tooling flexibility: Because the platform is model-agnostic, you can bring your own LLM providers, wire in your CI/CD, and adapt it to your existing SDLC workflows without vendor lock-in.

Core Concepts & Key Points

Concept	Definition	Why it's important
Containerized sandbox runtime	The isolated execution environment where each OpenHands agent runs, typically as a short-lived Kubernetes pod with scoped credentials.	Prevents agents from escaping their boundary, enforces least privilege, and makes every run auditable and reproducible.
Model-agnostic architecture	OpenHands Enterprise integrates with multiple LLM providers (e.g., Anthropic, OpenAI, Bedrock) via configuration, not hard-coded assumptions.	You keep procurement and technical flexibility to switch models, run BYOK, or use at-cost endpoints without refactoring the platform.
Enterprise control plane	The set of services (API, Web GUI, CLI/SDK endpoints, identity, and policy) that orchestrate agents, store metadata, and surface artifacts like diffs and logs.	Centralizes governance—RBAC, SSO/SAML, audit logs—while letting teams trigger and review agent work from GitHub, GitLab, Slack, CI/CD, or the terminal.

How It Works (Step-by-Step)

At a high level, deploying OpenHands Enterprise in your VPC on Kubernetes looks like any other production-grade internal platform: cluster, networking, identity, data stores, and runtime sandboxes. Here’s the deployment flow.

1. Establish cluster and networking prerequisites

   • Kubernetes cluster: A production-grade cluster in your VPC (EKS, GKE, AKS, or self-managed) with:
     • At least one node pool dedicated to OpenHands.
     • Cluster-level logging/monitoring (CloudWatch, Stackdriver, Prometheus/Grafana, etc.).
   • Networking:
     • Private subnets for the OpenHands namespace (inbound access via an ingress controller).
     • Egress rules to reach:
       • Your Git hosting (GitHub Enterprise, GitLab, Bitbucket, etc.).
       • CI/CD systems (for headless runs and integration).
       • LLM providers (unless you’re running models inside the same VPC).
       • Optional: internal artifact registries, ticketing systems, or issue trackers.
   • Ingress & DNS:
     • An ingress controller (NGINX, ALB, GKE Ingress, etc.).
     • Internal or external DNS pointing to the Web GUI and API endpoints.

2. Provision data and identity dependencies

   • Database: A managed relational database (e.g., RDS, Cloud SQL, Azure Database) or a self-hosted equivalent inside your VPC for:
     • Configuration/state of agents.
     • Audit logs and run metadata.
     • User and workspace data.
   • Object storage:
     • S3 / GCS / Azure Blob / on-prem object storage for:
       • Logs, artifacts, and potentially large model outputs.
       • Generated docs, release notes, and other SDLC artifacts.
   • Identity & access:
     • SSO/SAML: Integration with your IdP (Okta, Azure AD, Google Workspace, etc.).
     • RBAC: Map groups/roles to OpenHands organizations, projects, and permissions (e.g., who can trigger production-facing agents vs. sandbox-only runs).
     • Service credentials: Use your standard secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.) to store:
       • LLM API keys or service accounts.
       • Git provider tokens (ideally installation-based rather than user PATs).
       • CI/CD tokens and any environment-scoped secrets.
   • Audit logging:
     • Wire OpenHands audit logs into your SIEM or log aggregation (Splunk, Datadog, Elastic, etc.).
     • Ensure logs include user identity, agent configuration, run trace, and resulting artifacts.

3. Deploy the OpenHands Enterprise control plane and agent runtime

   The deployment itself typically uses Helm charts or a similar Kubernetes manifest pack provided by the OpenHands team. The architecture breaks down into:

   • Control plane services:
     • API service: Orchestrates agent runs, integrates with SDK/CLI, and exposes endpoints for external systems (GitHub/GitLab, CI/CD, Slack).
     • Web GUI: Shared workspace for scoping tasks, supervising runs, and reviewing diffs/artifacts.
     • Background workers: Handle long-running tasks, integration webhooks (GitHub, GitLab, Slack), and queue-based operations.
   • Agent execution layer:
     • Agent runner pods: Short-lived pods in a dedicated namespace or node pool.
     • Each run executes in a containerized sandbox with:
       • Scoped repo access (via GitHub/GitLab tokens or App installations).
       • Controlled network egress (to only the systems the agent needs).
       • Bounded CPU/memory and timeouts to prevent runaway tasks.
   • Observability:
     • Metrics: Export to your metrics system (Prometheus, Datadog, etc.) for request rates, worker queues, and agent runtimes.
     • Tracing (if enabled): For end-to-end run tracing across API, workers, and agent pods.
     • Logs: Aggregated to your log platform, with correlation IDs per run.

Once these three layers are in place, teams can delegate work from the terminal, Web GUI, or SDK into the same runtime, and you retain full control over where and how every agent runs.

Common Mistakes to Avoid

• Treating agents like a SaaS plugin instead of infrastructure:
  • How to avoid it: Plan the deployment as you would CI/CD or internal developer platforms—Kubernetes, ingress, network policies, SSO/SAML, RBAC, and audit logging from the start. Agents produce diffs, tests, and PRs in your repos; they deserve the same standards as build and deploy pipelines.
• Over-permissioning credentials:
  • How to avoid it: Issue scoped tokens per environment and per integration. For example, separate:
    • Read-only repo access for analysis/summarization agents.
    • Write-scoped repo access for agents that open PRs.
    • Isolated credentials for staging vs. production repos.
  • Pair each with dedicated Kubernetes secrets and network policies so a compromised pod can’t pivot laterally.

Real-World Example

A regulated enterprise wanted OpenHands Enterprise running “fully inside our VPC on Kubernetes,” with no public SaaS dependency and tight governance. Their approach:

• Cluster & network: They spun up a dedicated EKS cluster in their primary VPC, with:
  • Private subnets for the OpenHands namespace.
  • An internal ALB-based ingress with DNS registered in their private zone.
  • Egress restricted to:
    • GitHub Enterprise (hosted in a peered VPC).
    • An internal CI/CD system.
    • A centrally managed API gateway that proxied outbound LLM traffic to multiple providers.
• Identity & governance:
  • Wired the Web GUI and API to Okta via SAML, mapping Okta groups to OpenHands roles:
    • “Agent Admins” could define agent templates and configure integrations.
    • “Maintainers” could trigger write-capable agents on guarded repos.
    • “Developers” could run read-only and sandbox agents.
  • Forwarded all OpenHands audit logs into Splunk, tagged with user ID, repo, and environment.
• Runtime design:
  • Created a dedicated node group for agent pods with strict network policies:
    • Only allowed egress to GitHub Enterprise, the CI/CD API, and the LLM gateway.
    • Denied direct access to production databases or internal microservices.
  • Used AWS Secrets Manager to inject per-repo and per-environment tokens into agent pods at runtime.
• Outcomes:
  • They started with safe, read-only workflows: PR summaries, test gap analysis, and release note generation from commits.
  • Once comfortable with the audit logs and diff review flow, they enabled write-capable agents for:
    • Dependency upgrades across monorepos.
    • Automated fixes for failing tests.
    • Security patch PRs from their vulnerability backlog.

They got “same agent, same runtime” across interactive terminal sessions, the Web GUI, and headless CI/CD runs—without relaxing their VPC or Kubernetes guardrails.

Pro Tip: Treat OpenHands agent pods like mini CI runners, not like app microservices. Use separate node pools, network policies, and scoped credentials so you can safely let agents touch real repos while keeping them fenced off from production data paths.

Summary

Deploying OpenHands Enterprise in your VPC on Kubernetes is straightforward if you treat it as what it is: an open, model-agnostic platform for autonomous coding agents that behaves like real infrastructure. You provision a production-grade cluster, attach it to your identity, logging, and secrets stack, and run agents inside a containerized sandbox runtime you control.

The payoff is autonomy with observability: you can see exactly what each agent did, inspect the diffs, trace the run, and re-run it deterministically—whether it was triggered from the Web GUI, the terminal, or your CI/CD pipelines. No black-box behavior. No babysitting. Just reviewable engineering work produced inside your own VPC boundary.

Next Step

Get Started