What is Tilt and how does it work?
Tilt is a development tool that runs on your workstation and keeps a running environment in sync with your source code. It watches files, builds container images, applies Kubernetes manifests, and reports status and logs for each resource in a single web UI. It can also run Docker Compose projects and plain local commands, so one Tiltfile can describe a mixed setup.
The core loop is short. You save a file. Tilt sees the change and works out which resources depend on it. It rebuilds the affected image, or syncs the changed files into the running container. It then redeploys and updates that resource's status in the UI. Because Tilt tracks dependencies per resource, a change to one service does not restart the others.
You configure all of this in a Tiltfile, written in Starlark, a Python-like language. Since the Tiltfile is a program and not a static YAML file, you can use loops, conditionals, and functions to generate resources. That helps once you manage more than a handful of services.
This article uses one pattern throughout. You run the service you are editing with live code sync. You run its dependencies, such as other services, databases, and queues, as stable, prebuilt images. The edited service gets fast feedback, and the rest of the stack stays predictable and cheap to keep running.
┌──────────┐ file save ┌──────────────────────────────┐
│ Editor │ ──────────▶ │ Tilt │
└──────────┘ │ watch → build → deploy → UI │
└──────┬────────────────┬──────┘
image build │ │ file sync
▼ ▼
┌─────────────────── local Kubernetes cluster ──────────────┐
│ ┌────────────────────┐ ┌──────────────────────────┐ │
│ │ orders-svc (edited)│ │ prebuilt dependencies │ │
│ │ live-synced code │──▶│ users-svc, postgres, │ │
│ └────────────────────┘ │ redis (pinned images) │ │
│ └──────────────────────────┘ │
└───────────────────────────────────────────────────────────┘
┌──────────┐ file save ┌──────────────────────────────┐
│ Editor │ ──────────▶ │ Tilt │
└──────────┘ │ watch → build → deploy → UI │
└──────┬────────────────┬──────┘
│ │ file sync
▼ │ (live update)
┌─────────────────┐ │
│ image build │ │
│ (when required) │ │
└────────┬────────┘ │
│ new image │
┌─── local Kubernetes cluster ──┼────────────────┼────────────────────┐
│ ▼ ▼ │
│ ┌──────────────────────────────────┐ │
│ │ service you are editing │ │
│ │ live-synced, fast feedback │ │
│ └───────────┬──────────────────────┘ │
│ │ calls │
│ ┌──────────────────────┼──────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ other service │ │ database │ │ message queue │ │
│ │ prebuilt image │ │ prebuilt image │ │ prebuilt image │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Tilt watches the editor's file saves, rebuilds the image or live-syncs changed files into the one service being edited, while its dependencies run in the local cluster as stable, prebuilt images.
Tilt vs Docker Compose vs kubectl apply: which should your team use?
Most teams already have a way to run their stack locally. The question is whether that way still holds up once production runs on Kubernetes and a single feature touches three or four services.
There are three common approaches. Docker Compose with bind mounts mounts your source into a container that runs a file-watching dev server, so a save shows up almost immediately. A manual loop of build, push and kubectl apply uses your real manifests but makes you rebuild an image for every change. Tilt watches your files and runs the build and deploy steps for you. It can also sync changed files into running pods instead of rebuilding them.
| Criterion | Compose + bind mounts | Manual build + kubectl apply |
Tilt |
|---|---|---|---|
| Manifest fidelity to production | Low: a separate Compose file drifts from your Kubernetes manifests | High: same manifests | High: same manifests or Helm charts |
| Resource cost | Lowest: no cluster | Cluster overhead | Cluster overhead plus Tilt itself |
| Edit-to-running-code speed | Fast | Slow: full image rebuild every time | Fast with live_update |
| Multi-service visibility | docker compose logs, mixed together |
Several kubectl terminals |
One UI with per-resource status and logs |
| Setup effort | Low | Low at first, high to maintain | Moderate: write a Tiltfile and run a local cluster |
Fidelity is the main reason to adopt Tilt. Ingress rules, ConfigMaps, probes and service DNS behave locally the way they do in production, and Compose cannot reproduce them.
Adopt Tilt when both of these are true:
- Your services already deploy to Kubernetes.
- Your team regularly runs several dependent services together.
If you aren't on Kubernetes, or you work on one or two services, Compose is simpler and good enough. Tilt's extra machinery only pays for itself once a growing service graph makes manifest drift and terminal juggling expensive.
How do you choose and connect a local Kubernetes cluster for Tilt?
Tilt needs a cluster to deploy to, and on a laptop that usually means one of four options. They differ mainly in how a freshly built image reaches the cluster, which sets the floor on every rebuild.
| Cluster | How images get in | Notes |
|---|---|---|
| kind | Local registry, or loading into nodes | Nodes run as containers; quick to recreate |
| k3d | Local registry, or importing into nodes | Runs k3s in containers; lightweight |
| minikube | Image load, its Docker daemon, or a registry | Many drivers; behavior depends on the driver |
| Docker Desktop | Shares the Docker image store | No push step; one cluster per machine |
Loading an image copies the full image into each node on every build. A local registry transfers only changed layers, which helps as images grow. Tilt detects a registry advertised through the cluster's local-registry-hosting ConfigMap and pushes there automatically.
Tilt only deploys to contexts it recognizes as local, such as kind-*, k3d-*, minikube and docker-desktop. Any other context requires an explicit allow_k8s_contexts call. Tilt applies manifests and deletes resources on tilt down, so a stale kubeconfig pointing at staging could wreck a shared environment. The guard makes that a deliberate choice.
Expect more overhead than Compose. You are running a control plane, and on macOS and Windows a VM as well. With many services, RAM and CPU often become the limit, and no Tiltfile change recovers them.
Platform differences belong in your onboarding docs:
- macOS: memory is capped by the Docker VM settings.
- Linux: runs natively, with no VM.
- Windows: keep source inside the WSL filesystem, not under
/mnt/c, or file watching and sync slow down.
Registry hostnames such as localhost:5000 also resolve differently from inside nodes than from the host on each platform.
# Tiltfile (Starlark): connect Tilt to a local cluster safely
# Tilt already trusts kind-*, k3d-*, minikube and docker-desktop.
# Only add contexts here that you know are local, such as a
# renamed local cluster. Never add staging or prod.
allow_k8s_contexts('dev-laptop')
# Show which cluster this session targets so mistakes are visible.
print('Deploying to context: ' + k8s_context())
# Leave default_registry unset if the cluster advertises a registry
# through the local-registry-hosting ConfigMap. Tilt detects it and
# pushes only changed layers. Set it only for clusters that lack it:
# default_registry('localhost:5000')
docker_build(
'example/orders-api',
'./services/orders-api',
live_update=[
# Sync source into the running container instead of rebuilding.
# On Windows, keep this path inside the WSL filesystem, not /mnt/c.
sync('./services/orders-api/src', '/app/src'),
],
)
k8s_yaml('services/orders-api/k8s.yaml')
k8s_resource('orders-api', port_forwards=8080)
A minimal Tiltfile that trusts one extra local context through allow_k8s_contexts, prints the active context, relies on the cluster-advertised local registry, and uses live_update sync to avoid full image rebuilds.
Writing a Tiltfile: one live-updated service plus prebuilt dependencies
Start with the service you are actively changing. A docker_build call names the image reference and the build context, and optionally a non-default Dockerfile path. Tilt watches that context, rebuilds on change, and rewrites any matching image reference it finds in the YAML it deploys. Next, k8s_yaml hands Tilt the manifests. You can pass a file or list of files, or the output of the built-in helm() or kustomize() functions. That lets you reuse the same charts or overlays you ship rather than maintaining a parallel dev copy. Finally, k8s_resource takes the workload name and gives it a readable name and port_forwards, so the service is reachable on localhost without a Service of type NodePort.
Dependencies go in as their own resources: a Postgres StatefulSet, a RabbitMQ or Redis Deployment, and the upstream API your service calls. Point them at stock images or a pinned prebuilt tag from your registry, and give them no docker_build. Tilt then only applies them and never rebuilds them, so editing your service never touches them.
Add resource_deps on your service listing those dependency resources, so it deploys only once they are ready. Tilt treats a pod as ready based on Kubernetes readiness, so give each dependency a real readiness probe, such as pg_isready or a health endpoint. Without one, "ready" just means "container started."
Ordering is a convenience, not resilience. In a real cluster, dependencies restart, reschedule and fail independently. If your service only works because Tilt started it last, you have hidden a race condition. Keep retries with backoff, and fail readiness, not the process, when a dependency is unavailable.
# Tiltfile (Starlark, Python-like syntax)
# The service under active development: Tilt watches ./services/orders,
# rebuilds on change, and swaps this image ref into the deployed YAML.
docker_build(
'registry.example.com/orders',
'./services/orders',
dockerfile='./services/orders/Dockerfile.dev',
)
# Reuse the same manifests you ship: a kustomize overlay for the app,
# a Helm chart for the upstream API pinned to a prebuilt tag.
k8s_yaml(kustomize('./deploy/overlays/dev'))
k8s_yaml(helm(
'./charts/inventory-api',
name='inventory-api',
set=['image.tag=1.4.2'], # prebuilt tag, no docker_build, never rebuilt
))
# Stock images for infra. These manifests should define readiness probes
# (e.g. pg_isready for Postgres) so 'ready' means accepting connections.
k8s_yaml(['./deploy/dev/postgres.yaml', './deploy/dev/rabbitmq.yaml'])
k8s_resource('postgres', labels=['deps'], port_forwards='5432:5432')
k8s_resource('rabbitmq', labels=['deps'], port_forwards='15672:15672')
k8s_resource('inventory-api', labels=['deps'])
# Deploy orders only after its dependencies report ready.
# This is a startup convenience: orders must still retry with backoff
# and fail readiness (not crash) when a dependency goes away later.
k8s_resource(
'orders',
new_name='orders-svc',
port_forwards='8080:8080',
resource_deps=['postgres', 'rabbitmq', 'inventory-api'],
labels=['app'],
)
A minimal Tiltfile that live-builds one service, deploys Postgres, RabbitMQ and an upstream API from stock or pinned images without rebuilding them, and uses resource_deps plus readiness probes to order startup.
How do you set up hot reload with Tilt live_update?
live_update replaces "rebuild the image, push it, roll the pod" with "patch the running container in place." You declare it on the docker_build for your service as an ordered list of steps, and Tilt runs them whenever a watched file changes.
Sync and run steps
A sync step maps a local path to a path inside the container, so an edited file is copied over within seconds and an interpreter or framework file watcher picks it up. A run step executes a command in the container after syncing. Give it a trigger limited to your lockfile (package-lock.json, poetry.lock, go.sum) so dependencies reinstall only when they actually change, not on every save.
When Tilt rebuilds anyway
Tilt does a full image build when a changed file is not covered by any sync path, or when it matches a fall_back_on entry. List the Dockerfile, base image pins and system package manifests there. Patching those in place produces a container no clean build would ever reproduce.
Compiled languages
Don't compile inside the container. Build the binary on your host with a local_resource that targets the container's OS and architecture. Sync only the output binary, then restart the process. The restart_process extension wraps the entrypoint so a sync can trigger that restart.
Drift
Each patch moves the container further from what its image describes. Trigger a full rebuild from the Tilt UI regularly, and always before you trust a result. CI should build clean images and never use live_update.
When a rebuild can't be avoided, Dockerfile layer order decides how long it takes. Copy lockfiles and install dependencies before you copy source, so a code change doesn't invalidate the dependency layer.
# Tiltfile (Starlark)
load('ext://restart_process', 'docker_build_with_restart')
# Interpreted service: patch source in place, rebuild only when needed.
docker_build(
'registry.example.com/orders-api',
'./orders-api',
live_update=[
# fall_back_on must come first: these files force a full image build.
fall_back_on(['./orders-api/Dockerfile', './orders-api/.nvmrc']),
# Copy edited source; the app's file watcher reloads it.
sync('./orders-api/src', '/app/src'),
# Sync manifests so the run trigger below has fresh files to act on.
sync('./orders-api/package.json', '/app/package.json'),
sync('./orders-api/package-lock.json', '/app/package-lock.json'),
# Reinstall dependencies only when the lockfile changes.
run('cd /app && npm ci', trigger=['./orders-api/package-lock.json']),
],
)
# Compiled service: build on the host for the container's OS/arch.
local_resource(
'inventory-compile',
'cd inventory && CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o build/inventory ./cmd/inventory',
deps=['./inventory/cmd', './inventory/internal', './inventory/go.mod', './inventory/go.sum'],
)
# Ship only the binary; a sync restarts the process instead of rebuilding.
docker_build_with_restart(
'registry.example.com/inventory',
'./inventory',
entrypoint=['/app/inventory'],
dockerfile='./inventory/Dockerfile.dev',
only=['./build'],
live_update=[sync('./inventory/build/inventory', '/app/inventory')],
)
k8s_yaml(['k8s/orders-api.yaml', 'k8s/inventory.yaml'])
k8s_resource('inventory', resource_deps=['inventory-compile'])
A Tiltfile that live-updates a Node service with lockfile-triggered reinstalls and fall_back_on rebuilds, and handles a Go service by compiling on the host, syncing only the binary, and restarting the process.
How can Tilt save engineering time as the number of services grows?
Load only what you are editing
At ten or more services, starting everything on tilt up makes startup slow and the UI noisy. Declare a list argument with config.define_string_list, call config.parse(), and pass the result to config.set_enabled_resources. Each developer then runs tilt up -- api billing and gets only those services plus their dependencies. Set labels on k8s_resource to group the UI by domain. Give slow image builds trigger_mode=TRIGGER_MODE_MANUAL so they run only when you click them. Use local_resource for code generation or unit tests so they rerun on file change without a container.
Render manifests with kustomize() or helm() from the production charts, using a dev overlay or values file. A forked set of dev YAML drifts from production without anyone noticing. Keep secrets in a gitignored local file or pull them from your secret store at startup, and never commit them.
Illustrative estimate (assumed numbers, not a benchmark): time saved per day = edits × (full cycle − live-update cycle). With 40 edits, a 90 s rebuild-and-redeploy, and a 5 s sync: 40 × 85 s ≈ 57 minutes per developer.
The costs
The Tiltfile is a program. Without an owner, it rots the way bespoke shell scripts do. Running every dependency locally also stops scaling once laptops run out of memory. That pushes teams toward shared remote dev or staging instances, which bring drift and conflicts over shared state.
How do you debug services and migrate from Docker Compose to Tilt?
Reading failures by phase
Each resource in the Tilt UI reports its update status and its runtime status separately. That split is the fastest way to triage. A red update means the image build or the apply step failed, so check the Dockerfile or the manifest. A green update with a crashing runtime means the code is at fault, or a missing config value or unreachable dependency is. Per-resource logs keep each service's output separate, so you don't have to dig through one interleaved stream.
For debuggers, add the debug port to the resource's port_forwards alongside the HTTP port. Your IDE then attaches to localhost as if the process ran natively. Live update restarts can drop the debug session, so reattach after each sync.
Migrating incrementally
Start by pointing a Tiltfile at your existing docker-compose.yml with docker_compose(). Nothing about the runtime changes. The team gets the UI, per-service logs and live update on Compose services before anyone installs a local cluster. Once that is stable, move one service at a time to Kubernetes manifests. The service with the most painful rebuild cycle is a good first candidate. The rest stay on Compose until they are migrated.
When to skip Tilt
Stay on Compose if production doesn't run on Kubernetes, if you run only a few services that rebuild quickly, or if nobody will own the Tiltfile. A Tiltfile is code, and an unmaintained one fails in more confusing ways than a stale Compose file.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to tilt local development microservices, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Changing a shared variable is one edit and one review instead of editing every service's
.envby hand.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.