PLTF-4: Automate LiteLLM setup (#253)

* Automatically provision new LiteLLM team on installation.

Author: jlav

.gitignore

@@ -1,3 +1,10 @@
 charts/**/charts
 
-**/.DS_Store
+**/.DS_Store
+
+# Files generated by JetBrains IDEs, e.g. IntelliJ IDEA
+.idea/
+*.iml
+
+# Vscode files
+.vscode

charts/openhands/Chart.lock

@@ -10,7 +10,7 @@ dependencies:
   version: 1.2.13
 - name: litellm-helm
   repository: oci://ghcr.io/berriai
-  version: 0.1.664
+  version: 0.1.781
 - name: minio
   repository: https://charts.min.io/
   version: 5.0.10
@@ -22,6 +22,6 @@ dependencies:
   version: 20.3.0
 - name: runtime-api
   repository: oci://ghcr.io/all-hands-ai/helm-charts
-  version: 0.1.9
-digest: sha256:0eb3fcb98ec8a1aa3d6c2ba5e317942cbc2030a35440836ad6aec63de0dfb11e
-generated: "2025-08-21T14:15:03.196589052Z"
+  version: 0.1.20
+digest: sha256:993e079383b8356e71d7b12cdc0ae82ee0747f5ce72a9d7307471aa2c9be0da9
+generated: "2026-01-15T17:32:49.752308-05:00"

charts/openhands/Chart.yaml

@@ -2,7 +2,7 @@ apiVersion: v2
 description: OpenHands is an AI-driven autonomous software engineer
 name: openhands
 appVersion: 0.62.0
-version: 0.1.35
+version: 0.2.0
 maintainers:
   - name: rbren
   - name: xingyao

charts/openhands/README.md

@@ -247,51 +247,19 @@ authentication as well.
 
 When the chart is deployed, a job will run to configure the Keycloak realm with the identity provider credentials you provided.
 
-### Install OpenHands
-
-Now we can install the helm chart.
-
-```bash
-helm dependency update
-helm upgrade --install openhands --namespace openhands oci://ghcr.io/all-hands-ai/helm-charts/openhands -f site-values.yaml
-```
-
-This installation won't complete successfully the first time because we need to set up LiteLLM.
+### LiteLLM configuration
 
-> [!NOTE]
-> This process will be automated in the near future.
->
 > [!IMPORTANT]
 > We recommend using the provided LiteLLM instance rather than bringing your
 > own. The provided LiteLLM instance uses an admin key for automated user
 > management, which is the most extensively tested scenario. Our automation
 > relies on this admin key to create and delete users automatically.
 
-To set up LiteLLM, first use port-forward to connect:
-
-```bash
-kubectl port-forward svc/openhands-litellm 4000:4000 -n openhands
-```
-
-Next, create a new Team in LiteLLM:
-
-- Navigate to <http://localhost:4000/ui> in your browser.
-- login using the username `admin` password $GLOBAL_SECRET (set above).
-- go to Teams -> Create New Team.
-- Name it whatever you want.
-- Get the team id (e.g. `e0a62105-9c6c-4167-b5be-16674a99d502`), and add it to site-values.yaml:
-
-```yaml
-litellm:
-  teamId: "<TEAM_ID>"
-```
+#### Configure LiteLLM Models
 
-You'll also need to set your model list for LiteLLM, using the LLM secrets you set above:
+You'll need to set your model list for LiteLLM, using the LLM secrets you set above:
 
 ```yaml
-litellm:
-  teamId: "<TEAM_ID>"
-
 litellm-helm:
   proxy_config:
     model_list:
@@ -301,25 +269,38 @@ litellm-helm:
           api_key: os.environ/ANTHROPIC_API_KEY
 ```
 
-Finally you will need to set the default LLM model to use in your site-values.yaml. Find the "env:" section below in your site-values.yaml and uncomment the LITELLM_DEFAULT_MODEL. Set "your-model" to one of the models you configured:
+You will also need to set the default LLM model to use in your site-values.yaml. Find the "env:" section in your site-values.yaml and uncomment the LITELLM_DEFAULT_MODEL. Set "your-model" to one of the models you configured:
 
 ```yaml
 env:
-  # This var will cause the openhands deploy to create the LLM team name if it doesn't exist already
-  LITE_LLM_TEAM_NAME: openhands
   # replace <your-model> with your LLM model and uncomment this variable
-  # LITELLM_DEFAULT_MODEL: "litellm_proxy/<your-model>"
+  LITELLM_DEFAULT_MODEL: "litellm_proxy/<your-model>"
 ```
 
-### Verify your Setup
+#### LiteLLM Team Configuration
+
+To use an existing team, provide the team ID.
+
+If you do not set a team ID, a new team with ID `openhands` will be created. If the team ID you provide doesn't
+already exist, a new team with that ID will be created.
+
+```yaml
+litellm:
+  teamId: "<TEAM_ID>"
+```
 
-Finally, upgrade the release:
+### Install OpenHands
+
+Now we can install the helm chart.
 
 ```bash
+helm dependency update
 helm upgrade --install openhands --namespace openhands oci://ghcr.io/all-hands-ai/helm-charts/openhands -f site-values.yaml
 ```
 
-You should now be able to see OpenHands running with:
+### Verify your Setup
+
+After installation, you should be able to see OpenHands running with:
 
 ```bash
 kubectl port-forward svc/openhands-service 3000:3000 -n openhands

charts/openhands/example-values.yaml

@@ -3,8 +3,6 @@
 #   tag: 0.47.0
 
 env:
-  # This var will cause the openhands deploy to create the LLM team name if it doesn't exist already
-  LITE_LLM_TEAM_NAME: openhands
   # replace <your-model> with your LLM model and uncomment this variable
   # LITELLM_DEFAULT_MODEL: "litellm_proxy/<your-model>"
 
@@ -50,7 +48,7 @@ litellm:
   # NOTE: We recommend using the provided LiteLLM instance for simplicity and
   # because it is the most extensively tested scenario. Our automation uses an
   # admin key to do user management for the LiteLLM instance.
-  enabled: false
+  enabled: true
   url: "https://llm-proxy.example.com"
 
 litellm-helm:

charts/openhands/templates/_env.yaml

@@ -186,20 +186,23 @@
 {{- else if .Values.litellm.enabled }}
 - name: LITE_LLM_API_URL
   value: {{ .Values.litellm.url }}
-- name: LITE_LLM_TEAM_ID
-  value: {{ .Values.litellm.teamId }}
-- name: LITE_LLM_API_KEY
-  valueFrom:
-    secretKeyRef:
-      name: {{ .Values.litellm.auth.existingSecret }}
-      key: lite-llm-api-key
 {{- end }}
 {{- if index .Values "litellm-helm" "enabled" }}
 - name: LITE_LLM_API_KEY
   valueFrom:
     secretKeyRef:
       name: {{ index .Values "litellm-helm" "masterkeySecretName" }}
       key: {{ index .Values "litellm-helm" "masterkeySecretKey" }}
+{{- else if .Values.litellm.enabled }}
+- name: LITE_LLM_API_KEY
+  valueFrom:
+    secretKeyRef:
+      name: {{ .Values.litellm.auth.existingSecret }}
+      key: lite-llm-api-key
+{{- end }}
+{{- if .Values.litellm.enabled }}
+- name: LITE_LLM_TEAM_ID
+  value: {{ .Values.litellm.teamId }}
 {{- end }}
 {{- if .Values.stripe.enabled }}
 - name: STRIPE_API_KEY

charts/openhands/templates/deployment.yaml

@@ -14,6 +14,10 @@ spec:
       labels:
         app: openhands
       annotations:
+        checksum/keycloak-config: {{ include (print $.Template.BasePath "/keycloak-config-script.yaml") . | sha256sum }}
+        {{- if .Values.litellm.enabled }}
+        checksum/litellm-config: {{ include (print $.Template.BasePath "/litellm-config-script.yaml") . | sha256sum }}
+        {{- end }}
         {{- if .Values.allowedUsers }}
         checksum/user-waitlist: {{ include (print $.Template.BasePath "/user-waitlist-configmap.yaml") . | sha256sum }}
         {{- end }}
@@ -38,6 +42,12 @@ spec:
           configMap:
             name: keycloak-config-script
             defaultMode: 0755
+        {{- if .Values.litellm.enabled }}
+        - name: litellm-config-script
+          configMap:
+            name: litellm-config-script
+            defaultMode: 0755
+        {{- end }}
       initContainers:
       - name: keycloak-config
         imagePullPolicy: Always
@@ -50,6 +60,19 @@ spec:
         command:
           - sh
           - /scripts/keycloak-config.sh
+      {{- if .Values.litellm.enabled }}
+      - name: litellm-config
+        imagePullPolicy: Always
+        image: '{{.Values.image.repository}}:{{.Values.image.tag | default .Chart.AppVersion }}'
+        env:
+        {{- include "openhands.env" . | nindent 8 }}
+        volumeMounts:
+          - name: litellm-config-script
+            mountPath: /scripts
+        command:
+          - sh
+          - /scripts/litellm-config.sh
+      {{- end }}
       containers:
       - name: openhands
         imagePullPolicy: Always

charts/openhands/templates/litellm-config-script.yaml

@@ -0,0 +1,59 @@
+{{- if .Values.litellm.enabled }}
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: litellm-config-script
+data:
+  litellm-config.sh: |
+    #!/bin/sh
+    set -eu
+
+    echo "Setting up LiteLLM"
+
+    MAX_RETRIES=60
+    RETRY_INTERVAL=5
+
+    echo "LiteLLM Configuration Script"
+    echo "=============================="
+    echo "API URL: $LITE_LLM_API_URL"
+    echo "Team ID: $LITE_LLM_TEAM_ID"
+
+    echo ""
+    echo "Waiting for LiteLLM to be ready..."
+    retries=0
+    until curl --output /dev/null --silent --fail "$LITE_LLM_API_URL/health/liveness"; do
+        retries=$((retries + 1))
+        if [ $retries -ge $MAX_RETRIES ]; then
+            echo "ERROR: LiteLLM did not become ready after $((MAX_RETRIES * RETRY_INTERVAL)) seconds"
+            exit 1
+        fi
+        echo "LiteLLM not ready yet (attempt $retries/$MAX_RETRIES), waiting ${RETRY_INTERVAL}s..."
+        sleep $RETRY_INTERVAL
+    done
+    echo "LiteLLM is ready!"
+
+    echo ""
+    echo "Checking for existing team with ID: $LITE_LLM_TEAM_ID"
+    HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" -X GET "$LITE_LLM_API_URL/team/info?team_id=$LITE_LLM_TEAM_ID" \
+      -H "Authorization: Bearer $LITE_LLM_API_KEY" \
+      -H "Content-Type: application/json")
+
+    if [ "$HTTP_CODE" = "200" ]; then
+        echo "Team already exists with ID: $LITE_LLM_TEAM_ID"
+        exit 0
+    elif [ "$HTTP_CODE" = "404" ]; then
+        echo "Team does not exist, creating new team with ID: $LITE_LLM_TEAM_ID"
+        curl --fail -s -X POST "$LITE_LLM_API_URL/team/new" \
+          -H "Authorization: Bearer $LITE_LLM_API_KEY" \
+          -H "Content-Type: application/json" \
+          -d "{
+            \"team_id\": \"$LITE_LLM_TEAM_ID\",
+            \"team_alias\": \"$LITE_LLM_TEAM_ID\"
+          }"
+        echo ""
+        echo "Created team with ID: $LITE_LLM_TEAM_ID"
+    else
+        echo "ERROR: Unexpected response code: $HTTP_CODE"
+        exit 1
+    fi
+{{- end }}

charts/openhands/values.yaml

@@ -169,8 +169,9 @@ litellm:
   # NOTE: to set the LLM model, set the LITELLM_DEFAULT_MODEL variable in the env section above.
   # REQUIRED: Update to match the hostname set in the litellm-helm ingress section
   url: "https://llm-proxy.example.com"
-  # REQUIRED: Update this AFTER you initially install the chart and login to litellm to create the team.
-  # teamId: ""
+  # Team ID for LiteLLM. If the team ID doesn't exist, it will automatically be created.
+  # Set this to use an existing team.
+  teamId: "openhands"
   auth:
     existingSecret: lite-llm-api-key