Tilt Up Principles (Always Active) These apply whenever working with Tiltfiles, Tilt errors, or dev environment bootstrap: Fix the Tiltfile, Not the Symptoms Fix the source config directly - Tiltfile, Dockerfile, k8s manifest, or helm values Never add shell workarounds - no wrapper scripts, no || true , no try/except pass Never hard-code ports, paths, hostnames, image tags, or container names that should be dynamic Never add fallbacks that mask the real error - if a resource fails, the failure must be visible Never add sleep/retry loops for flaky dependencies - fix dependency ordering via resource_deps() or k8s_resource(deps=) Never add polling for readiness that Tilt already handles - use k8s_resource(readiness_probe=) or probe configs Express Dependencies Declaratively Port conflicts: fix the port allocation source, don't pick a different port Resource ordering: use resource_deps() , not sequential startup scripts Env vars: use silo.toml or gen-env output, not inline defaults Image availability: use image_deps or deps , not sleep-until-ready Tilt Live-Reloads After editing a Tiltfile, Tilt picks up changes automatically. Never restart tilt up for: Tiltfile edits Source code changes Kubernetes manifest updates Restart only for: Tilt version upgrades, port/host config changes, crashes, cluster context switches. Workflow (When Explicitly Starting Tilt) Step 1: Assess Current State Check if tilt is already running: SESSION = $( basename $( git rev-parse --show-toplevel 2
/dev/null ) || basename $PWD ) tmux list-windows -t " $SESSION " -F '#{window_name}' 2
/dev/null | grep -q "^tilt$" If running, check health via tilt get uiresources -o json and skip to Step 3. Check for required env files ( .localnet.env , .env.local , silo.toml ): If silo.toml exists, use silo up path If gen-env script exists, run it first If neither, check project README for bootstrap instructions Check for k3d cluster or Docker prerequisites. Step 2: Start Tilt in tmux Follow the tmux skill patterns: SESSION = $( basename $( git rev-parse --show-toplevel 2
/dev/null ) || basename $PWD ) if ! tmux has-session -t " $SESSION " 2
/dev/null ; then tmux new-session -d -s " $SESSION " -n tilt tmux send-keys -t " $SESSION :tilt" 'tilt up' Enter elif ! tmux list-windows -t " $SESSION " -F '#{window_name}' | grep -q "^tilt$" ; then tmux new-window -t " $SESSION " -n tilt tmux send-keys -t " $SESSION :tilt" 'tilt up' Enter else echo "Tilt window already exists in session: $SESSION " fi For silo projects: silo up instead of tilt up . Step 3: Monitor Bootstrap Poll for convergence: Wait 10s for initial resource registration Poll every 15s, up to 20 iterations: tilt get uiresources -o json | jq -r '.items[] | select(.status.runtimeStatus == "error" or .status.updateStatus == "error" or .status.updateStatus == "pending") | "(.metadata.name): runtime=(.status.runtimeStatus) update=(.status.updateStatus)"' Track resources: pending -> in_progress -> ok Success: all resources reach runtime=ok, update=ok (or not_applicable ) If resources stabilize in error , proceed to Step 4 Step 4: Diagnose and Fix Errors For each resource in error state: Read logs: tilt logs
--since 2m Read the Tiltfile and relevant k8s manifests Identify root cause in the config (not the running process) Apply fix following the Principles above Tilt live-reloads - re-poll status to verify After 3 fix iterations on the same resource without progress: Report the error with full logs Identify whether it's a Tiltfile bug, upstream dependency, or infrastructure problem Do not silently skip or disable the resource Step 5: Report
Tilt Status:
Resources: X/Y ok Session: tmux $SESSION:tilt
Errors (if any)
: —