Self-host on Kubernetes
Deploy CUGA on kind, minikube, or a cloud cluster with Helm.
Self-host on Kubernetes
Architecture: A deployed CUGA stack runs the Clients (Web UI), Orchestrator (backend + LangGraph), Capability (tools, knowledge, sandbox), Persistence (vector DB + config DB), and External (LLM APIs, secrets) layers together. See How CUGA works — Deployment.
The cuga-agent repo ships a Helm chart and helper scripts for running CUGA outside your laptop.
What gets deployed
| Component | Role |
|---|---|
| CUGA backend | FastAPI — chat streaming, knowledge, manage, config, auth |
| Web UI | React chat and Manage UI |
| Tool registry | OpenAPI + MCP discovery (may run in-process or separately) |
| Persistence | Postgres/pgvector or SQLite + Milvus (via Helm values) |
| Ingress / secrets | TLS, API keys as Kubernetes secrets |
Prerequisites
Helm 3 and a cluster (kind, minikube, Docker Desktop Kubernetes, or GKE / EKS / AKS).
Local cluster (kind / minikube)
From the cuga-agent repository root:
cp deployment/.env.example deployment/.env
# Set GROQ_API_KEY or OPENAI_API_KEY
./deployment/deploy-local.sh
kubectl port-forward svc/cuga 7860:7860Open http://localhost:7860.
Cloud cluster
Build and push the image to your registry, then install the chart under deployment/helm/ with API keys as Kubernetes secrets. Full walkthrough: deployment/README.md.
Cluster-specific values (ingress, TLS, image pull secrets) vary by environment — use the Helm README as the source of truth.
Related
- Manage and publish — draft config in the UI, then deploy the published version
- Configure — storage —
storage.mode = "prod"keeps published configs on restart