Skip to main content

​
Gemini - Google AI Studio Configuration

When running OpenHands, you’ll need to set the following in the OpenHands UI through the Settings under the LLM tab:
  • LLM Provider to Gemini
  • LLM Model to the model you will be using. If the model is not in the list, enable Advanced options, and enter it in Custom Model (e.g. gemini/<model-name> like gemini/gemini-2.0-flash).
  • API Key to your Gemini API key

​
VertexAI - Google Cloud Platform Configuration

To use Vertex AI through Google Cloud Platform when running OpenHands, you’ll need to set the following environment variables using -e in the docker run command:
Then set the following in the OpenHands UI through the Settings under the LLM tab:
  • LLM Provider to VertexAI
  • LLM Model to the model you will be using. If the model is not in the list, enable Advanced options, and enter it in Custom Model (e.g. vertex_ai/<model-name>).

​
Vertex AI Dependencies

The vertex_ai/* models (including Gemini and Claude via Vertex AI) require the google-cloud-aiplatform package, which is not included by default in the published agent-server image. How you enable it depends on your deployment:
Unlike AWS Bedrock (whose boto3 dependency is bundled by default), Vertex AI support is opt-in. If you skip this step, you will see a ModuleNotFoundError: No module named ‘vertexai’ error when the agent tries to call a Vertex AI model.

​
Local / Non-Docker Install

Install the vertex extra in your Python environment:

​
Custom Agent-Server Image

Build the image with the ENABLE_VERTEX build flag (the container build file is in the software-agent-sdk repo; run from the repo root):
Then point OpenHands at your custom image via the AGENT_SERVER_IMAGE_REPOSITORY and AGENT_SERVER_IMAGE_TAG environment variables (see the Custom Sandbox Guide for details).

​
OpenHands Enterprise (Replicated / Kubernetes)

The default OHE installer Vertex path routes LLM calls through a LiteLLM proxy — the agent-server uses a litellm_proxy/... model, and the proxy makes the actual Vertex call. So the agent-server image does not need Vertex enabled for the default path; ENABLE_VERTEX=1 is only relevant if you customize OHE to bypass the proxy and call vertex_ai/* directly from the agent-server.

​
Claude via Vertex AI

If you route Anthropic Claude through Google Vertex AI / Model Garden (rather than direct Anthropic endpoints), use the vertex_ai/ prefix with the Vertex-published model name, which is date-stamped:
  • Custom Model: vertex_ai/claude-sonnet-4-5@20250929
Use the exact model name shown in your Vertex AI Model Garden console.
For vertex_ai/* models, OpenHands still needs google-cloud-aiplatform from the vertex extra above. In custom Claude via Vertex AI setups, if you encounter ModuleNotFoundError: No module named ‘anthropic’, install the Anthropic SDK too: pip install “anthropic[vertex]”.

​
Troubleshooting

​
Vertex AI SDK Import Error

If you encounter this error:
This means the agent-server image does not include the Vertex AI SDK. Enable the vertex extra as described in Vertex AI Dependencies above.