agentlab

README

agentlab

The Giant Swarm agent platform on your laptop: one binary, one throwaway kind cluster, every chain proven end to end.

---

agentlab runs the Giant Swarm agent platform — muster as the MCP gateway, the Kubernetes MCP server, the kagent agents runtime and Giant Swarm's Backstage portal — on a kind cluster on your machine, so the whole platform can be tested and demoed without a management cluster.

Two kinds of client meet at one gateway. MCP clients such as Claude Code talk to muster directly; people use Backstage, the human frontend to the whole platform — servers, workflows, tools, agents, models — with their own token. The agents Backstage creates run on kagent and are MCP clients of muster too, calling tools as the person who invoked them.

The platform needs an identity provider, so the lab bundles its own Dex: users that exist nowhere but this cluster, RBAC driven by the groups claim, and the apiserver, muster and Backstage all trusting the same issuer.

What's in the box

• One Go binary. agentlab configure asks every option through an interactive form and writes agentlab.yaml; every manifest renders from embedded templates. No YAML to hand-edit, no scripts to source.
• The agent platform. The agent-platform chart every Giant Swarm management cluster runs, installed in its lab shape: muster behind an agentgateway TLS edge, the single OAuth enforcement point in front of an unauthenticated in-cluster mcp-kubernetes. Per-server sign-in, declared toolsets and a fake multi-cluster fleet are all exercised.
• Backstage, the human frontend. Giant Swarm's Backstage is how a person works the whole platform: browse and sign in to MCP servers, run workflows, explore tools, create agents and chat with them, manage models. Every call carries the signed-in user's own token, so the portal shows exactly what the platform grants that person.
• Agents. kagent runs the agents Backstage or agent-manager creates. They are MCP clients of muster like Claude Code is, forwarding the caller's token and bounded further by declared toolsets, so they see the same catalogue under the same rules.
• Models. An Anthropic default; extra model configs for OpenAI-compatible, Gemini and Ollama endpoints; managed models through model-manager fronting the model servers on the host — an Ollama, a Lemonade Server, an LM Studio.
• VMs. vm-manager, the platform's VM provisioner, as a pod of the KVM node (the chart's components.vm-manager) registered with muster as x_vm-manager_*: VMs with an instance metadata service, a vTPM and attestation, created by the person or an agent who asked.
• Swarmgeist. klaus-gateway, the fleet's Slack bridge, on the host against the lab's public gRPC edge and — with platform.klausGateway — as the meta chart's in-cluster component with its OBO link store in a Secret, proven across a pod loss. No Slack workspace, so no real sign-in: the store is proven through the gateway's own package.
• Observability. A minimal Prometheus plus mcp-prometheus, so PromQL questions about the lab go through MCP too.
• Identity you can reason about. Three throwaway users, a fixed group vocabulary, one issuer URL valid from the host, the node and every hostNetwork pod, and a lab CA you trust explicitly.
• Proofs, not hope. Headless *-test commands drive every chain — Dex login, muster, MCP tools, agents, toolsets, models, RBAC, Backstage — and fail loudly.

Getting started

Requirements: docker (or Podman >= 4's docker-compatible CLI) — nothing else; go >= 1.26 only to build from source. kind, Helm and the Kubernetes client are built into the binary: the cluster runs the Kubernetes of the embedded kind release's default node image, the platform installs through Helm 4's SDK, and every call to the apiserver goes through client-go. Give docker at least 4 CPUs and 6 GiB for the full lab; agentlab up checks before it touches anything (see Docker resources).

go install github.com/giantswarm/agentlab@latest   # or a release binary, or `go build -o agentlab .`

export ANTHROPIC_API_KEY=sk-ant-...   # optional: powers the agents and Backstage's AI chat
export GITHUB_TOKEN=github_pat_...    # optional: skill discovery/resolution call GitHub authenticated (5000/h, not 60/h)
agentlab configure --defaults         # drop --defaults for the interactive form
agentlab up                           # certs, kind cluster, Dex, RBAC, the platform — verified
agentlab open portal                  # the portal in your browser (the URL is printed too)
agentlab platform-test                # headless proof: Dex -> muster -> mcp-kubernetes -> apiserver

On a terminal, up ends by asking whether to trust the lab CA (one sudo prompt, so browsers get a green lock) and whether to open the portal — open portal is the command for later, and open agents opens the kagent UI.

Then point Claude Code at the platform:

agentlab trust                # if you said no above: one sudo prompt, `agentlab untrust` reverts it
export NODE_USE_SYSTEM_CA=1   # Node >= 22.15; older Node: NODE_EXTRA_CA_CERTS=$PWD/certs/ca.crt
claude mcp add --transport http muster https://muster.127.0.0.1.nip.io/mcp
# in Claude Code:  /mcp  ->  authenticate  ->  Dex login page  ->  done

The portal (https://backstage.127.0.0.1.nip.io) signs in the default users admin@lab.local, dev@lab.local and viewer@lab.local, password password. agentlab down deletes the cluster.

The full walkthrough, including what configure discovers about your machine, is in Getting started.

Documentation

Page	What it covers
Getting started	Requirements, docker CPU and memory, install, what configure discovers, the first up, connecting Claude Code
Command reference	Every agentlab command and flag, the environment variables, keeping the binary current
TLS	The lab CA, trust and untrust, Node and browsers, bringing your own certificate
The agent platform	muster + mcp-kubernetes: the request path, per-server sign-in, the fake fleet, toolsets, deviations from a real management cluster, the dev channel (a branch's dev builds), Agent Substrate and the platform Postgres from the chart
Agents	The kagent runtime, the default ModelConfig and the API key Secret
The migration rehearsal	A 3.x lab with the four fleet shapes upgraded in place to the 4.x line: the command sequence, the timings, what the migrate Job rewrote, refused and deleted, what an installation's cut-over does differently
Models	Extra model configs, model servers on the host, managed models through model-manager
vm-manager	The platform's VM provisioner as a pod of the node: the KVM devices, the image directory, the dev image, the golden PCR recipe, the proof
klaus-gateway	Swarmgeist as the meta chart's component: the values, the two lab Secrets, the OBO link store in a Secret across a pod loss, the dev image, what a lab without a Slack workspace cannot prove
Observability	Prometheus + mcp-prometheus, and Backstage's metrics views
Backstage	The human frontend: the muster plugin, agents and models in the portal, the agent create flow
Identity	Users and groups, the shared issuer, the Dex version, wiring another app, trustedPeers
Troubleshooting	The gotchas that cost time
Usage data	The one anonymous signal per command, and how to opt out
Development	Repository layout, building and testing, the hack journal

Development

make build     # go build -o agentlab .
make test      # go test ./...

The lab's end-to-end checks are its own *-test subcommands, not go test. Every hack and workaround, with its status, is recorded in HACKS.md; CLAUDE.md briefs coding agents on the repository. The layout is in Development.

License

Apache 2.0.

Documentation

Overview

agentlab is a local lab for the Giant Swarm agent platform: muster + the Kubernetes MCP (and optionally Backstage) on a throwaway kind cluster, with a bundled Dex as the OIDC provider — users that exist nowhere but this cluster.

The binary embeds every manifest as a template; `agentlab configure` asks for the configuration interactively and persists it to agentlab.yaml, and the lifecycle commands render + apply from there.