What is Tilt and how does its development loop work?

Tilt is an open-source tool that automates the inner development loop for services running on Kubernetes. You describe your services in a Tiltfile, a configuration file written in Starlark, a Python dialect. Tilt reads it and runs the loop on every save: it watches source files, rebuilds the affected container image, applies the Kubernetes manifests to a local cluster such as kind, k3d, minikube or Docker Desktop's built-in Kubernetes, and waits for the pod to become ready.

  edit file
      |
      v
  Tilt file watcher ----> which resources depend on this path?
      |
      v
  build image (or sync files into the running container)
      |
      v
  push or load image into local cluster
      |
      v
  kubectl-style apply of manifests
      |
      v
  pod restarts -> readiness -> logs streamed to Tilt UI
      |
      +---------------- back to editing ----------------+

Tilt tracks each service as a separate resource. Its web UI shows the build status, runtime status and logs for each resource side by side. When ten services are running, this is what makes the setup usable. A failed build or a crash-looping pod appears next to the one service that caused it, so you don't have to search for it with kubectl get pods and ten separate log tails.

The main reason to choose Tilt is that the manifests it applies locally are the same kind you deploy to staging and production. That includes Deployments, Services, ConfigMaps, probes, resource limits and Helm charts or Kustomize overlays. A docker compose file describes a different system that only approximates your real deployment. With Tilt, mistakes in that configuration, such as a misnamed Service, a failing readiness probe or a missing environment variable, show up on your laptop before they reach a shared cluster.

+--------------------------------------------------------------------------+
| Developer laptop                                                         |
|                                                                          |
|  +-------------+         +-------------------------------------------+   |
|  | source code |--save-->| Tilt (reads the Starlark Tiltfile)        |   |
|  | manifests   |         |                                           |   |
|  +-------------+         |  file watcher: path -> affected resource  |   |
|                          |        |                                  |   |
|  +-------------+         |        v                                  |   |
|  | Tilt web UI |<-status-|  image build  or  live sync into pod      |   |
|  | per resource|  + logs |        |                                  |   |
|  | build/run/  |         |        v                                  |   |
|  | logs        |         |  apply manifests (YAML, Helm, Kustomize)  |   |
|  +-------------+         +------+-----------------------------^------+   |
|                                 | images + manifests          | status   |
|                                 v                             | + events |
|  +------------------------------------------------------------+           |
|  | Local cluster: kind / k3d / minikube / Docker Desktop      |           |
|  |                                                            |           |
|  | [svc-a] [svc-b] [svc-c] [svc-d] [svc-e] ... [svc-j]        |           |
|  |  Deployments, Services, ConfigMaps, probes, limits         |           |
|  +------------------------------------------------------------+           |
|                                                                          |
|  Same manifest kinds you deploy to staging and production.               |
+--------------------------------------------------------------------------+

Tilt watches source files, rebuilds or live-syncs only the affected service, applies the same kinds of Kubernetes manifests you deploy to a local cluster, and reports per-resource build status, runtime status and logs in its web UI.

How does Tilt work under the hood?

tilt up starts a long-running process. Its first step is to evaluate the Tiltfile. Evaluation does not build or deploy anything directly. Calls such as docker_build(), k8s_yaml(), k8s_resource() and local_resource() register declarations, and Tilt turns them into an internal model of resources. Each resource has a set of file dependencies, an optional image build, the manifests it applies and the resources it waits on. If you edit the Tiltfile itself, Tilt re-evaluates it and reconciles the model. Resources you added start, and resources you removed are torn down.

From that model Tilt knows which file paths belong to which resource. A build's dependencies default to its build context, and you can narrow them with options such as only or ignore, or with a .dockerignore. When a watched file changes, Tilt maps the path to the affected resources and queues only those. A change under services/orders/ does not touch the other nine services.

For each image, Tilt builds with Docker by default. You can plug in other builders through custom_build(). After the build, Tilt gives the image a unique tag and gets it to the cluster. On Docker Desktop's Kubernetes the cluster shares the local Docker daemon, so the image is already available. On kind or k3d with a local registry, Tilt pushes the image there. Tilt then parses the registered manifests, finds image references that match a docker_build name, and rewrites them to the new tag before applying. That rewrite is why a manifest that says image: orders ends up running the image you just built.

After applying, Tilt watches the cluster through the Kubernetes API. It follows the pods that belong to each resource, records their status and readiness, and streams their logs into the UI under the matching resource. That per-resource view is built from the same model that drives builds.

Live update short-circuits this path. When a changed file matches a sync() rule, Tilt copies the file into the running container and runs any matching run() steps. It skips the image build and the manifest apply. If a change can't be handled that way, for example a file outside every sync path that is listed in fall_back_on, Tilt falls back to a full image rebuild and redeploy.

tilt down deletes the Kubernetes objects that Tilt applied from the Tiltfile. It's the clean way to reset the environment.

Who should use Tilt, and when is docker compose the better choice?

Tilt pays off when your services already deploy to Kubernetes and the manifests are something your team edits. Backend and platform engineers in that position get one set of Deployments, Services and ConfigMaps for both local and deployed environments, so a change to a probe or a port is tested where it is written. If manifests are generated by a separate team and developers never open them, that fidelity is mostly unused, and you are paying for a local cluster without the benefit.

Skip Tilt for small systems of two or three services with no Kubernetes-specific behaviour. Docker compose starts faster, needs no cluster, and any engineer can read it. Tilt also cannot help with managed cloud services that have no local equivalent, such as a proprietary queue or a hosted database feature. Those still need emulators, mocks or a real cloud account.

The usual alternatives trade off differently:

Approach Fidelity to production Cost Isolation between developers
Tilt on a local cluster High for Kubernetes config, limited by laptop resources Laptop CPU and memory Full
Docker compose Low for Kubernetes config, fine for app logic Lowest Full
Shared remote dev cluster High, including real cloud services Ongoing cluster spend Weak unless you add per-developer namespaces
Emulators or mocks Varies, often diverges on edge cases Low Full

Most teams mix these approaches. A common split is Tilt for the services they own and emulators for cloud dependencies they cannot run locally.

When should you avoid Tilt?

Tilt adds a local cluster, a Tiltfile to maintain and one more tool for every engineer to learn. In these situations that cost tends to outweigh the benefit:

  • You don't deploy to Kubernetes. If production runs on VMs, a serverless platform or a container service with its own config format, Tilt's main advantage disappears. You would be testing Kubernetes manifests that exist only for local development.
  • The system is small and stable. For two or three services that rarely change their deployment config, docker compose or running processes directly on the host is simpler and starts faster.
  • Laptops can't hold the workload. Some services need far more memory than a developer machine has, such as large JVM services, search clusters or ML models, or need hardware such as GPUs. Selective startup helps, but if even the minimum working set doesn't fit, a remote dev cluster is the better fit.
  • Most behaviour depends on managed cloud services. If the interesting bugs live in IAM policies, managed queues or hosted database features, a local cluster with stand-in containers won't reproduce them. You'll spend the time maintaining emulators instead.
  • You need performance or scale results. A single-node local cluster on a laptop says nothing reliable about latency, throughput or autoscaling. Run those tests in an environment that matches production.
  • Nobody will own the Tiltfile. An unowned Tiltfile drifts out of date with the manifests and breaks quietly. A broken local environment costs more time than a missing one. If no one can maintain it, start with something lighter.

How should you structure a Tiltfile for ten local microservices?

Give each service its own directory with its source, Dockerfile, and Kubernetes manifests, plus a small Tiltfile that describes only that service. A top-level Tiltfile at the repository root pulls them together. include('./services/orders/Tiltfile') executes a child file in place. load('./tilt/lib.star', 'service') imports specific symbols. Use include() for per-service files and load() for shared helpers. Keeping each service's file next to its code means the team that owns the service also owns how it runs locally.

Each service file needs three building blocks:

  • docker_build('orders', './services/orders') tells Tilt how to build an image. Tilt then rewrites any matching image reference in your manifests to the freshly built tag.
  • k8s_yaml() registers manifests. It accepts a file path, a list of paths, or the output of helm('./charts/orders') or kustomize('./deploy/overlays/dev'). This lets you reuse the charts or overlays you already ship instead of maintaining separate dev YAML.
  • k8s_resource('orders', port_forwards='8080:8080', labels=['checkout'], resource_deps=['postgres']) configures how the workload appears in Tilt. labels groups resources in the UI. resource_deps delays startup until dependencies are healthy.

With ten services, those three calls get copy-pasted ten times and slowly drift apart. Replace them with one helper in a shared .star file, such as service(name, port, deps=[], labels=[]), that wraps all three. Each service file then becomes a single readable line.

Stop there. A helper that grows conditionals, code generation, and nested abstractions turns into a framework that only its author can debug. When it breaks at 9 a.m., everyone else is blocked. Prefer a little repetition to that kind of indirection.

def service(name, context, manifests, port, deps=[], labels=[]):
    # Paths arrive already resolved by the caller, so relative-path
    # rules inside loaded files never surprise anyone.
    docker_build(name, context)
    k8s_yaml(manifests)  # a path, a list of paths, or helm()/kustomize() output
    k8s_resource(
        name,
        port_forwards='%d:%d' % (port, port),
        labels=labels,
        resource_deps=deps,  # wait until these resources are healthy
    )

load('../../tilt/lib.star', 'service')

service('orders',
        context=os.path.abspath('.'),
        manifests=kustomize(os.path.abspath('./k8s/overlays/dev')),
        port=8080, deps=['postgres'], labels=['checkout'])

k8s_yaml('infra/postgres.yaml')
k8s_resource('postgres', labels=['infra'])

for svc in ['orders', 'payments', 'inventory']:  # extend to all ten
    include('./services/%s/Tiltfile' % svc)

This example shows a single shared Starlark helper that wraps docker_build(), k8s_yaml() and k8s_resource(), a per-service Tiltfile that calls it with Kustomize or Helm output, and a root Tiltfile that uses include() to load each service.

How does live update work for interpreted and compiled services?

A live_update block replaces the image rebuild with a short list of steps applied to the running container. sync() copies changed files from a host path to a container path. run() executes a command inside the container after the sync, and its trigger argument limits it to specific files. Point the trigger at requirements.txt or package.json so the reinstall runs only when dependencies change, not on every edit to a handler.

For interpreted services, sync the source tree and let a reloading process pick up the change, such as a dev server with file watching. Compiled services need a different approach. Compiling inside the container is slow and requires a toolchain in the image, so build on the host with a local_resource, sync only the output binary, and restart the process.

Concern Interpreted (Python, Node) Compiled (Go, Rust)
What gets synced Source files Built binary
How the change takes effect Process reloads itself Process restarts
Host setup Minimal Cross-compilation toolchain
Typical failure Stale dependencies Wrong architecture or libc

The main cost is drift. After a day of syncs, the container holds files that no image build ever produced. Make it a habit to force a clean rebuild before you trust a test result.

Compiled services need a host toolchain that targets the container's OS and CPU. An ARM laptop builds ARM binaries by default, and an amd64 container cannot run them. Binaries linked against glibc fail on Alpine's musl. A static build, or a base image that matches the host's libc, avoids both problems.

load('ext://restart_process', 'docker_build_with_restart')

k8s_yaml(['k8s/api-gateway.yaml', 'k8s/orders.yaml'])

docker_build(
    'example/api-gateway',
    'services/api-gateway',
    live_update=[
        sync('services/api-gateway', '/app'),
        # Reinstall only when the dependency manifest changes,
        # not on every edit to a handler.
        run('pip install -r /app/requirements.txt',
            trigger=['services/api-gateway/requirements.txt']),
    ],
)

local_resource(
    'orders-compile',
    'cd services/orders && CGO_ENABLED=0 GOOS=linux GOARCH=amd64 '
    + 'go build -o build/orders ./cmd/orders',
    deps=['services/orders/cmd', 'services/orders/internal',
          'services/orders/go.mod', 'services/orders/go.sum'],
)

docker_build_with_restart(
    'example/orders',
    'services/orders',
    entrypoint=['/app/orders'],
    only=['./build'],
    live_update=[sync('services/orders/build', '/app')],
)

k8s_resource('orders', resource_deps=['orders-compile'])

A Tiltfile that live-updates a Python service by syncing source and reinstalling only when requirements.txt changes, and updates a Go service by cross-compiling a static binary on the host, syncing it, and restarting the process.

How do you run only the services you are working on?

Split the ten services into two groups. Actively developed services get a docker_build with live update. Everything else just needs to run: those services use manifests that reference a tagged image in your team's registry, so Kubernetes pulls them and Tilt never builds them. In the Tiltfile, loop over the services and call docker_build only for names in the developer's chosen list.

To pick that list, declare it with config.define_string_list("to-run", args=True). Read it back with config.parse(), then pass the result to config.set_enabled_resources(). With that in place, tilt up orders payments starts only those two resources. When an enabled resource lists others in resource_deps, Tilt enables those dependencies too. A developer working on orders never has to remember that it needs inventory and auth. The dependency graph lives in the Tiltfile, not in a wiki page.

The benefit is resource cost. Illustrative estimate, with assumed inputs:

  • A dev-mode service with live update, debug flags, and a dev server uses 400 MB.
  • A prebuilt production image idles at 150 MB.
  • With all ten in dev mode, that is about 4 GB before any image builds run.
  • With two active services and three pulled dependencies, it is about 1.25 GB. The other five services don't run at all.

On macOS the pressure is greater. Containers run inside a Linux VM that has a fixed memory allocation, so builds and running pods compete for the same space. The VM also takes memory away from the host's IDE and browser.

Startup takes less time as well. Tilt builds two images instead of ten, and pulling the rest from the registry is usually faster than compiling them.

config.define_string_list("to-run", args=True)
cfg = config.parse()
active = cfg.get("to-run", [])

REGISTRY = "registry.example.com/shop"
SERVICES = ["auth", "inventory", "orders", "payments", "catalog",
            "cart", "search", "shipping", "notifications", "reviews"]

DEPS = {
    "orders": ["inventory", "auth"],
    "payments": ["auth"],
    "cart": ["catalog", "auth"],
    "shipping": ["orders"],
}

for name in SERVICES:
    # Each manifest pins a tagged image, e.g. registry.example.com/shop/auth:2.3.1.
    # With no matching docker_build, Kubernetes pulls that image and Tilt builds nothing.
    k8s_yaml("k8s/%s.yaml" % name)

    if name in active:
        # Actively developed: build locally and sync source changes into the pod.
        docker_build(
            REGISTRY + "/" + name,
            "services/" + name,
            live_update=[sync("services/%s/src" % name, "/app/src")],
        )

    # Assumes each Deployment is named after its service.
    k8s_resource(name, resource_deps=DEPS.get(name, []))

if active:
    config.set_enabled_resources(active)

A Tiltfile that reads service names from tilt up arguments, calls docker_build with live update only for those services, and uses resource_deps so the upstream services they need start from prebuilt registry images.

How do you handle databases, queues, and caches in Tilt?

Treat Postgres, RabbitMQ, and Redis as ordinary Kubernetes resources. Write a plain Deployment or StatefulSet manifest for each, load it with k8s_yaml(), and give it a name with k8s_resource(). Then declare resource_deps on every service that needs it. Tilt holds the dependent service until its dependencies report ready. This removes the startup race where orders crashes three times because Postgres is still initializing. Those crash loops also bury real errors in the logs.

Use local_resource() for migrations and seed scripts, and make it depend on the database resource. The application services then depend on the migration resource, so the order is explicit: database ready, schema applied, services start. You can also trigger a local resource manually from the Tilt UI. That makes re-seeding after a destructive test a single click, and you don't need to remember a script name.

"Ready" only means something if the container defines it. Add a readiness probe to every stateful dependency, for example pg_isready for Postgres or a PING for Redis. Without a probe, Kubernetes marks the pod ready as soon as the process starts. Tilt then releases dependents before the database is accepting connections.

Be clear about what this setup does not prove. A local cluster flattens networking and network policies. It uses whatever default storage class the tool provides. It usually has no real ingress controller. It replaces managed databases and queues with single containers that have different failover and connection-limit behavior. It also skips IAM and workload identity entirely, so permission errors only appear later. Passing in Tilt means the code works; passing in staging is a separate result.

How can Tilt save engineering time?

The time savings come from four places.

Shorter edit-to-running loops. Without automation, testing a change inside the cluster means rebuilding the image, tagging it, loading or pushing it, editing or re-applying the manifest, and waiting for the rollout. Tilt does that on save. With live update it skips the build and apply entirely for synced files.

Illustrative estimate, with assumed inputs:

  • A manual rebuild-and-redeploy cycle takes an assumed 3 minutes, including the time spent typing commands and checking pod status.
  • A live-update sync and reload takes an assumed 10 seconds.
  • A developer runs an assumed 30 in-cluster iterations per day.
  • Manual: 30 × 3 min = 90 minutes. Tilt: 30 × 10 s = 5 minutes. That's about 85 minutes per developer per day under these assumptions.

Your numbers will differ. Measure your own build and rollout times before you use a figure like this to justify the setup.

Less time spent locating failures. With ten services, a lot of debugging time goes to finding which pod is failing and why. Tilt's per-resource status and logs put the failing service and its error in one place. resource_deps also removes the crash loops caused by startup ordering, which otherwise look like real bugs.

Config bugs caught before a shared environment. Because the local environment applies the same Deployments, Services, probes and charts, mistakes like a wrong port, a misnamed Service or a broken readiness probe fail on the laptop. Otherwise they fail in a staging deploy, where the feedback is slower and other people may be blocked.

Faster onboarding. A Tiltfile that encodes the dependency graph, plus a bootstrap script for the cluster, replaces a long README of manual steps. A new engineer runs the script and tilt up. A tilt ci job keeps that path working.

These savings have a cost. Someone has to maintain the Tiltfile, the bootstrap script and the CI job, and engineers need machines that can run the cluster. If iterations are rare or builds are already fast, the maintenance can cost more than it saves.

Keeping a ten-service Tilt environment usable for a whole team

Make the UI and logs scannable

Ten services produce a lot of noise in one sidebar. Pass labels to k8s_resource and local_resource so the UI groups resources by domain, such as "payments", "infra", and "frontend". Engineers can then collapse what they aren't touching. Give each service a clear resource name, and keep startup logs quiet enough that a real error stands out. For expensive builds like a full frontend bundle or a protobuf regeneration, set trigger_mode=TRIGGER_MODE_MANUAL. Every save then marks the resource as pending instead of pinning the CPU, and the developer starts the rebuild when they are ready.

Test the environment itself

A Tiltfile that nobody runs in CI breaks quietly. Someone renames a chart value, and the next new hire loses a day to it. Add a CI job that runs tilt ci. It brings every resource up, waits for readiness, and exits non-zero on failure.

Lower onboarding friction

Ship one bootstrap script that creates the cluster and a local registry with fixed names. That way allow_k8s_contexts and image references match on every machine. Pick one cluster tool, such as kind or k3d, and test the script on macOS, Linux, and WSL2. Most onboarding failures come from differences between operating systems and cluster tools. Document a minimum RAM and CPU spec, because ten services plus a database will exhaust a small laptop.

Keep secrets out of the Tiltfile. Load them from a gitignored dev secrets file, and fail with a clear message when that file is missing.

Budget for ownership

The Tiltfile is a shared codebase. Give it an owner, review changes to it, and refactor it when it gets messy, the same as any other code.

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 kubernetes development, 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.