Local Development Setup

This guide walks you through setting up a local development environment for testing Omnia.

Prerequisites

Install the required tools:

• Go 1.25+: Download Go
• Docker: Install Docker
• kubectl: Install kubectl
• kind: Install kind
• Helm: Install Helm

Create a Local Cluster

Create a kind cluster with port forwarding:

cat <<EOF | kind create cluster --config=-
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 30080
    hostPort: 8080
    protocol: TCP
EOF

Verify the cluster is running:

kubectl cluster-info

Deploy Redis (Optional)

If you need session persistence, deploy Redis:

kubectl create namespace redis
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install redis bitnami/redis -n redis \
  --set auth.enabled=false \
  --set architecture=standalone

Build and Load Images

Build the operator and agent images:

make docker-build IMG=omnia-operator:dev

docker build -t omnia-agent:dev -f Dockerfile.agent .

kind load docker-image omnia-operator:dev
kind load docker-image omnia-agent:dev

Install the Operator

Deploy using Helm with local images:

helm install omnia charts/omnia -n omnia-system --create-namespace \
  --set image.repository=omnia-operator \
  --set image.tag=dev \
  --set image.pullPolicy=Never

Verify Installation

Check the operator is running:

kubectl get pods -n omnia-system
kubectl logs -n omnia-system -l app.kubernetes.io/name=omnia -f

Deploy Test Resources

Apply sample manifests:

kubectl apply -f config/samples/

Using Demo Mode for Testing

For local development without LLM costs, use the demo or echo handler modes:

apiVersion: omnia.altairalabs.ai/v1alpha1
kind: AgentRuntime
metadata:
  name: test-agent
spec:
  promptPackRef:
    name: test-prompts
  facade:
    type: websocket
    handler: demo  # Use 'echo' for simple connectivity testing
  session:
    type: memory

The demo handler provides:

• Streaming responses that simulate real LLM output
• Simulated tool calls for password and weather queries
• No API key required

This is useful for:

• UI/frontend development
• Integration testing
• Demos and screenshots
• Validating WebSocket connectivity

Connect to an Agent

Forward the agent port:

kubectl port-forward svc/sample-agent 8080:8080

Test with websocat:

websocat ws://localhost:8080?agent=sample-agent

Troubleshooting

Operator not starting

Check logs:

kubectl logs -n omnia-system deployment/omnia-operator

Agent pods failing

Check events:

kubectl describe agentruntime <name>
kubectl describe pod -l app.kubernetes.io/instance=<name>

WebSocket connection refused

Ensure the service is ready:

kubectl get endpoints <agent-name>