Whale Lab

Docker, as a living world. Your own AI teaches it over MCP.

Live demo →  ·  Architecture  ·  Contributing

Whale Lab is an interactive Docker learning world. The whale is the host, Santa is dockerd, the reindeer crew are containerd and runc, and the shipping containers are containers. Switch the abstraction level and the same scene sheds the metaphor: at level 3 the shipping box dissolves into what it really is, a process on the host. A container is not a little VM.

The twist: there is no built-in tutor. You connect your own AI (Claude Code, Cursor, Claude Desktop, any MCP client) and it drives the world while it teaches: breaking things on purpose, tracing causes, rewinding, quizzing you.

• No accounts, no hosted AI, no server-side lab state.

• The browser owns a deterministic Docker simulation. A thin Cloudflare Worker only relays MCP calls to your tab.

• Seven levels of truth: Story → Objects → Engine → Process → Kernel → OCI → Ecosystem.

See it

Related MCP server: open-computer-use

Try it in 60 seconds

1. Open https://learndocker.hamdibouzidi.com

2. Press Connect your AI, then Test connection (Santa waves, proving the pipe works end to end).

3. Add the endpoint to your AI client. For Claude Code:

   claude mcp add --transport http docker-world https://learndocker.hamdibouzidi.com/mcp \
     --header "Authorization: Bearer <labId>.<secret>"

   The dialog shows your own key, plus configs for Cursor / VS Code, Claude Desktop and a paste-in prompt.

4. Ask: "Teach me why my container lost its data when I deleted it."

Your key is generated in your browser and never sent in a URL. See security.

What it teaches

A container is a process · image vs container · lifecycle · Dockerfile, layers and build cache · volumes and persistence · networks, DNS, isolation · port publishing · dockerd / containerd / shim / runc · PID 1 and signals · namespaces · cgroups and the OOM killer · registries · Compose and health cascades · debugging · OCI standards · the Kubernetes/cloud bridge.

Every one of 27 experiments carries a prediction whose stated answer is machine-verified against the simulator in tests, so the lab can't teach something its own world contradicts.

How it works

YOUR AI ──MCP (HTTP, Bearer labId.secret)──▶ Worker /mcp ──▶ Lab Durable Object ──WebSocket──▶ YOUR BROWSER
                                                                                               ├─ world engine (pure reducer, causal events, timeline)
 you click / type / turn dials ──────────────────────────────────────────────────────────────▶ ├─ concept graph (70 concepts), scenarios
                                                                                               └─ projection ─▶ Rive art + SVG relationships

• Semantic mutations only. The AI says run_container or set_resource_limit; it can never set pixels or frames. The renderer decides what it looks like.

• Event-sourced. Every change records what caused it, so you can rewind, step, branch and diff before/after.

• Rive does the art, an SVG layer draws data-driven relationships, and real DOM buttons keep it keyboard and screen-reader accessible.

Details: docs/ARCHITECTURE.md · Rive internals: rive/README.md

The 14 MCP tools

world_inspect · world_focus · world_mutate (34 typed actions) · world_run_scenario · world_set_view · world_set_overlay · world_compare · world_rewind · world_reset · world_connection_test · concept_inspect · concept_trace_relationship · lesson_check_understanding · lesson_get_progress

Tool descriptions double as the teacher's manual; the server also sends it in the MCP initialize instructions.

For now, the best setup is two tabs side by side: your AI in one, Whale Lab in the other. Leave full screen and use your browser’s split view, or move one tab into a second window. Chat with your AI while it changes the world here. The Ai-Agent (meta muse, grok bot...) option copies a complete setup prompt, including your endpoint and private lab key.

Run it locally

npm install
npm run dev:relay     # Worker + Durable Object on :8787 (set RELAY_PORT if taken)
npm run dev           # Vite on :5173, proxies /mcp and /ws to the relay

npm test              # 113 unit tests
npm run test:relay    # real workerd + official MCP SDK client
npm run test:e2e      # real Chrome, Rive, Worker (builds first)
npm run build         # typecheck + production bundle in dist/

To test the actual deployment (including edge routing, auth, browser relay, the in-app self-test and Santa's wave):

MCP_SMOKE_URL=https://learndocker.hamdibouzidi.com node tests/e2e/mcp-smoke.mjs

The teaching reference study documents the local Whisper transcription, frame analysis, and how the learning interface applies them.

Requires Node 22+. Rebuilding the Rive art (npm run build:rive) also needs the rive CLI; the compiled .riv is committed so you don't need it to run the app.

Deploy your own

One Worker serves the site, /mcp and /ws, with one SQLite-backed Durable Object per lab. Keep assets.run_worker_first for /mcp, /ws, and /health: SPA navigation fallback must not intercept these API routes.

npm run build && npx wrangler login && npx wrangler deploy

Add your domain under routes in wrangler.jsonc. Cloudflare Workers Builds also works from this repo with build command npm run build and deploy command npx wrangler deploy.

Security model

• The lab id is public routing; the secret is a 256-bit capability token sent only in the Authorization header (and in the browser socket's first message), never in a URL.

• The relay stores sha256(secret) only. The first browser to present a pair claims the lab.

• Strict CSP (wasm-unsafe-eval only for the Rive runtime), nosniff, no-referrer. axe-core WCAG 2 A/AA is clean on six views.

Report vulnerabilities per SECURITY.md.

Status and limitations

First public version. Be aware:

• It is a faithful simulation, not a Docker daemon. One sample Dockerfile, one Compose project, a fixed image catalogue. A live-Docker adapter is a natural fit (everything flows through one typed reducer) but is not built.

• Six deck slots; extra containers collapse into an overflow chip.

• The relay has no rate limiting yet.

• Rive performance was measured in headless software GL only; not yet on real phones or GPUs.

See the roadmap for what's next.

Contributing

Issues and PRs are welcome. Start with CONTRIBUTING.md; please follow the Code of Conduct.

License

MIT © Hamdi Bouzidi