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:
PROJECT=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" || basename "$PWD")
zmx list --short 2>/dev/null | grep -q "^${PROJECT}-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 zmx
Follow the zmx skill patterns:
PROJECT=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" || basename "$PWD")
SESSION="${PROJECT}-tilt"
if zmx list --short 2>/dev/null | grep -q "^${SESSION}$"; then
echo "Tilt session already exists: $SESSION"
else
zmx run "$SESSION" 'tilt up'
echo "Started tilt in zmx 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. Include docker-compose container health
(
composeResourceInfo.healthStatus) — an Up (unhealthy) compose container
keeps runtimeStatus=ok and is otherwise invisible, so bootstrap can look
"done" while canton/splice/postgres are silently failing their HEALTHCHECK:tilt get uiresources -o json | jq -r '.items[] | select(.status.runtimeStatus == "error" or .status.updateStatus == "error" or .status.updateStatus == "pending" or .status.composeResourceInfo.healthStatus == "unhealthy") | "\(.metadata.name): runtime=\(.status.runtimeStatus) update=\(.status.updateStatus) compose=\(.status.composeResourceInfo.healthStatus // "-")"'
- Track resources:
pending -> in_progress -> ok
- Success: all resources reach
runtime=ok, update=ok (or not_applicable)
AND no docker-compose resource is composeResourceInfo.healthStatus == "unhealthy"
- If resources stabilize in
error, OR a compose resource stays unhealthy,
proceed to Step 4. For an unhealthy compose probe, read the real cause with
docker inspect <compose-project>-<svc> --format '{{json .State.Health}}' —
often the mounted healthcheck script calls a CLI the image lacks (the service
is up; fix the probe script, don't disable the check)
Step 4: Diagnose and Fix Errors
For each resource in error state:
- Read logs:
tilt logs <resource> --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: <healthy|degraded|errored>
**Resources**: X/Y ok
**Session**: zmx $SESSION
### Errors (if any)
- <resource>: <root cause> — <what was fixed or what remains>
1---
2name: tiltup
3description: Use when starting tilt, debugging Tiltfile errors, or bootstrapping a dev environment. Starts Tilt in zmx, monitors bootstrap to healthy state, fixes Tiltfile bugs without hard-coding or fallbacks.
4metadata:
5 source: https://skillmd.com/skills/alleneubank/tiltup
6---
7
8# Tilt Up
9
10## Principles (Always Active)
11
12These apply whenever working with Tiltfiles, Tilt errors, or dev environment bootstrap:
13
14### Fix the Tiltfile, Not the Symptoms
15
16- **Fix the source config directly** - Tiltfile, Dockerfile, k8s manifest, or helm values
17- **Never add shell workarounds** - no wrapper scripts, no `|| true`, no `try/except pass`
18- **Never hard-code** ports, paths, hostnames, image tags, or container names that should be dynamic
19- **Never add fallbacks** that mask the real error - if a resource fails, the failure must be visible
20- **Never add sleep/retry loops** for flaky dependencies - fix dependency ordering via `resource_deps()` or `k8s_resource(deps=)`
21- **Never add polling** for readiness that Tilt already handles - use `k8s_resource(readiness_probe=)` or probe configs
22
23### Express Dependencies Declaratively
24
25- Port conflicts: fix the port allocation source, don't pick a different port
26- Resource ordering: use `resource_deps()`, not sequential startup scripts
27- Env vars: use `silo.toml` or gen-env output, not inline defaults
28- Image availability: use `image_deps` or `deps`, not sleep-until-ready
29
30### Tilt Live-Reloads
31
32After editing a Tiltfile, Tilt picks up changes automatically. **Never restart `tilt up`** for:
33- Tiltfile edits
34- Source code changes
35- Kubernetes manifest updates
36
37Restart only for: Tilt version upgrades, port/host config changes, crashes, cluster context switches.
38
39## Workflow (When Explicitly Starting Tilt)
40
41### Step 1: Assess Current State
42
431. Check if tilt is already running:
44 ```bash
45 PROJECT=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" || basename "$PWD")
46 zmx list --short 2>/dev/null | grep -q "^${PROJECT}-tilt$"
47 ```
48 If running, check health via `tilt get uiresources -o json` and skip to Step 3.
49
502. Check for required env files (`.localnet.env`, `.env.local`, `silo.toml`):
51 - If `silo.toml` exists, use `silo up` path
52 - If gen-env script exists, run it first
53 - If neither, check project README for bootstrap instructions
54
553. Check for k3d cluster or Docker prerequisites.
56
57### Step 2: Start Tilt in zmx
58
59Follow the `zmx` skill patterns:
60```bash
61PROJECT=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" || basename "$PWD")
62SESSION="${PROJECT}-tilt"
63
64if zmx list --short 2>/dev/null | grep -q "^${SESSION}$"; then
65 echo "Tilt session already exists: $SESSION"
66else
67 zmx run "$SESSION" 'tilt up'
68 echo "Started tilt in zmx session: $SESSION"
69fi
70```
71
72For silo projects: `silo up` instead of `tilt up`.
73
74### Step 3: Monitor Bootstrap
75
76Poll for convergence:
771. Wait 10s for initial resource registration
782. Poll every 15s, up to 20 iterations. Include docker-compose container health
79 (`composeResourceInfo.healthStatus`) — an `Up (unhealthy)` compose container
80 keeps `runtimeStatus=ok` and is otherwise invisible, so bootstrap can look
81 "done" while canton/splice/postgres are silently failing their HEALTHCHECK:
82 ```bash
83 tilt get uiresources -o json | jq -r '.items[] | select(.status.runtimeStatus == "error" or .status.updateStatus == "error" or .status.updateStatus == "pending" or .status.composeResourceInfo.healthStatus == "unhealthy") | "\(.metadata.name): runtime=\(.status.runtimeStatus) update=\(.status.updateStatus) compose=\(.status.composeResourceInfo.healthStatus // "-")"'
84 ```
853. Track resources: `pending` -> `in_progress` -> `ok`
864. Success: all resources reach `runtime=ok, update=ok` (or `not_applicable`)
87 AND no docker-compose resource is `composeResourceInfo.healthStatus == "unhealthy"`
885. If resources stabilize in `error`, OR a compose resource stays `unhealthy`,
89 proceed to Step 4. For an unhealthy compose probe, read the real cause with
90 `docker inspect <compose-project>-<svc> --format '{{json .State.Health}}'` —
91 often the mounted healthcheck script calls a CLI the image lacks (the service
92 is up; fix the probe script, don't disable the check)
93
94### Step 4: Diagnose and Fix Errors
95
96For each resource in error state:
971. Read logs: `tilt logs <resource> --since 2m`
982. Read the Tiltfile and relevant k8s manifests
993. Identify root cause in the config (not the running process)
1004. Apply fix following the Principles above
1015. Tilt live-reloads - re-poll status to verify
102
103After 3 fix iterations on the same resource without progress:
104- Report the error with full logs
105- Identify whether it's a Tiltfile bug, upstream dependency, or infrastructure problem
106- Do not silently skip or disable the resource
107
108### Step 5: Report
109
110```
111## Tilt Status: <healthy|degraded|errored>
112
113**Resources**: X/Y ok
114**Session**: zmx $SESSION
115
116### Errors (if any)
117- <resource>: <root cause> — <what was fixed or what remains>
118```