Isolated sandboxes, not plain Agents. gVisor SandboxAgents on Viper — the page I send people is /agents/. Handbook below is still the full lab map.

k8s-viper is a lab-grade single-node Kubernetes box. Bootstrap once; everything after that is git → Argo CD.

Imperative install only for k3s + Argo + root app. Platform services are GitOps.

bootstrap.sh  →  dockerized k3s (k3s-viper) + Argo CD + root Application
                      ↓
              argocd/apps/*  (GitOps, auto-sync)
                      ↓
   ingress | vault | ESO | headlamp | argocd-access
   gateway-api | agentgateway | langfuse
   substrate | kagent | kagent-ai | desktop
                      ↓
   Traefik :80/:443  +  NodePorts 30080 / 30443 / 30200 / 30100 / 30300 / 30500
                      ↓
   agentgateway-proxy :30100
        ├─ /v1 · /openai  → OpenAI (Vault)     gpt-5.5 / gpt-5-mini
        ├─ /spark         → Spark vLLM :8000   Qwen/Qwen3.6-35B-A3B-FP8
        ├─ /mcp           → SandboxAgent MCPs (LAN Streamable HTTP)
        ├─ /desktop/      → noVNC desktop viewer
        └─ /desktop-api/  → computer-use HTTP API
                      ↓
   kagent UI :30500  → default model gpt-5.5 via gateway /v1
   Agent Substrate (ate-system) → gVisor workers (kagent-default)
                      ↓
   OTEL collector → Langfuse (configured)

Typical lab node values. Set your InternalIP above if different.

Fixed NodePorts for LAN access without port-forward. Keep these private — no public exposure without TLS and real identity.

Auth commands

# Talk to the cluster (kubectl is not on the host PATH)
docker exec k3s-viper kubectl get nodes -o wide

# Argo CD admin password (user: admin)
docker exec k3s-viper kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath='{.data.password}' | base64 -d; echo

# Headlamp SA token (paste into login form)
docker exec k3s-viper kubectl -n headlamp create token headlamp --duration=12h

Argo UI uses a self-signed cert — accept the browser warning. Vault UI needs init + unseal first.

Argo CD Applications. Watch with docker exec k3s-viper kubectl -n argocd get applications.

Map hosts to the node IP in /etc/hosts, then hit Traefik on :80.

172.16.10.135  whoami.viper.local headlamp.viper.local langfuse.viper.local

curl -H 'Host: whoami.viper.local' http://172.16.10.135/

agentgateway fronts OpenAI (/v1, /openai) with credentials from Vault, and DGX Spark Qwen (/spark) at 172.16.10.173:8000 with no auth. Models: gpt-5.5, gpt-5-mini, Qwen/Qwen3.6-35B-A3B-FP8. Langfuse (+ ClickHouse) receives OTEL traces. Full runbook: docs/agentgateway-langfuse.md.

export GW=http://172.16.10.135:30100

curl -sS "$GW/v1/chat/completions" -H 'content-type: application/json' \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"hi"}],"max_completion_tokens":64}'

# small model
curl -sS "$GW/v1/chat/completions" -H 'content-type: application/json' \
  -d '{"model":"gpt-5-mini","messages":[{"role":"user","content":"hi"}],"max_completion_tokens":64}'

# DGX Spark (vLLM)
curl -sS "$GW/spark/v1/chat/completions" -H 'content-type: application/json' \
  -d '{"model":"Qwen/Qwen3.6-35B-A3B-FP8","messages":[{"role":"user","content":"hi"}],"max_tokens":64}'

Run on the target Linux node with outbound HTTPS.

git clone https://github.com/sebbycorp/k8s-viper.git
cd k8s-viper
sudo ./scripts/bootstrap.sh

Optional environment

sudo REPO_URL=https://github.com/YOU/k8s-viper.git \
     REPO_REVISION=main \
     ARGOCD_VERSION=v3.5.0 \
     ./scripts/bootstrap.sh

# Existing cluster:
sudo INSTALL_K3S_SKIP=1 ./scripts/bootstrap.sh

1. Edit manifests or Helm values on a branch.
2. Open a PR — CI runs scripts/validate.sh (no cluster credentials).
3. Merge to main.
4. Argo CD auto-syncs (prune + self-heal on platform apps).

./scripts/validate.sh
docker exec k3s-viper kubectl -n argocd get applications

# Build this handbook locally
cd site && hugo --minify

After Argo syncs Vault and External Secrets, init and unseal once, then wire Kubernetes auth for ESO. Full runbook: docs/vault-eso-setup.md.

# Unseal (lab helper)
~/.config/k8s-viper/vault-unseal.sh

# UI after unseal → http://172.16.10.135:30200/

• v1 lab assumes private LAN access to NodePorts and Traefik.
• Headlamp binds cluster-admin for full lab visibility — tighten for multi-user.
• Leave config.unsafeUseServiceAccountToken off unless behind a real auth proxy.
• Argo CD serves a self-signed TLS cert on the NodePort.
• Vault tlsDisable: true in chart values — fine for lab, not production.
• No OIDC / SSO in v1.