VibeOps

Kagent + Ollama on Docker Desktop (Windows): End‑to‑End Commands & Rationale

0. Assumptions

  • OS: Windows with Docker Desktop installed and Kubernetes enabled.
  • Goal: run Kagent on Docker Desktop’s Kubernetes, and connect it to a local LLM served by Ollama (llama3.2:1b), with no external API keys.

1. Install and verify Docker Desktop Kubernetes

Command

powershell# Check Kubernetes node
kubectl get nodes

Why
Ensures the built‑in single‑node cluster (docker-desktop / desktop-control-plane) is up and ready before installing anything on top.

2. Install Kagent via Helm (conceptual)

(Exact Helm commands may vary by chart version; the important part is that you end up with a kagent namespace and controller/engine/UI pods.)

Conceptual commands

# Create namespace (if not created by Helm)
kubectl create namespace kagent

# Install CRDs and core Kagent chart (pseudo‑commands)
helm install kagent-crds <crds-chart> -n kagent
helm install kagent <kagent-chart> -n kagent

Why
Installs Kagent’s CRDs (including ModelConfig and Agent) and the core components (controller, engine, UI) into a dedicated namespace.

3. Fix ImagePullBackOff for Kagent core images

When pods like kagent-controller, kagent-ui, or kagent-tools are stuck in ImagePullBackOff with “unexpected EOF”, manually pull the image using Docker and then delete the pod.

Example command (controller)

docker pull cr.kagent.dev/kagent-dev/kagent/controller:0.7.7
kubectl delete pod -l app.kubernetes.io/component=controller -n kagent
kubectl get pods -n kagent -w

Example command (UI)

powershelldocker pull cr.kagent.dev/kagent-dev/kagent/ui:0.7.7
kubectl delete pod -l app.kubernetes.io/component=ui -n kagent
kubectl get pods -n kagent -w

Why
On Docker Desktop, transient network issues can break image pulls. Pulling images manually populates the local cache, and deleting pods lets Kubernetes recreate them using cached layers, avoiding repeated failures.

4. Expose the Kagent UI

Command

kubectl port-forward svc/kagent-ui -n kagent 8080:8080

Why
Forwards the Kagent UI service to http://localhost:8080, enabling access to the dashboard from the browser on the host.

5. Spin up Ollama in Docker

Command

docker run -d --name ollama `
  -p 11434:11434 `
  -v ollama:/root/.ollama `
  ollama/ollama

Why
Starts Ollama as a container, persisting model data in a named volume and exposing the API on port 11434. This will become the “local LLM server” that Kagent eventually uses.

6. Download a small model in Ollama

Command

docker exec -it ollama ollama pull llama3.2:1b

Why
Fetches a very small but usable LLM, llama3.2:1b, into the Ollama instance, minimizing RAM/CPU footprint while still being useful for testing.

7. Verify Ollama endpoint from the host

Command

curl.exe http://localhost:11434

Expected content:

textOllama is running

Why
Confirms that the Ollama server is reachable and responding on the configured port.

8. Create a temporary debug pod in kagent

Commands

docker pull busybox:latest

kubectl delete pod tmp-shell -n kagent --ignore-not-found

kubectl run tmp-shell -n kagent `
  --image=busybox:latest `
  --restart=Never `
  -it -- sh

Why
Provides a minimal shell inside the cluster, in the same namespace as Kagent, to test connectivity to services (such as Ollama) from the Kubernetes side.

9. Verify Ollama from inside Kubernetes

Commands (inside tmp-shell)

text# List models
wget -O- http://ollama:11434/api/tags

# Test a simple generation
wget -O- --header="Content-Type: application/json" \
  --post-data='{"model":"llama3.2:1b","prompt":"Say hi"}' \
  http://ollama:11434/api/generate

Why

  • Confirms that a Kubernetes Service named ollama exists and resolves.
  • Verifies that the model llama3.2:1b is visible and can generate text when accessed from inside the cluster, not just from the host.

10. Inspect the default ModelConfig

Command

kubectl get modelconfig -n kagent
kubectl get modelconfig default-model-config -n kagent -o yaml

Why
Shows how Kagent currently expects to reach its model (provider type, model name, host), and reveals the existing configuration that still referenced llama.cpp and host.docker.internal.

11. Edit ModelConfig to point to Ollama + llama3.2:1b

Command

kubectl edit modelconfig default-model-config -n kagent

Edit the spec section to:

textspec:
  apiKeySecret: ""
  apiKeySecretKey: ""
  model: llama3.2:1b
  ollama:
    host: ollama:11434
  provider: Ollama

Why
Aligns Kagent’s ModelConfig with the actual Ollama service accessible from the cluster:

  • provider remains Ollama
  • model name matches exactly the model exposed by Ollama
  • host is the Kubernetes DNS name and port of the Ollama service (ollama:11434).

12. Restart the Kagent engine component

Command

kubectl delete pod -l app.kubernetes.io/component=engine -n kagent
kubectl get pods -n kagent -w

Why
Forces the engine pod to restart and reload the updated model configuration, ensuring it uses the new Ollama endpoint and model.

13. Create a first agent in Kagent UI

UI actions

  1. Go to http://localhost:8080 (Kagent UI).
  2. Create a new agent (agent1) of type “Declarative”.
  3. Select default-model-config as ModelConfigRef.
  4. Add a simple system prompt (“You’re a helpful agent…”) and save.

Why
Defines a concrete agent resource in Kubernetes that uses the newly configured model, so we can validate both scheduling (pods/images) and LLM connectivity.

14. Fix ImagePullBackOff for the agent runtime

When agent1 pod shows ImagePullBackOff for cr.kagent.dev/kagent-dev/kagent/app:0.7.7:

Command

docker pull cr.kagent.dev/kagent-dev/kagent/app:0.7.7
kubectl delete pod agent1-<pod-hash> -n kagent
kubectl get pods -n kagent -w

Why
Same pattern as with the controller/UI: manually pulling the image ensures it is available to the node, and deleting the pod triggers a recreate that uses the cached image, allowing the agent pod to reach Running.

15. Test the agent in Kagent UI

UI actions

  1. Confirm in the UI that agent1 shows as Ready.
  2. Open agent1, send a message like “who are you?” or “hello”.

Why
This step checks the end‑to‑end chain:

  • Kagent agent → engine → ModelConfig → Ollama service (ollama:11434) → model llama3.2:1b
  • and verifies that responses flow back into the UI.

If an error such as Ollama_chatException - /11434/api/chat appears, it indicates a mismatch between the adapter’s expected Ollama API path (/api/chat) and the tested path (/api/generate), meaning the infrastructure is correct but the framework’s Ollama integration needs version alignment or a different backend (e.g., a vLLM OpenAI‑compatible server).

Leave a comment