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:

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.

Modes

• Default (monolith) — one temps serve process (--role=all, the single-binary control plane). This is what you get with a bare /start-temps. Use Procedure below.
• split — the two-process topology: a standalone temps proxy (Pingora data plane) plus a separate temps serve --role=console (Axum control plane). Use this to verify the proxy keeps serving while the console restarts. Trigger with "start temps split" / "/start-temps split". Use references/split-mode.md instead of the default Procedure below.

When to invoke

• "start temps" / "launch temps" / "bring up the server"
• "restart temps" / "kill and restart"
• "start temps split" / "test the proxy/console split" → references/split-mode.md
• After backend changes that need the server reloaded
• Anywhere you want a local control plane up for the checkout you're in

Procedure

0. Allocate this checkout's slot (ports, database name, data dir)

Run this from inside the checkout you are working in (the worktree, not necessarily your primary clone). It is idempotent — rerunning it returns the same slot. Run it verbatim; it prints the port map and writes ~/.temps-dev/slot-<N>.env, which every later step sources. The file is created with mode 0600, and every value is shell-escaped before writing so checkout paths and overrides cannot become commands when the file is sourced.

set -u
umask 077
mkdir -p "$HOME/.temps-dev"

# Which checkout is this working in?
REPO=$(git -C "$PWD" rev-parse --show-toplevel 2>/dev/null || pwd)
if [ -f "$REPO/Cargo.toml" ] && [ -d "$REPO/crates/temps-cli" ]; then TEMPS_ROOT="$REPO"
else echo "ERROR: no temps Rust workspace under $REPO — cd into a temps checkout first"; exit 1; fi

DB_CONTAINER="${TEMPS_DEV_DB_CONTAINER:-temps-db}"
DB_URL_BASE="${TEMPS_DEV_DB_URL_BASE:-postgres://temps:temps@localhost:5432}"

SLOT=""
TEMPS_ROOT_ID=$(printf '%s' "$TEMPS_ROOT" | shasum -a 256 | awk '{print $1}')
# 1. Reuse an existing claim for this checkout.
for f in "$HOME"/.temps-dev/slot-*.env; do
  [ -e "$f" ] || continue
  if grep -qxF "TEMPS_ROOT_ID=$TEMPS_ROOT_ID" "$f"; then
    SLOT=${f##*/slot-}; SLOT=${SLOT%.env}; break
  fi
done
# 2. Otherwise atomically claim the lowest slot (>= 0) that is unclaimed and
#    not listening. `mkdir` is the exclusion primitive: two concurrent agents
#    cannot both create the same claim directory.
#    Claims remain reserved until step 7 releases them. A stopped server or
#    temporarily unavailable checkout is not proof its migration DB is stale.
if [ -z "$SLOT" ]; then
  for i in $(seq 0 29); do
    f="$HOME/.temps-dev/slot-$i.env"
    claim="$HOME/.temps-dev/slot-$i.claim"
    { [ -e "$f" ] || [ -e "$claim" ]; } && continue
    busy=0
    for p in $((3000+i)) $((8080+i*10)) $((8081+i*10)) $((8443+i*10)); do
      lsof -nP -iTCP:$p -sTCP:LISTEN >/dev/null 2>&1 && busy=1
    done
    [ "$busy" -eq 1 ] && continue
    mkdir "$claim" 2>/dev/null || continue
    printf '%s\n' "$TEMPS_ROOT_ID" > "$claim/root-id"
    chmod 600 "$claim/root-id"
    SLOT=$i; CLAIM_DIR="$claim"; break
  done
fi
[ -z "$SLOT" ] && { echo "ERROR: no free slot in 0..29 — stop some servers first"; exit 1; }

if [ "$SLOT" = 0 ]; then
  DB_NAME=temps
else
  DB_NAME=temps_s$SLOT
fi
DATA_DIR="$TEMPS_ROOT/crates/temps-cli/temps_data"   # gitignored in every checkout

SLOT_FILE="$HOME/.temps-dev/slot-$SLOT.env"
{
  echo "# temps dev slot $SLOT — written by the start-temps skill. Delete to release."
  printf 'TEMPS_SLOT=%q\n' "$SLOT"
  printf 'TEMPS_ROOT_ID=%q\n' "$TEMPS_ROOT_ID"
  printf 'TEMPS_ROOT=%q\n' "$TEMPS_ROOT"
  printf 'TEMPS_HTTP_PORT=%q\n' "$((8080+SLOT*10))"
  printf 'TEMPS_CONSOLE_PORT=%q\n' "$((8081+SLOT*10))"
  printf 'TEMPS_TLS_PORT=%q\n' "$((8443+SLOT*10))"
  printf 'TEMPS_PARKED_PORT=%q\n' "$((8085+SLOT*10))"
  printf 'TEMPS_WEB_PORT=%q\n' "$((3000+SLOT))"
  printf 'TEMPS_DB_NAME=%q\n' "$DB_NAME"
  printf 'TEMPS_DB_CONTAINER=%q\n' "$DB_CONTAINER"
  printf 'TEMPS_DATABASE_URL=%q\n' "$DB_URL_BASE/$DB_NAME"
  printf 'TEMPS_DATA_DIR=%q\n' "$DATA_DIR"
  printf 'TEMPS_ADMIN_EMAIL=%q\n' 'dev@temps.sh'
  printf 'TEMPS_ADMIN_PASSWORD_FILE=%q\n' "$HOME/.temps-dev/slot-$SLOT.admin-password"
  printf 'TEMPS_SERVE_LOG=%q\n' "/tmp/temps-serve-s$SLOT.log"
  printf 'TEMPS_CONSOLE_LOG=%q\n' "/tmp/temps-console-s$SLOT.log"
  printf 'TEMPS_PROXY_LOG=%q\n' "/tmp/temps-proxy-s$SLOT.log"
  printf 'TEMPS_WEB_LOG=%q\n' "/tmp/temps-web-s$SLOT.log"
} > "$SLOT_FILE"
chmod 600 "$SLOT_FILE"
echo
echo "slot $SLOT -> api http://localhost:$((8080+SLOT*10))  web http://localhost:$((3000+SLOT))  db $DB_NAME"
echo "env file: $SLOT_FILE (mode 0600; contains the database URL — do not print it)"

Substitute the printed slot number for <N> in every block below, and report the two URLs at the end — in a non-zero slot they are not the familiar :3000 / :8080.

0b. Provision this slot's database and data dir

Each non-zero slot runs against its own database (temps_s<N>) and its own TEMPS_DATA_DIR, so a branch's migrations, encrypted rows, CAS blobs and sandboxes can't corrupt another branch's. Slot 0 uses the plain temps database from CONTRIBUTING.md.

Every slot starts from a fresh, empty database: the branch's own migrations build the schema on first serve, and the admin user is created non-interactively from TEMPS_ADMIN_EMAIL + TEMPS_ADMIN_PASSWORD_FILE (no prompt to feed via stdin).

source "$HOME/.temps-dev/slot-<N>.env"
PSQL="docker exec -i $TEMPS_DB_CONTAINER psql -U temps"

if $PSQL -tAc "SELECT 1 FROM pg_database WHERE datname='$TEMPS_DB_NAME'" | grep -q 1; then
  echo "database $TEMPS_DB_NAME already exists"
else
  $PSQL -c "CREATE DATABASE \"$TEMPS_DB_NAME\"" && \
    echo "created empty $TEMPS_DB_NAME — migrations run on first serve"
fi

mkdir -p "$TEMPS_DATA_DIR"
if [ ! -f "$TEMPS_ADMIN_PASSWORD_FILE" ]; then
  { openssl rand -base64 24 | tr -d '\n'; printf '!Aa1\n'; } > "$TEMPS_ADMIN_PASSWORD_FILE"
  chmod 600 "$TEMPS_ADMIN_PASSWORD_FILE"
fi
echo "login: $TEMPS_ADMIN_EMAIL / ***"
echo "password file: $TEMPS_ADMIN_PASSWORD_FILE (mode 0600; do not print its contents)"

Report the email and password-file path, but never the password — a fresh slot DB has no other account. (Password rules: ≥8 chars with upper, lower, digit and a special character — validate_password_complexity rejects anything weaker and serve will fail to start.)

Docker precheck

If Docker is down, some plugin/sandbox initialization can fail silently while the HTTP port still binds — the server looks up, but pieces that shell out to Docker won't work and the reason can be buried in the log. Check first:

docker info >/dev/null 2>&1 && echo "docker ok" || \
  echo "DOCKER DOWN — start it before testing anything that provisions containers"

1. Kill only this slot's processes

Ownership-checked: it refuses to kill anything whose cwd is outside this checkout. If it refuses, do not work around it with kill -9 — another session owns that process. Re-run step 0 after deleting this slot's env file to get a different slot instead.

source "$HOME/.temps-dev/slot-<N>.env"

for spec in "$TEMPS_HTTP_PORT backend" "$TEMPS_CONSOLE_PORT console" "$TEMPS_WEB_PORT web"; do
  set -- $spec; PORT=$1; LABEL=$2
  for PID in $(lsof -nP -iTCP:$PORT -sTCP:LISTEN -t 2>/dev/null); do
    CWD=$(lsof -a -p "$PID" -d cwd -Fn 2>/dev/null | sed -n 's/^n//p' | head -1)
    case "$CWD" in
      "$TEMPS_ROOT"|"$TEMPS_ROOT"/*) ;;
      *) echo "REFUSING to kill pid $PID on :$PORT ($LABEL) — cwd '$CWD' is outside $TEMPS_ROOT"; continue ;;
    esac
    kill "$PID" 2>/dev/null; sleep 2
    kill -0 "$PID" 2>/dev/null && { kill -9 "$PID"; sleep 1; }
  done
  lsof -nP -iTCP:$PORT -sTCP:LISTEN 2>/dev/null || echo "port $PORT free ($LABEL)"
done

Never use a bare pkill -f temps / pkill -f cargo — it takes down every other checkout's server too.

2. Launch the server

--profile fast gives release-grade runtime speed with much faster link times than --release (see Notes). TEMPS_ADMIN_EMAIL + TEMPS_ADMIN_PASSWORD_FILE make the first-run admin bootstrap non-interactive — without them a fresh database wedges a detached process in an infinite email/password re-prompt loop. Docker Desktop on macOS does not expose the Linux forwarding plane where Temps installs sandbox egress rules, so this trusted local-development launcher explicitly opts into unfiltered sandbox networking. Never copy that override into a production deployment.

source "$HOME/.temps-dev/slot-<N>.env"

cd "$TEMPS_ROOT/crates/temps-cli" && \
  RUST_BACKTRACE=full \
  TEMPS_LOG_FORMAT=full \
  TEMPS_DATA_DIR="$TEMPS_DATA_DIR" \
  TEMPS_ADMIN_EMAIL="$TEMPS_ADMIN_EMAIL" \
  TEMPS_ADMIN_PASSWORD_FILE="$TEMPS_ADMIN_PASSWORD_FILE" \
  TEMPS_DISABLE_HTTPS_REDIRECT=true \
  TEMPS_TELEMETRY=0 \
  TEMPS_ALLOW_INSECURE_SANDBOX_NETWORKING=1 \
  nohup cargo run --profile fast --bin temps --package temps-cli -- \
    serve \
    --disable-https-redirect \
    --database-url="$TEMPS_DATABASE_URL" \
    --address=127.0.0.1:$TEMPS_HTTP_PORT \
    --tls-address=127.0.0.1:$TEMPS_TLS_PORT \
    --console-address=127.0.0.1:$TEMPS_CONSOLE_PORT \
    --log-level=debug \
    > "$TEMPS_SERVE_LOG" 2>&1 & disown
echo "serve launched (slot $TEMPS_SLOT) -> $TEMPS_SERVE_LOG"

(If you're testing multi-node worker join locally, add --private-address=<your LAN IP> — workers use it to reach this control plane's services.)

Run this detached (nohup ... & disown, not a backgrounded foreground job) so the process survives past this command finishing.