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.
Docker images
Build from the cuga-agent repository root:
docker build -f Dockerfile.ubi -t cuga:full .
# Or build the smaller dependency set:
docker build -f Dockerfile.ubi.slim -t cuga:slim .| Capability | Full image | Slim image |
|---|---|---|
| Core web/API agent, policies, action shortlisting | Included | Included |
| Knowledge embeddings and retrieval | Included | Included |
| Plain text and Markdown ingestion | Included | Included; Markdown uses plain-text chunking without Docling |
| PDF/Office/HTML/image ingestion through Docling | Included | Unavailable; use the full image |
| Evolve memory, PII hooks, READI | Included; requires configuration | Unavailable |
The slim Dockerfile excludes the document-processing and Evolve dependency stacks. It preloads the remaining models and runs an offline verification during the build. Offline model assets do not remove the need to reach configured inference and tool endpoints.
Run either locally built image with an environment file containing your model configuration:
docker volume create cuga-data
docker run --rm --name cuga -p 7860:7860 \
--env-file .env \
-v cuga-data:/data/dbs \
cuga:slimOpen http://localhost:7860. The default container entry point starts Manage. Replace cuga:slim with cuga:full for document processing or configured memory. Set CUGA_DEMO_MODE=knowledge to start the knowledge demo instead. See LLM connections and bundled Memory setup.
Kubernetes with Helm
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
