CUGA LogoCUGA AGENT
Run

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 .
CapabilityFull imageSlim image
Core web/API agent, policies, action shortlistingIncludedIncluded
Knowledge embeddings and retrievalIncludedIncluded
Plain text and Markdown ingestionIncludedIncluded; Markdown uses plain-text chunking without Docling
PDF/Office/HTML/image ingestion through DoclingIncludedUnavailable; use the full image
Evolve memory, PII hooks, READIIncluded; requires configurationUnavailable

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:slim

Open 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

ComponentRole
CUGA backendFastAPI — chat streaming, knowledge, manage, config, auth
Web UIReact chat and Manage UI
Tool registryOpenAPI + MCP discovery (may run in-process or separately)
PersistencePostgres/pgvector or SQLite + Milvus (via Helm values)
Ingress / secretsTLS, 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:7860

Open 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.