start-temps

Start a local Temps server

Boots the temps binary from source (cargo run --bin temps --package temps-cli -- serve ...) for quick local iteration, no debugger required. See CONTRIBUTING.md for the one-shot manual version of this; this skill adds port isolation across worktrees and a repeatable restart flow.

Prerequisites

• The database container from CONTRIBUTING.md ("Database" section) running and reachable, e.g.:

  docker run -d --name temps-db --restart unless-stopped \
    -p 127.0.0.1:5432:5432 \
    -v temps-db-data:/home/postgres/pgdata/data \
    -e POSTGRES_USER=temps -e POSTGRES_PASSWORD=temps -e POSTGRES_DB=temps \
    timescale/timescaledb-ha:pg18
  

  If your container has a different name, user, password, or port, set TEMPS_DEV_DB_CONTAINER / TEMPS_DEV_DB_URL_BASE before running step 0, or just edit the generated slot env file afterwards.

• bun install already run in <checkout>/web.

• Docker running, if you'll exercise features that shell out to it (container deploys, agent sandboxes, etc.) — see the Docker precheck below.

Port slots — read this first

If you keep multiple worktrees of this repo around (one per branch/PR), the naive approach — hardcode :8080 / :3000 and kill whatever's listening — means starting temps in worktree B kills the server another session was using in worktree A. This skill instead assigns each checkout a slot (0–29) and derives every port from it:

Thing	Port	Slot 0
Backend HTTP (--address)	8080 + slot*10	8080
Console (--console-address)	8081 + slot*10	8081
TLS (--tls-address)	8443 + slot*10	8443
Parked address (split mode only)	8085 + slot*10	8085
Web dev server (bun dev)	3000 + slot	3000
Database	temps_s<slot>	temps
TEMPS_DATA_DIR	<checkout>/crates/temps-cli/temps_data	same, per checkout

Rules:

• All listeners bind to 127.0.0.1 by default. LAN exposure is not part of this workflow; configure TLS and strong non-development credentials before opting into a non-loopback bind.
• The first checkout you run step 0 in claims slot 0, so the familiar http://localhost:3000 / :8080 belong to whichever worktree you started first (usually your primary clone).
• Every other checkout gets the lowest free slot ≥ 1, and keeps it — the claim is recorded atomically in ~/.temps-dev/slot-<N>.claim/ with its mode-0600 state in slot-<N>.env, so restarting temps in the same worktree always lands on the same ports. Existing claims remain reserved until explicitly released with step 7, even while their server is stopped.
• The kill step verifies the listening process's cwd is inside this checkout before killing it. If it isn't, stop and report rather than killing it — that process belongs to another session.
• The ranges never overlap (HTTP 8080–8370, parked 8085–8375, TLS 8443–8733, web 3000–3029). If you run other local services in the 8080–8730 or 3000–3029 range, expect port contention and free a slot (step 7) or shift the base ports in this skill.