Skip to main content

​
Gemini - Google AI Studio Configs

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 Configs

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: 
GOOGLE_APPLICATION_CREDENTIALS="<json-dump-of-gcp-service-account-json>"
VERTEXAI_PROJECT="<your-gcp-project-id>"
VERTEXAI_LOCATION="<your-gcp-location>"
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: 
pip install "openhands-sdk[vertex]"
# or, with uv (works in any Python environment):
uv pip install "openhands-sdk[vertex]"

​
Custom Agent-Server Image

Build the image with the ENABLE_VERTEX build flag (the Dockerfile is in the software-agent-sdk repo; run from the repo root): 
docker build \
    --build-arg ENABLE_VERTEX=1 \
    -t my-agent-server:vertex \
    -f openhands-agent-server/openhands/agent_server/docker/Dockerfile \
    .
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.
Claude via Vertex AI may also require the anthropic[vertex] package in addition to google-cloud-aiplatform. If you encounter ModuleNotFoundError: No module named ‘anthropic’, ensure the image includes both dependencies.

​
Troubleshooting

​
”No module named ‘vertexai’” Error

If you encounter this error: 
litellm.BadRequestError: Vertex_aiException BadRequestError - vertexai import failed
please run `pip install -U "google-cloud-aiplatform>=1.38"`.
Got error: No module named 'vertexai'
This means the agent-server image does not include the Vertex AI SDK. Enable the vertex extra as described in Vertex AI Dependencies above.