# Start Temps Cluster

Start (or restart) a local multi-node Temps cluster using Docker-in-Docker, one...

- Repository: https://github.com/gotempsh/temps (887 stars)
- Category: Testing
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add gotempsh/temps --skill start-temps-cluster -g -a claude-code -y`
Codex: `npx skills add gotempsh/temps --skill start-temps-cluster -g -a codex -y`
Cursor: `npx skills add gotempsh/temps --skill start-temps-cluster -g -a cursor -y`
Gemini CLI: `npx skills add gotempsh/temps --skill start-temps-cluster -g -a gemini-cli -y`

## Description

Start (or restart) a local multi-node Temps cluster using Docker-in-Docker, one control plane + 3 worker nodes, each a privileged DinD container running its own dockerd + `temps agent`, wired with the real multi-host overlay (VXLAN, compute_cidr allocation) via `tools/dev-cluster/` in whichever checkout/worktree you run it from. Invoke when the user says "start the temps cluster", "spin up a multi-node dev cluster", "test this with multiple workers", "bring up worker nodes locally", "docker in dind cluster", or wants to verify cross-node behavior (node targeting, cluster DNS, overlay networking, node join/mTLS) that a single-node `start-temps` server cannot exercise. Distinct from `start-temps` (single-node, native binary, port-slot based) and `start-temps-ee` (single-node EE binary), this is the only path that actually has more than one node.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Start a local multi-node Temps cluster (Docker-in-Docker)

Wraps `tools/dev-cluster/`, a docker-compose harness that runs a real Temps
control plane plus 3 worker nodes, each a privileged DinD container, with the
actual overlay network (VXLAN, `compute_cidr` allocation, cluster DNS) wired
up exactly as it would be on real hardware. Use this whenever a fix or feature
needs *more than one node* to prove anything, single-node `start-temps`
cannot exercise cross-node scheduling, the overlay, or cluster DNS at all.

## Topology

```
┌──── temps-underlay (10.42.0.0/24, docker bridge, the "VPC") ────┐
│                                                                  │
│  postgres            10.42.0.5   (TimescaleDB pg18, internal)   │
│  control-plane        10.42.0.10  DinD + `temps serve`           │
│    host ports 80 → 80, 443 → 443 (NOT 8080, see Gotcha below)  │
│                                                                  │
│  worker-1  10.42.0.21   worker-2  10.42.0.22   worker-3 10.42.0.23│
│    each: privileged DinD + `temps agent`, own dockerd            │
└──────────────────────────────────────────────────────────────────┘

Allocator carves /24s from 10.202.0.0/16 (default for new clusters, ADR 056),
one per worker:
  worker-1 → 10.202.0.0/24
  worker-2 → 10.202.1.0/24
  worker-3 → 10.202.2.0/24

Cross-node container traffic flows over a VXLAN tunnel pinned to the
underlay IPs above. Within-node traffic uses the unchanged
`temps-app-network` Docker bridge (same as single-node temps).
```

The temps source tree is bind-mounted read-write at `/workspace` inside every
DinD container, and `cargo build --bin temps` runs *inside Linux*, no
cross-compiling from macOS. **The cluster builds from whichever checkout you
run `./dev-cluster` in.** `cd` into the right worktree first if you're testing
a fix that isn't on the checkout's current branch.

## Prerequisites

The rest: https://github.com/gotempsh/temps/blob/HEAD/.agents/skills/start-temps-cluster/SKILL.md