Configuration Reference

Environment variables, resource limits, probe configuration, and DNS setup for the CompassAI API and Frontend.

This page documents all configuration for the CompassAI API and Frontend components. Configuration is primarily driven by environment variables set in Kubernetes deployment manifests.

TypeDB Connection

The CompassAI API connects to TypeDB (FFO) using the TypeDB gRPC driver.

In Kubernetes, TypeDB runs as a ClusterIP service in the f3iai namespace. The API pod resolves it via internal DNS.

LLM Endpoint

The chat interface sends LLM inference to the Frontier llm-router, a separate Kubernetes service (self-hosted and commercial frontier models). The settings below cover a direct Ollama endpoint.

The endpoint must point to an Ollama instance with the specified model loaded. The API calls /api/chat with stream: false and a 120-second timeout.

PostgreSQL

CompassAI PostgreSQL connection settings. MCP server registration is not stored in PostgreSQL. Operators register MCP servers as forwards in Remuda.

MCP Server URLs

Each MCP server has a dedicated environment variable for its endpoint URL. These are used when constructing tool calls.

Registration

Operators register MCP servers as forwards in Remuda. Agents discover and invoke tools through the Remuda endpoint (OIDC / Bearer auth), instead of attaching to each backend server.

DNS Configuration

CompassAI relies on internal Kubernetes DNS to resolve service names. For environments using Tailscale with CoreDNS, ensure that:

• CoreDNS is configured to forward .svc.cluster.local queries to the cluster DNS
• Tailscale MagicDNS does not intercept queries for cluster-internal domains
• The API pod’s /etc/resolv.conf lists the cluster DNS server first

If MCP servers are on different networks (e.g., accessible via Tailscale but not cluster DNS), set their URLs to use Tailscale hostnames or IP addresses directly in the environment variables.

Resource Limits

API

resources:
  requests:
    memory: "512Mi"
    cpu: "250m"
  limits:
    memory: "2Gi"
    cpu: "1"

The API requires up to 2Gi of memory due to:

• TypeDB driver connection overhead
• LLM response buffering (large tool call results)
• Concurrent request handling

Frontend

resources:
  requests:
    memory: "128Mi"
    cpu: "100m"
  limits:
    memory: "512Mi"
    cpu: "500m"

The frontend is a static Next.js build served by Nginx, so resource requirements are minimal.

Health Probes

API

livenessProbe:
  httpGet:
    path: /health
    port: 8000
  initialDelaySeconds: 60
  periodSeconds: 30
  timeoutSeconds: 5
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /health
    port: 8000
  initialDelaySeconds: 15
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

The liveness probe has a longer initial delay (60s) to account for TypeDB driver initialization and MCP server discovery at startup. The readiness probe starts checking after 15 seconds so the pod can begin receiving traffic as soon as it is ready.

Frontend

The frontend uses a simple TCP socket probe on port 80 (Nginx), as it serves static content and has no application-level health endpoint.

Example Deployment Environment Block

env:
  - name: TYPEDB_HOST
    value: "typedb.f3iai.svc.cluster.local"
  - name: TYPEDB_PORT
    value: "1729"
  - name: DATABASE_NAME
    value: "ffo"
  - name: TYPEDB_USER
    valueFrom:
      secretKeyRef:
        name: compass-secrets
        key: typedb-user
  - name: TYPEDB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: compass-secrets
        key: typedb-password
  - name: LLM_ENDPOINT
    value: "http://ollama.f3iai.svc.cluster.local:11434"
  - name: LLM_MODEL
    value: "llama4:scout"
  - name: POSTGRES_HOST
    value: "postgres.f3iai.svc.cluster.local"
  - name: POSTGRES_PASSWORD
    valueFrom:
      secretKeyRef:
        name: compass-secrets
        key: postgres-password
  - name: FFO_MCP_URL
    value: "http://ffo-mcp.f3iai.svc.cluster.local:50060"
  - name: KEYCLOAK_MCP_URL
    value: "http://keycloak-mcp.f3iai.svc.cluster.local:50060"

Sensitive values (passwords, credentials) should always be sourced from Kubernetes Secrets rather than hardcoded in the deployment manifest.