How do I enable BYOK in OpenHands Cloud and use my own OpenAI/Anthropic/Bedrock/Vertex keys?

OpenHands Cloud lets you bring your own OpenAI, Anthropic, Bedrock, and Vertex model keys so you keep control over cost, data residency, and vendor choice while still getting a shared agent platform for your team. BYOK is available across OpenHands Cloud plans and can be combined with OpenHands’ own at-cost provider if you want a hybrid setup.

Quick Answer: Enable BYOK in OpenHands Cloud by going to Settings → Language Models (LLM) in your org, adding your OpenAI/Anthropic/Bedrock/Vertex keys, and selecting which models are available to agents. Once configured, agents running in the Web GUI, CLI, and SDK will call your models through the OpenHands sandbox runtime, so you keep full control of providers, credentials, and spend.

Why This Matters

If you’re serious about running coding agents in production, you can’t be locked into a single model vendor or pricing model. BYOK in OpenHands Cloud lets you plug in OpenAI, Anthropic, Bedrock, and Vertex the same way you wire up any other piece of infrastructure: via scoped, auditable credentials and a runtime boundary you control. You choose which provider backs which workload—bugfix PRs, test generation, dependency upgrades—without rewriting your pipelines or surrendering visibility into what the agent did.

Key Benefits:

• Cost and provider control: Route workloads to the right model (and cloud) for the job, and pay your providers directly while still using OpenHands’ orchestration.
• Compliance and data governance: Keep model traffic inside your chosen vendors and regions while OpenHands runs in a containerized sandbox with audit logs.
• Future-proofing and flexibility: Swap models, add new providers, or run a hybrid of BYOK and OpenHands at-cost models without reworking your agent workflows.

Core Concepts & Key Points

Concept	Definition	Why it's important
BYOK (Bring Your Own Key)	Configuring OpenHands Cloud to use your own API keys for LLM providers like OpenAI, Anthropic, Bedrock, or Vertex	Preserves model choice, lets you buy at enterprise rates, and keeps you out of proprietary lock-in
Model-Agnostic Runtime	OpenHands’ ability to call different LLMs behind the same agent interface and sandboxed execution environment	You can change providers or models without rewriting automation, pipelines, or SDK code
Sandboxed Agent Execution	Every agent runs in an isolated Docker/Kubernetes-style container with controlled access to repos, credentials, and tools	You get autonomy without black boxes: inspect artifacts, audit runs, and re-run tasks deterministically

How It Works (Step-by-Step)

At a high level, enabling BYOK in OpenHands Cloud is a three-part process: configure providers, scope which models agents can use, and wire the same runtime into your CLI/SDK/CI.

1. Configure your LLM keys in OpenHands Cloud

In your OpenHands Cloud org:

1. Navigate to Settings → Language Models (LLM).

2. For each provider you want to use, add your credentials:

   • OpenAI

     • Create or locate an API key in your OpenAI account.
     • In OpenHands, select OpenAI as a provider.
     • Paste your API key, optionally add org ID if required.
     • Save and test the connection (e.g., via a quick agent run on a small repo).

   • Anthropic

     • Generate an API key in the Anthropic console (Claude).
     • In OpenHands, select Anthropic.
     • Paste the key and save.
     • Enable the specific Claude models you want agents to call (e.g., Claude 3.5 Sonnet) if OpenHands exposes per-model toggles.

   • Amazon Bedrock

     • In AWS, provision Bedrock access and an IAM role/user with scoped permissions.
     • Create access keys or configure a role that OpenHands can use (depending on your deployment model).
     • In OpenHands, choose Bedrock and provide:
       • Access key/secret or role details
       • Region and target models (e.g., Anthropic via Bedrock, Amazon Titan, etc.)
     • Confirm that the agent’s runtime can reach Bedrock from your VPC/network.

   • Google Vertex AI

     • In GCP, create a service account with Vertex AI permissions.
     • Generate a JSON key for that service account.
     • In OpenHands, select Vertex and upload the service account JSON or paste the key fields.
     • Set project ID, region, and model IDs as required.

3. Decide whether to:

   • Only use BYOK, or
   • Mix BYOK with OpenHands provider at-cost (OpenHands Cloud supports BYOK or using its own provider at-cost; many teams use both and route workloads accordingly).

Once configured, OpenHands will invoke these providers from within its containerized sandbox runtime, not from your developer laptops.

2. Choose default models and routing behavior

Next, define how agents actually use your keys:

1. Still under Settings → Language Models (LLM):
   • Set a default model for:
     • Interactive Web GUI sessions
     • CLI/terminal runs (if your plan exposes separate defaults)
     • SDK/API-created agents (e.g., long-running automation)
   • Enable/disable specific models to control what’s available to users.
2. Optionally set policy by environment or project:
   • For security-sensitive repos, you might restrict to:
     • Anthropic via Bedrock in a specific AWS region, or
     • Vertex in a locked-down GCP project.
   • For lower-risk tasks (e.g., docs generation), you might allow a wider set of models or use OpenHands’ at-cost provider.

From here, your engineers can call agents without specifying provider details; OpenHands resolves to the right model based on the settings and policies you’ve defined.

3. Use your BYOK setup from Web GUI, CLI, and SDK

Once BYOK is configured, it’s automatically applied across surfaces:

1. Web GUI

   • When a user starts an agent run (e.g., “fix failing tests in this repo” or “upgrade these dependencies”), the agent calls your configured models through the sandbox runtime.
   • The full trace—commands executed, diffs created, tests run—remains visible and auditable for each run.

2. OpenHands CLI / Local Web UI

   • Generate a token from Settings → API in your OpenHands Cloud account.
   • Configure the CLI to use this token.
   • When you run agents from your terminal (e.g., against local or remote repos), requests are routed through your org’s model settings, including BYOK providers.

3. OpenHands Cloud Agent SDK / Automation

   • Use the Cloud Agent SDK to orchestrate agents from CI, cron jobs, or internal tools.
   • The SDK doesn’t need embedded provider keys; it relies on your org’s BYOK configuration in OpenHands Cloud.
   • This keeps secrets concentrated in one place with RBAC and auditability, instead of scattered across pipelines.

The net effect: same agent behaviors and outputs, but LLM calls are backed by your OpenAI/Anthropic/Bedrock/Vertex contracts and environments.

Common Mistakes to Avoid

• Hardcoding LLM keys directly in CI or app code:
  This bypasses OpenHands’ sandbox and governance. Instead, centralize provider keys in Settings → Language Models (LLM) and let the CLI/SDK use your OpenHands API token.

• Using a single “god key” with unlimited scope:
  Avoid an over-privileged root key for LLM providers. Create scoped API keys or service accounts per environment (dev/stage/prod) and per provider, then map them into OpenHands with clear naming and access policies.

• Ignoring model-region alignment for compliance:
  For Bedrock and Vertex, ensure regions and data handling settings match your compliance needs. Don’t leave them at defaults if your data residency or privacy policy requires specific regions.

• Assuming BYOK disables OpenHands’ at-cost models by default:
  BYOK and OpenHands at-cost can coexist. Explicitly choose which models are enabled and which are defaults so you don’t accidentally send traffic to the wrong provider.

Real-World Example

A regulated fintech team wants to use Anthropic models for code refactors and bugfix PRs, but all traffic must stay within their AWS accounts. They deploy OpenHands Cloud with:

• Self-hosted in their VPC, using containerized sandbox runtimes for agents.
• Anthropic via Amazon Bedrock configured under Settings → Language Models (LLM) with scoped IAM roles.
• OpenAI added as a secondary provider using BYOK for non-sensitive workloads like docs and release notes.

They configure:

• Bedrock Anthropic as the default for production repos.
• OpenAI as an opt-in model for a “docs-bot” project used only on public documentation.

Developers trigger agents from:

• The Web GUI to triage bug tickets into reviewable PRs.
• The CLI to run large-scale dependency upgrades across multiple services.
• A CI job wired through the Cloud Agent SDK to automatically fix failing tests on new PRs.

Every run is logged with which provider/model was used, what commands executed, and what diffs were produced. When the team later negotiates a better OpenAI contract, they simply update the OpenAI key and defaults in OpenHands—no pipeline rewrites, no secret sprawl.

Pro Tip: Treat LLM providers like any other production dependency: define per-environment credentials, lock them behind SSO/RBAC in OpenHands, and use tags or naming conventions (“bedrock-prod-anthropic”, “vertex-eu-docs”) so you can quickly audit and rotate them without guesswork.

Summary

BYOK in OpenHands Cloud lets you connect your own OpenAI, Anthropic, Bedrock, and Vertex keys to a model-agnostic agent runtime that’s built for real engineering work. You centralize provider configuration in Settings → Language Models (LLM), choose which models and regions are allowed, and then let agents run from the Web GUI, CLI, or SDK with full auditability and sandbox isolation. Model choice stays yours; OpenHands provides the secure, observable execution layer that makes autonomous code changes safe to adopt.

Next Step

Get Started