Following the tutorials on Kubernetes

The quick start and most of the tutorials are written against the Docker Compose install: they edit files under ~/.vectorstep/, run docker compose exec, and read tokens out of ~/.vectorstep/.env. The VectorStep side is identical on Kubernetes — same YAML, same API calls, same auth model — only how you reach the ports and where the files live change. This page is the translation table.

If you haven’t installed yet, start with the Kubernetes deploy tutorial.

Reaching the services

The Services are ClusterIP, so use a port-forward (or your own Ingress) where a tutorial says http://localhost:8000 or http://localhost:18780:

kubectl -n vectorstep port-forward svc/vectorstep 8000:8000 &
kubectl -n vectorstep port-forward svc/vectorstep-gateway 18780:18780 &

After that, every localhost:8000 / localhost:18780 URL in the docs — and the UI at http://localhost:8000/ui/ — works unchanged.

Tokens

Where a tutorial reads a token from ~/.vectorstep/.env or docker compose exec, read it from the Secret instead:

# VectorStep (login to the UI, /reload, the write API)
kubectl -n vectorstep get secret vectorstep-secrets -o jsonpath='{.data.VECTORSTEP_ADMIN_TOKEN}' | base64 -d
# Triggering a pipeline with POST /webhook
kubectl -n vectorstep get secret vectorstep-secrets -o jsonpath='{.data.VECTORSTEP_WEBHOOK_TOKEN}' | base64 -d
# Gateway admin token — authoring agents and skills, the Gateway's /reload
kubectl -n vectorstep get secret vectorstep-gateway-secrets -o jsonpath='{.data.VECTORSTEP_GATEWAY_ADMIN_TOKEN}' | base64 -d

Files: pipelines, steps, agents, skills

This is the big difference. On Docker you edit files in ~/.vectorstep/; on Kubernetes they live on a PersistentVolume inside the pod (/data/pipelines, /data/steps, /data/agents, /data/skills), so you don’t edit them in place — you deliver them. Everywhere a tutorial says “save this as ~/.vectorstep/pipelines/foo.yaml” (or agents/…, steps/…, skills/…), do one of these instead:

Tutorial says	On Kubernetes
Save foo.yaml to ~/.vectorstep/pipelines/ (or steps/)	POST /pipelines (or /steps) with the YAML and the admin token — or copy the file in. See Write API.
Save an agent’s agent.yaml + soul.md to ~/.vectorstep/agents/<name>/	POST /agents on the Gateway with the Gateway admin token. See Creating agents.
Create a skill under ~/.vectorstep/skills/	POST /skills on the Gateway. See Skills.
“Reload” / curl -X POST …/reload	POST /reload through the port-forward, with the matching admin token. The service and the Gateway reload separately.
docker compose restart after a config change	kubectl -n vectorstep rollout restart deployment/vectorstep (or …-gateway)
Edit vectorstep.yaml / the Gateway’s config.yaml	Edit the ConfigMap (kubectl -n vectorstep edit configmap vectorstep-config), then restart as above
docker compose logs -f	kubectl -n vectorstep logs -f deploy/vectorstep (and deploy/vectorstep-gateway)
docker compose exec gateway …	kubectl -n vectorstep exec deploy/vectorstep-gateway -- …

For a team, don’t hand-run those API calls: put the files in git and ship them from CI — Changing config on Kubernetes has three routes (API push, kubectl copy, GitOps ConfigMap) with templates.

Using the MCP servers against a cluster

The MCP servers run on your own machine (Claude Code, Claude Desktop) and talk to the services over HTTP, so point them at the port-forwards above and give them the admin tokens from the Secrets:

claude mcp add vectorstep-service \
  --env VECTORSTEP_BASE_URL=http://127.0.0.1:8000 \
  --env VECTORSTEP_TOKEN=<VectorStep admin token> \
  -- uvx vectorstep-service-mcp

claude mcp add vectorstep-gateway \
  --env GATEWAY_BASE_URL=http://127.0.0.1:18780 \
  --env GATEWAY_OPERATOR_TOKEN=<Gateway admin token> \
  -- uvx vectorstep-gateway-mcp

Keep the port-forwards running while you use them. The Gateway’s admin token can rewrite agent definitions — see Reaching the Gateway from outside the cluster before exposing it any more widely than a port-forward.

Two things that differ in practice

• A model API key. The tutorials’ agents call a real LLM. The deploy tutorial accepts any placeholder key to bring the services up, but a run that reaches an agent needs a real ANTHROPIC_API_KEY in vectorstep-gateway-secrets (or another provider configured in the Gateway ConfigMap).
• Pin your image tags. The shipped manifests use :latest with imagePullPolicy: Always, so any pod restart can pick up a newer release. The service and Gateway must run matching versions — pin both to the same tag (ghcr.io/bantex01/vectorstep:0.1.12, no v prefix) once you’re past evaluation.