Helm + Vertex AI

Deploy OpenAgentic on Kubernetes with the in-tree Helm chart, backed by Google Vertex AI (Gemini).

Deploy OpenAgentic v1.0.0 on a Kubernetes cluster with the in-tree Helm chart and use Google Vertex AI (Gemini) for chat and image generation. Because inference runs in Vertex AI, the cluster footprint stays light; the datastores (PostgreSQL with pgvector, Redis, and the Milvus standalone trio) run inside the release.

Note: The interactive setup wizard does not yet drive the Helm path. Use either the ./install.sh --helm one-liner or run Helm by hand, as shown below. For a single-node install, see Docker Compose. For the broader Kubernetes notes, see Kubernetes.

Before you begin

You need the following:

No in-cluster GPU is required. Vertex AI serves chat and image models from the cloud. Embeddings are served by the in-cluster Ollama (nomic-embed-text), which runs CPU-only.

What the release deploys

The chart is self-contained and runs the platform plus its datastores in the openagentic namespace. All services run as single-replica Deployments.

Important: Milvus is the in-cluster vector backend and the API requires it at boot. The API connects to Milvus on startup and exits if the connection cannot be established after its retry budget. The chart deploys the Milvus standalone trio (milvus, etcd, minio) by default (milvus.enabled: true), so this is handled for you. Set milvus.enabled: false only if you run the API in pgvector-only mode (MILVUS_ENABLED=false).

Install

The packaged chart is hosted at https://install.openagentics.io/openagentic-1.0.0.tgz — helm installs from it directly, nothing to clone.

Cloud MCPs and Vertex AI authenticate with static service-account credentials. There is no IdP-based on-behalf-of (OBO) token exchange in the self-hosted build.

1. Inspect the chart’s configurable values and start a values overlay from them.

   helm show values https://install.openagentics.io/openagentic-1.0.0.tgz > values-k8s.yaml
   # Edit values-k8s.yaml: set ai.google.vertex.projectId, region, and the other
   # placeholders. Do not commit this file — it holds secrets.

2. Install from the OCI chart, passing your Vertex AI service-account key at apply time so it is never written into the values file.

   # Path to your Vertex AI service-account JSON key (kept out of git)
   KEY=/path/to/vertex-sa-key.json
   
   helm upgrade --install openagentic https://install.openagentics.io/openagentic-1.0.0.tgz \
     --namespace openagentic --create-namespace \
     -f values-k8s.yaml \
     --set-file secrets.gcpServiceAccountJson="$KEY" \
     --wait --timeout 10m

Alternatively, the one-line installer runs the same Helm command for you (using your values overlay when present, otherwise the chart defaults), and waits for the rollout:

curl -sSL https://install.openagentics.io | bash -s -- --helm

Note: secrets.gcpServiceAccountJson is defined in the values-k8s.yaml overlay. The base chart templates seed only the local Ollama provider (default) or AWS Bedrock (bootstrapProvider.enabled: true). To make Vertex AI the active provider, configure it in the overlay as shown in the next section.

Vertex AI configuration

The values-k8s.yaml overlay selects Vertex AI as the LLM provider and sets the model. The keys that matter:

# Provider selection and default model
env:
  DEFAULT_LLM_PROVIDER: "vertex-ai"
  DEFAULT_MODEL: "gemini-2.0-flash-001"
  GCP_PROJECT_ID: "<your-gcp-project>"
  GCP_REGION: "us-central1"

# Vertex AI provider wiring
ai:
  google:
    vertex:
      enabled: true
      priority: 1
      projectId: "<your-gcp-project>"
      location: "us-central1"
      model: "gemini-2.0-flash-001"

Embeddings are served by the in-cluster Ollama, separate from the chat provider:

embedding:
  enabled: true
  provider: "ollama"
  model: "nomic-embed-text"
  dimensions: 768
  ollama:
    model: "nomic-embed-text"

The service-account key is supplied at install time with --set-file secrets.gcpServiceAccountJson=.... Keep it out of the values file and out of git.

Note: Providers are pluggable. The bootstrap step seeds one provider on first boot; you add or change providers afterward from the admin console. You can switch chat to AWS Bedrock, OpenAI, Azure OpenAI, Anthropic, or local Ollama without redeploying.

First boot is slow

The first boot takes roughly 5 to 7 minutes. The API runs prisma db push, waits on mcp-proxy, initializes the Milvus collections, and indexes the MCP tools into pgvector before it reports healthy. Watch the pods rather than assuming a hang:

kubectl get pods -n openagentic -o wide -w
kubectl logs -n openagentic deployment/api -f

Caution: The API runs a single replica (replicas: 1). Do not scale it above one. Two API pods bounce provider:reload pub/sub messages between each other, triggering a model-rediscovery loop in which neither pod becomes ready.

Access the UI

The chart does not enable an Ingress by default. Reach the UI with a port-forward:

kubectl port-forward -n openagentic svc/ui 8080:80

Then open http://localhost:8080. The default first-boot admin account is [email protected] with the password set by secrets.adminPassword (default changeme-on-first-login; change it in your overlay).

To expose the UI over HTTPS instead, set ingress.enabled: true, ingress.host, and ingress.tlsSecret (the name of a pre-existing kubernetes.io/tls secret in the release namespace). When Ingress is enabled, the chart adds your public origin to the API’s ALLOWED_ORIGINS automatically.

MCP servers

The chart deploys and registers the bundled MCP servers. The default enabled set is web, admin, kubernetes, and prometheus (the mcps.enabled string also lists a legacy knowledge token, but there is no knowledge server — it was removed upstream, so the token is inert). The Kubernetes MCP authenticates with the mcp-proxy pod ServiceAccount and a read-only ClusterRole granted by templates/mcp-proxy-rbac.yaml; the Prometheus MCP queries the in-cluster prometheus service.

Each server spawns, initializes, and registers its tools (for example, the Kubernetes MCP exposes k8s_list_pods, k8s_get_pod, k8s_get_pod_logs, and k8s_list_namespaces), and the tools are indexed for semantic discovery. Chat selects tools through the three-layer cascade (intent routing, then pgvector semantic search, then a hard ceiling of 15 tools per turn) and invokes them through mcp-proxy.

Toggle servers through the mcpProxy.env block. Each MCP has an OpenAgentic_<NAME>_MCP_DISABLED flag; set the ones you want to "false". Cloud MCPs read their credentials from the same block:

Model routing and governance are configured in the admin console after first boot. See Configuration.

Upgrade and uninstall

To upgrade, rebuild and push your images (or rebuild locally if the cluster shares your Docker store, for example OrbStack or k3s), then re-run the same install command:

helm upgrade --install openagentic ./helm/openagentic \
  --namespace openagentic \
  -f helm/openagentic/values-k8s.yaml \
  --set-file secrets.gcpServiceAccountJson="$KEY" \
  --wait --timeout 10m

To uninstall:

helm uninstall openagentic -n openagentic
kubectl delete namespace openagentic

What’s next

• Configuration — provider, model routing, and governance settings.
• MCP servers — the bundled servers and their credential models.
• Deploy with Docker Compose — single-node install.