What is Tilt and how does its inner dev loop work?
Tilt is an open-source tool that watches your source tree and keeps a Kubernetes cluster in sync with it. You describe your services in a Tiltfile. Tilt then runs a continuous loop: it detects a change, rebuilds or patches the affected container, deploys it, and streams the result back to you in a terminal and a web UI.
file save -> image build or live update (sync files into the running container) -> push to local registry or load image into cluster -> deploy (apply manifests, wait for the pod) -> logs + UI status -> back to watching
Compare this with the manual cycle. Without Tilt, you run docker build, tag the image, push it, update the manifest or restart the deployment, find the new pod, and run kubectl logs. Each step is quick on its own. The cost is the context switching and the mistakes, such as a stale tag or logs from the wrong pod. Tilt removes the manual steps. Live update can also skip the image build entirely, so an interpreted-language change can reach the running process without a new container.
Illustrative estimate: assume 90 seconds of manual steps per change and 30 changes a day. That is 45 minutes of mechanical work per engineer per day, before counting any mistakes.
The more important idea for large systems is that a Tiltfile is a program, written in Starlark. It can select, group, and parameterize services. Treat it as code that decides what runs, not as a script that launches everything.
+---------------------+ +----------------------------------+
| Tiltfile (Starlark) |----->| File watcher detects file save |<-------+
| selects, groups and | +----------------------------------+ |
| parameterizes the | | | |
| services that run | | new image | files only |
+---------------------+ v v |
+----------------+ +--------------------+ |
| Image build | | Live update: | |
| (docker build) | | sync files into | |
+----------------+ | running container, | |
| | no image build | |
v +--------------------+ |
+----------------+ | |
| Push to local | | |
| registry, or | | |
| load image | | |
| into cluster | | |
+----------------+ | |
| | |
v | |
+----------------+ | |
| Deploy: apply | | |
| manifests and | | |
| wait for pod | | |
+----------------+ | |
| | |
v v |
+----------------------------------------+ |
| Logs + status: terminal and web UI |------+
+----------------------------------------+
Tilt's inner dev loop: the Tiltfile decides which services are in scope. A file save then goes through either a full image build, push or load, and deploy, or a live update that syncs files into the running container. Both paths end in logs and UI status, and Tilt goes back to watching.
How does Tilt work?
tilt up starts a long-running process. That process does five jobs.
1. Evaluate the Tiltfile. Tilt first evaluates the Tiltfile. The result is a set of resources, and each resource is a unit Tilt manages. Three kinds matter here:
- image builds declared with
docker_build - Kubernetes objects loaded with
k8s_yamland grouped withk8s_resource - host commands declared with
local_resource
When the Tiltfile or a file it loads changes, Tilt re-evaluates it and reconciles the resource set. Resources you add start up, and resources you remove are torn down.
2. Swap in its own image tags. When Tilt builds an image such as example/orders-api, it gives the result a tag that Tilt generated itself. It then scans the loaded manifests for references to that image name and rewrites them to the new tag before applying them. You never edit tags by hand. A manifest that references an image Tilt does not build is applied unchanged.
3. Watch files and choose an update. Each image build depends on its build context and any files listed in live update rules. Tilt ignores the paths excluded by .dockerignore and by the ignore patterns you configure. When a watched file changes, Tilt queues an update for the resource that owns it. It then picks one of two updates:
-
Live update. Tilt uses this when all of these hold:
- the resource has live update rules
- the container is already running
- every changed file is covered by a
syncstep - no changed file matches
fall_back_on
Tilt copies the changed files into the running container and runs any matching
runsteps. -
Full image build and redeploy. Tilt uses this in every other case, and also when a live update step fails.
4. Deploy and track the workload. For a full update, Tilt does three things:
- applies the manifests to the cluster
- watches the pods that belong to the workload
- reports whether they became ready, crashed, or failed to pull
It also streams container logs and sets up the port forwards declared on k8s_resource. A local_resource runs its command on your machine and reports in the same UI.
5. Report status and clean up. The terminal and the web UI show the state of every resource:
- the last update
- its logs
- whether it is healthy or failing
You can also mark a resource as manual-trigger, which stops it from rebuilding on every save. tilt down deletes the Kubernetes objects that Tilt applied.
How can Tilt save engineering time?
Tilt saves time in a few specific ways. Each one only matters if your setup meets the conditions described in the next section.
- It removes manual redeploy steps. Building, tagging, pushing, editing manifests, finding the new pod and tailing its logs collapse into a file save. This is the per-change saving from the illustrative estimate above.
- Live update skips image builds. For interpreted languages, and for compiled languages whose binary is built on the host, most edits never trigger an image build or a pod restart. The wait between saving and seeing the effect shrinks to the time it takes to sync files and reload.
- Subsetting avoids work nobody needs. Services you are not editing run from prebuilt images, so they cost no build time at startup. They also leave CPU free for the builds you do need. This is covered in the subsetting section below.
- One place to look. Logs, readiness state and build errors for every service appear in one UI. Nobody has to hunt across terminals and pods to find which service failed.
- Onboarding becomes a command. A new engineer clones the repository, starts a local cluster and runs
tilt upwith a profile. They no longer follow a wiki page of setup steps that has drifted from reality. - Configuration breakage is caught once. Running
tilt ciin the pipeline finds a broken Tiltfile or manifest before each developer runs into it separately.
These savings are not free. The Tiltfile needs maintenance, and laptops need enough memory for a cluster. The rollout section below works through an illustrative estimate that sets the time saved against that maintenance cost. Use your own team's numbers rather than assuming the margin is positive.
Who should use Tilt, and when should you avoid it?
Tilt pays off when three conditions hold together:
- your services already deploy to Kubernetes
- a developer routinely needs many of them running at once
- the manifests, Helm charts or Kustomize overlays already exist
Backend and platform engineers in that position get a loop that rebuilds and redeploys only what changed. They also exercise the same Deployments, Services and ConfigMaps that production uses, so manifest mistakes show up on a laptop rather than in staging.
If you run three or four services, or you do not deploy to Kubernetes at all, Tilt adds a cluster to keep alive and a layer of YAML that buys you little. Running processes directly is the fastest loop available, because there is no image build. A compose file is often enough for a handful of services with a database. Pick the cheapest option that catches the bugs you actually ship.
| Option | Setup effort | Closeness to production | Resource use | Loop speed |
|---|---|---|---|---|
| Processes run directly | Low | Low: no containers, no orchestration | Lowest | Fastest |
| Compose-based setup | Low to medium | Medium: containers, but not your real manifests | Moderate | Fast |
| Tilt on local Kubernetes | Medium to high | Higher: real manifests and Kubernetes objects | Highest: cluster overhead plus every pod | Fast with live update, slower on full rebuilds |
"Higher" is not "identical." A local cluster still differs from production in several ways:
- networking and ingress
- storage classes
- node count
- secrets handling
- cloud-managed services such as hosted databases and queues
Tilt narrows the gap but does not close it.
What are the alternatives to Tilt?
The alternatives fall into a few categories. Each one trades closeness to production, resource use and setup effort in a different way.
- Running processes directly on the host. Each service runs from your editor or terminal with its language's own hot reload. There are no containers and no cluster, so this is the fastest loop and uses the least memory. You lose container images, manifests and service discovery, and wiring a dozen services together through environment variables and ports gets fragile.
- Compose-based setups. A single compose file describes containers, networks and volumes. It is simple to learn and works well for a handful of services plus a database. It does not use your Kubernetes manifests, so configuration errors in Deployments, Services or ConfigMaps go unnoticed until a real cluster runs them. Rebuilds are usually whole images unless you add bind mounts.
- Scripts or Makefiles around
docker buildandkubectl apply. These have no new dependency and are fully transparent. You end up reimplementing file watching, tag management, readiness tracking and log aggregation. Scripts like this tend to grow until they become a worse version of a dev-loop tool. - Other Kubernetes dev-loop tools. Several open-source tools cover similar ground. They watch, build and deploy to a cluster, often with file sync. They differ in how they are configured, usually declarative YAML rather than a programmable file. They also differ in how they handle subsetting and in their UI. If a declarative config fits your team better than Starlark, evaluate them on the same criteria used in this article.
- Connecting a local process to a remote cluster. Some approaches run the service you are editing on your laptop and route its traffic to and from a shared cluster that runs everything else. This avoids running dozens of pods locally. It needs a shared cluster, network access to it, and care to keep developers from interfering with each other.
- Remote shared dev environments. The whole stack runs on cluster or cloud resources, and the laptop only edits code. This suits systems too large for a laptop. You pay in network latency, infrastructure cost and contention between users.
The rollout section returns to these alternatives briefly. It covers when each one is the better fit for a team.
How do you write a Tiltfile with docker_build, k8s_yaml and k8s_resource?
A Tiltfile is Starlark, a Python dialect, and Tilt re-evaluates it whenever it changes. A minimal single-service setup needs three calls:
docker_buildnames an image and its build context. Tilt then finds that image name in your Kubernetes manifests and swaps in the tag it built.k8s_yamlloads those manifests. Pass it rendered output from the built-inhelm()orkustomize()functions instead of maintaining separate dev YAML, so local and deployed configs come from one source.k8s_resourceturns a workload into a named unit in the Tilt UI. It is also where you setport_forwardsandresource_deps, for example making the API wait until its database resource is ready.
The speed comes from live_update, a list of steps attached to docker_build:
fall_back_onmust come first. It lists files, such aspackage.json,go.modorrequirements.txt, whose changes trigger a full image rebuild.synccopies changed files into the running container.runexecutes a command in the container, optionally only when specific files change.
Interpreted languages gain the most, because syncing source plus a hot-reloading server skips the build entirely. Compiled services can get similar speed if a local_resource cross-compiles the binary on the host and live_update syncs just that artifact.
The cost is drift. Every sync and run step mutates a container that no Dockerfile describes. Deleted files, packages added by hand, and leftover state can make it behave differently from a clean build. Trigger a full rebuild in these situations:
- before trusting a test result
- after switching branches
- whenever behavior seems inexplicable
docker_build(
'example/orders-api',
context='./services/orders-api',
live_update=[
# Must come first: dependency manifest changes force a full rebuild.
fall_back_on(['./services/orders-api/requirements.txt']),
# Copy changed source into the running container.
sync('./services/orders-api/app', '/app/app'),
# Only runs when the listed file changes.
run('pip install -r /app/requirements-dev.txt',
trigger=['./services/orders-api/requirements-dev.txt']),
],
)
k8s_yaml(helm(
'./charts/orders-api',
name='orders-api',
values=['./charts/orders-api/values-dev.yaml'],
))
k8s_yaml(helm('./charts/postgres', name='orders-db'))
k8s_resource('orders-db', port_forwards='5432:5432')
k8s_resource(
'orders-api',
port_forwards='8080:8080',
resource_deps=['orders-db'],
)
A minimal Tiltfile that builds one service, loads its Helm-rendered manifests, waits for its database, and uses live_update to sync source while dependency changes trigger a full rebuild.
How do you structure a Tiltfile for dozens of microservices?
A single Tiltfile that defines thirty services becomes unreadable quickly. Split it along ownership lines. Tilt offers two mechanisms:
load()imports functions and values from another Starlark file. Use it for shared helpers.include()executes another Tiltfile as if its contents were inline. Use it for per-team service definitions.
A workable layout:
Tiltfileat the repo root, which only parses config and includes team filestilt/lib.starfor shared helperstilt/teams/payments.tilt,tilt/teams/search.tilt, and so on, one per team- each service's manifests stay in its own directory, next to its code
The central helper in lib.star takes a service name, a source path and a registry image. It checks whether that name is in the developer's list of services being edited:
- If it is, the helper calls
docker_buildwith live update rules. - If it is not, the helper skips the build and deploys the manifests with the prebuilt image already referenced in the YAML.
Each service definition then becomes a one-line call. That keeps team files short and makes the behavior consistent across services.
The rule this helper enforces is that a service you are not editing should never build locally. Building twenty images you will not touch has three costs:
- it wastes minutes on every startup
- it burns CPU that your live updates need
- it runs code that nobody has verified matches what CI ships
Treat the Tiltfile as production code. It is Starlark, so it has real logic, real bugs and real failure modes. Give it a named owner and require review for changes to lib.star. When something breaks, debug it rather than adding a workaround in a team file. Without that discipline, it turns into a script nobody understands and everyone is afraid to edit.
def _editing():
raw = os.getenv('TILT_EDIT', '')
return [s.strip() for s in raw.split(',') if s.strip()]
def tilt_service(name, src, image, port=None):
# Only services being edited are built locally. The ref equals the
# registry image in the YAML, so Tilt swaps in the local build.
if name in _editing():
docker_build(image, src, live_update=[
sync(src + '/app', '/app'),
])
# Not edited: no build. The manifest's prebuilt CI image is deployed as-is.
k8s_yaml(src + '/k8s.yaml')
k8s_resource(name, port_forwards=[port] if port else [],
labels=[src.split('/')[1]])
load('../lib.star', 'tilt_service')
tilt_service('checkout', 'services/payments/checkout',
'registry.example.com/payments/checkout', port=8080)
tilt_service('ledger', 'services/payments/ledger',
'registry.example.com/payments/ledger')
include('./tilt/teams/payments.tilt')
include('./tilt/teams/search.tilt')
A shared Starlark helper builds an image from source only for services listed in TILT_EDIT and otherwise deploys the prebuilt registry image, so each team file holds only one-line service definitions.
How do you run only a subset of services with Tilt?
Subsetting is required at this scale. Laptop RAM and CPU are the real limit. Once dozens of pods each start their own JVM, Node process or Python interpreter, the machine runs out of memory well before Tilt or Kubernetes reaches any limit of its own. A developer only needs the services they are changing, plus whatever those services call.
Subsetting takes three calls:
- Declare a list argument with
config.define_string_list("to-run", args=True). - Read it with
config.parse(). - Pass the result to
config.set_enabled_resources().
Map each profile name to a resource list in lib.star so that adding a service updates every profile that depends on it. Developers then run tilt up payments, and they can switch profiles without restarting by using tilt args.
| Profile | Built from source | Run from pinned images | Pointed at remote |
|---|---|---|---|
payments |
payments-api, ledger-worker | accounts-api, postgres | fraud-scoring (shared staging) |
search |
search-api, indexer | catalog-api, elasticsearch | recommendations |
frontend |
web-bff | accounts-api, catalog-api, payments-api | all async workers |
The middle column carries a risk: version skew. Suppose catalog-api runs from an image that is three weeks old:
- your change may fail against a contract that has since been fixed
- it may pass against behavior that no longer exists
Neither result points to the real cause, so either can cost an afternoon. To limit this:
- Pin dependency images to a tag that CI refreshes from the main branch.
- Show that tag in the resource's labels or links so a stale image is visible in the UI.
load('./lib.star', 'PROFILES')
config.define_string_list('to-run', args=True)
cfg = config.parse()
enabled = []
for name in cfg.get('to-run', []):
# A profile name expands to its services. Any other value is treated as a single resource name.
for r in PROFILES.get(name, [name]):
if r not in enabled:
enabled.append(r)
if not enabled:
enabled = PROFILES['payments']
config.set_enabled_resources(enabled)
k8s_yaml(listdir('k8s'))
docker_build('registry.example.com/payments-api', './services/payments-api')
k8s_resource('accounts-api', labels=['pinned-image'])
k8s_resource('postgres', labels=['pinned-image'])
A Tiltfile that turns tilt up payments or tilt args search into an expanded resource list, passes it to config.set_enabled_resources, and labels pinned-image dependencies so they are visible in the UI.
Which local cluster should you use, and how do you handle startup order and stateful dependencies?
Choosing a local cluster
Tilt reads your kubeconfig context and recognises common local clusters. It also reads the standard local-registry-hosting ConfigMap that some clusters publish. When a local registry is advertised, or the cluster shares the host's image store, Tilt builds and loads images locally and skips the push to a remote registry.
| Cluster | How images reach it | Onboarding notes |
|---|---|---|
| kind | Loaded into nodes or a local registry | Light, scriptable, and matches CI well |
| k3d | Registry created alongside the cluster | Fast startup and a small footprint |
| minikube | Build against its internal daemon or registry | Many drivers, so setups differ across OSes |
| Docker Desktop | Shares Docker's image store | Little setup, but licensing and resource limits apply |
Whichever you choose, test the setup on every OS and CPU architecture your team uses. On arm64 laptops, a dependency published only as amd64 will either fail to pull or run slowly under emulation. Publish multi-arch images for anything you own.
Startup order
resource_deps delays a resource until its dependencies are ready, and readiness probes define what "ready" means. Use it sparingly, for two reasons:
- Each dependency you add makes startup more serial and slower.
- It hides services that crash when a dependency is missing instead of retrying, and that behaviour will break in production.
Use labels to group the dashboard by domain, such as payments and infra, so 30+ resources stay readable.
Stateful dependencies
You have three options:
- Lightweight in-cluster instances. These are isolated and disposable.
- In-cluster instances seeded by a
local_resource. The seed step gives everyone the same realistic data. - Shared dev instances. These are cheap to run, but other people's changes can affect your data.
Expose the choice as a Tiltfile config flag so each engineer can switch without editing the Tiltfile.
How do you roll Tilt out to a team and keep it from breaking?
Make the Tiltfile a shared, tested artifact
Commit the Tiltfile in the same repository as the services it builds. A change to a Dockerfile or manifest and the matching Tiltfile change then go through review together.
Document the per-developer profiles in a README next to the Tiltfile. Cover which service groups exist and which config flags select local or shared dependencies. Keep personal choices in a gitignored config file so nobody has to edit shared code to change their own setup.
Run tilt ci in your pipeline against a throwaway cluster. It brings up the resources, waits for them to become healthy, and exits non-zero on failure. This catches a broken Tiltfile, an invalid manifest or a failing build before twenty developers each run into it on Monday morning.
Weigh the cost honestly
Illustrative estimate, assumed inputs:
- 15 engineers each make 25 changes a day.
- Tilt's live update saves 45 seconds per change compared with a full rebuild and redeploy.
That works out to about 4.7 engineer-hours saved per day.
Against that, assume these costs:
- one owner spends 6 hours a week maintaining the Tiltfile and fixing laptop-specific problems such as CPU architecture, memory limits and VPN DNS
- each new hire needs half a day of onboarding
With these inputs Tilt clearly pays for itself. If you halve the team or the number of changes per day, the margin shrinks quickly.
When something else fits better
- Running processes directly suits a handful of services in a single language.
- Compose-based setups suit teams that don't deploy to Kubernetes, or that don't need production-like manifests locally.
- Remote shared dev environments suit stacks too large for a laptop, at the cost of network latency and contention between users.
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.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
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.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- 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.