What are Tilt and Docker Compose, and how does each one work?

Docker Compose is a declarative format and CLI for multi-container applications. A YAML file lists services, the images they use or the build contexts they come from, plus the networks, volumes, ports and environment each one gets. docker compose up hands that model to a single Docker engine, which creates the containers on a shared network where services find each other by name. Compose starts things and keeps them running. It does not know how your code changes over time.

Tilt focuses on the change loop. It reads a Tiltfile written in Starlark, a Python-like configuration language, so build and deploy logic can use functions, loops and conditionals instead of copy-pasted blocks. Tilt watches your source, rebuilds images or syncs changed files into running containers, applies Kubernetes manifests (raw YAML, Helm or Kustomize output) to a cluster, and shows logs and build status for every resource in one UI. The cluster is usually local, such as kind, k3d, minikube or Docker Desktop's Kubernetes. Tilt can also load a Compose file and manage those services, so it does not require Kubernetes.

Docker Compose:
  source ──> docker compose up ──> Docker engine ──> containers

Tilt:
  source ──> Tilt (watches files)
               ├─ image build ──> push/load ──┐
               └─ file sync (live update) ────┴──> local k8s cluster ──> pods

The difference matters for ten services. Compose describes the system as it runs. Tilt adds what happens each time you edit one of those ten services.

 DOCKER COMPOSE
 ┌──────────────┐   ┌──────────────────┐   ┌───────────────┐   ┌────────────┐
 │ source +     │──>│ docker compose up│──>│ Docker engine │──>│ containers │
 │ compose.yaml │   └──────────────────┘   └───────────────┘   │ (1 network)│
 └──────────────┘                                              └────────────┘

 TILT
 ┌──────────────┐   ┌───────────────────┐
 │ source +     │──>│ Tilt              │
 │ Tiltfile     │   │ watches files,    │
 └──────────────┘   │ syncs or rebuilds │
                    └─────────┬─────────┘
               ┌──────────────┴──────────────┐
               v                             v
     ┌───────────────────┐         ┌───────────────────┐
     │ image build       │         │ file sync         │
     │ (docker build)    │         │ (live update)     │
     └─────────┬─────────┘         └─────────┬─────────┘
               v                             │
     ┌───────────────────┐                   │
     │ push / load image │                   │
     └─────────┬─────────┘                   │
               v                             v
     ┌─────────────────────────────────────────────────┐
     │ local Kubernetes cluster (kind, k3d, minikube)  │
     │ manifests applied: YAML / Helm / Kustomize      │
     │ ──> pods, one per service                       │
     └─────────────────────────────────────────────────┘

Compose hands a static service model to one Docker engine, while Tilt watches source and either rebuilds images or syncs files into pods running on a local Kubernetes cluster.

How does it work when you run it?

With Compose, docker compose up reads the file, derives a project name (by default from the directory name), and creates a project network. It then builds or pulls each image and starts the containers in the order implied by depends_on. Each service gets a DNS name on that network equal to its service name, so orders reaches Postgres at postgres:5432. After that, Compose is mostly passive. It applies restart policies, and running up again recreates only the containers whose configuration or image changed.

With Tilt, tilt up evaluates the Tiltfile once to build a list of resources. Each resource is an image build plus the Kubernetes objects or Compose service that uses it. Tilt then runs a control loop. It watches the files each build depends on, ignoring paths listed in .tiltignore. When a file changes, it decides whether to live-update the running container or rebuild the image. For a rebuild, it injects the new image tag into the manifests and re-applies them, then tracks the resulting pods until they are ready. If you edit the Tiltfile itself, Tilt re-evaluates it and reconciles the difference. Status and logs for every resource stream to a web UI, which is served locally on port 10350 by default, and to the terminal.

How does the edit-to-running-code loop differ between Tilt and Compose?

For most teams the inner loop decides the choice. Runtime config matters less, because ten services in steady state look much the same under either tool. What you feel all day is the gap between saving a file and seeing the change in a running process.

Compose gives you two paths. The fast one bind-mounts your source directory into the container and relies on a watcher inside it, such as nodemon, air or a framework's reload mode, to restart the process. The slow one rebuilds the image and recreates the container. That can cost tens of seconds per edit, longer if dependency layers get invalidated.

Tilt's live_update targets the second path on Kubernetes. Instead of rebuilding and redeploying, Tilt copies changed files into the running container with sync() steps and can follow up with run(), for example to reinstall dependencies when a lockfile changes. fall_back_on() lists files that should force a full rebuild instead. This is how hot reload works against pods.

There are caveats:

  • Compiled languages still need a build step. You either compile inside the container through run() or cross-compile locally and sync the binary.
  • Silent staleness. If a sync() destination doesn't match the container's working directory, or a file that needs a rebuild isn't covered by fall_back_on(), the pod keeps running old code. Tilt reports nothing wrong.
  • macOS and Windows. Bind mounts cross a VM boundary, so file I/O can be slow. Change notifications may not reach the in-container watcher, depending on your Docker setup, which pushes some teams to polling. Tilt copies files into the container, so it avoids depending on the bind mount, but a sync step still runs on every save.
services:
  orders:
    build: ./orders
    working_dir: /app
    volumes:
      - ./orders:/app          # host source appears inside the container
      - /app/node_modules      # keep the image's node_modules, not the host's
    # nodemon restarts the process on change. --legacy-watch switches to
    # polling, for setups where file events don't cross the VM boundary.
    command: npx nodemon --legacy-watch src/index.js

k8s_yaml('k8s/orders.yaml')

docker_build(
    'orders-image',            # must match the image name in k8s/orders.yaml
    './orders',
    live_update=[
        # fall_back_on steps must come first: these files force a full rebuild.
        fall_back_on(['./orders/Dockerfile']),
        # Destination must match the container's WORKDIR, or the pod
        # silently keeps running old code.
        sync('./orders', '/app'),
        # Reinstall dependencies only when the manifest changes.
        run('npm install', trigger=['./orders/package.json']),
    ],
)

k8s_resource('orders', port_forwards=8080)

The same Node service wired two ways: Compose bind-mounts the source and lets nodemon restart the process, and Tilt syncs changed files into the running pod, falling back to a full rebuild when the Dockerfile changes.

How do you model ten services in a Compose file and a Tiltfile?

Compose: one file, startup ordering, profiles

In Compose, each of the ten services is a block with its build context, ports and environment. Dependencies go in depends_on using the long form. For example, condition: service_healthy makes orders wait until the postgres healthcheck passes. Profiles split the system. Services tagged profiles: [payments] stay off unless you pass --profile payments, and untagged services always start.

depends_on only controls startup. Compose checks readiness once, when it launches the dependent. If Postgres restarts an hour later, Compose does nothing, and orders either reconnects or fails quietly. Kubernetes has no startup ordering, so a pod has to tolerate a dependency that is missing at boot or that disappears later. Strict ordering gives you clean local startups, but it can hide missing retry logic until staging. If you drop depends_on locally, those retry bugs show up on your laptop, and your logs get noisier.

Tilt: a Starlark program

A Tiltfile is code, so you don't write ten blocks. You loop over a list of service names. For each one, you call docker_build, or custom_build when the image comes from a tool like Bazel or ko. Manifests come in through k8s_yaml, either from plain files or from Helm output via helm(). After loading the manifests, k8s_resource sets the developer-facing details for each service: port_forwards exposes ports locally, resource_deps delays updates until a dependency is ready, and labels groups services in the UI.

Because the Tiltfile is a program, it can grow conditionals, helper functions and environment detection. Over time it can turn into an untested build system that only one person understands. Treat it like production code: keep functions small, review changes, and have someone other than the author run it.

SERVICES = [
    {'name': 'orders',    'port': 8081, 'deps': ['postgres'],         'group': 'core'},
    {'name': 'inventory', 'port': 8082, 'deps': ['postgres'],         'group': 'core'},
    {'name': 'payments',  'port': 8083, 'deps': ['orders'],           'group': 'payments'},
    {'name': 'gateway',   'port': 8080, 'deps': ['orders', 'inventory'], 'group': 'edge'},
    # ...remaining services follow the same shape
]

k8s_yaml(helm('charts/postgres', name='postgres'))
k8s_resource('postgres', labels=['infra'])

def register_service(svc):
    name = svc['name']
    # Image ref must match the image used in the service's manifest
    # so Tilt can swap in the freshly built tag.
    docker_build('example.local/' + name, 'services/' + name)
    k8s_yaml('services/' + name + '/k8s.yaml')
    k8s_resource(
        name,
        port_forwards=svc['port'],     # reachable at localhost:<port>
        resource_deps=svc['deps'],     # wait for deps to be ready before updating
        labels=[svc['group']],         # group related services in the Tilt UI
    )

for svc in SERVICES:
    register_service(svc)

A Tiltfile that loops over a service list, calls docker_build and k8s_yaml for each service, loads Postgres from a Helm chart, and uses k8s_resource to set port forwards, resource_deps and UI labels.

How can you run only part of a ten-service system locally?

Most days you are changing one or two services, not ten. Running the other eight costs RAM, CPU and startup time without improving your feedback loop.

Compose: profiles and named services

Assign rarely touched services to a profile, such as profiles: ["billing"]. Plain docker compose up then skips them, and docker compose --profile billing up includes them when you need them. For one-off subsets, name the services: docker compose up orders inventory. Compose still starts anything those services list under depends_on, so the dependency graph you declared earlier sets how small "small" can get. Adding --no-deps skips that, which helps when a dependency is already running.

Tilt: named resources and manual triggers

tilt up orders inventory starts only those resources. Tilt does not pull in dependencies automatically, so you choose what runs. For services you want available but not rebuilt on every save, set trigger_mode=TRIGGER_MODE_MANUAL on the resource and run tilt trigger payments when you actually want a rebuild. Setting auto_init=False keeps a resource idle until you trigger it. To drop a dependency entirely, point it elsewhere with config. For example, set the service's upstream URL from a Tiltfile argument so it can target a shared staging instance or a local stub.

The part neither tool decides

If all ten services don't fit on a developer laptop, someone has to decide which dependencies get stubbed, who maintains those stubs, and which shared environment is safe for local traffic. Those are organizational decisions. Compose and Tilt only carry out whatever your team decides.

docker compose up -d

docker compose --profile billing up -d

docker compose up -d orders inventory

docker compose up -d --no-deps orders

tilt up orders inventory

tilt trigger payments

PAYMENTS_URL= tilt up orders

Commands for running a subset of services: Compose profiles, named services and --no-deps, then Tilt named resources, a manual trigger, and an environment variable that points a dependency at a shared or stubbed service.

Dev/prod parity, debugging visibility and laptop resource cost

Once those decisions are made, three factors drive what the setup costs day to day.

Parity

Tilt can deploy the same Kubernetes manifests or Helm charts you ship. That means a failing readiness probe, a missing ConfigMap key, a DNS name that only resolves in-cluster, or a memory limit that OOM-kills a service shows up on a laptop instead of in staging. The parity is partial, though. Dev overrides accumulate in the Tiltfile and drift from production in their own way: debug images, single replicas, disabled sidecars, skipped init containers.

Compose has no link to production manifests. It is a second description of the system, so every new env var, port or dependency has to be changed in two places or the two descriptions diverge.

Visibility

Tilt's web and terminal UIs show build status, runtime status and logs per resource in one view. That matters when one of ten services is crash-looping. Compose offers docker compose logs and docker compose ps with service-name filters. These work, but you assemble the overall picture yourself.

Resources

Illustrative estimate (assumed numbers, not a benchmark)

Total RAM = (N × per-service) + database + broker + cluster overhead

  • Compose: (10 × 300 MB) + 1,000 MB + 500 MB + 0 ≈ 4.5 GB
  • Tilt on kind, k3d or minikube: the same workload + an assumed 1,000 MB for the control plane ≈ 5.5 GB

Measure the real figures on your own hardware with docker stats before deciding.

Factor Tilt Docker Compose
Parity Reuses real manifests; dev overrides drift Parallel description; drifts from production
Visibility Unified per-resource UI logs and ps with filters
Overhead Workload + local cluster Workload only

How can Tilt or Compose save engineering time?

Both tools save time in the same places: the edit loop, environment setup, and finding the failing service. They differ in how much of each they cover.

  • Shorter edit loop. The largest recurring cost is waiting after each save. Compose with a bind mount and an in-container watcher already restarts in seconds for interpreted languages. Tilt's live_update brings that behaviour to services running in Kubernetes, where the default otherwise is rebuilding the image, pushing or loading it, and rolling the pod. Removing that rebuild from most edits is where Tilt's savings come from.
  • One-command onboarding. A checked-in Compose file or Tiltfile replaces a wiki page of setup steps. A new engineer runs docker compose up or tilt up and gets the same ten services everyone else runs. This only holds if the file is maintained, and for Tilt the local cluster setup has to be scripted too.
  • Less time hunting for the broken service. With ten services, a lot of debugging time goes into working out which one failed. Tilt's per-resource status and logs make that visible right away. With Compose you get there through docker compose ps and filtered docker compose logs.
  • Running less. Profiles, named services and manual triggers keep the machine from rebuilding or hosting services you aren't touching. That reduces startup time and resource contention.
  • Earlier failure detection. Running real manifests locally under Tilt surfaces probe, config and resource-limit mistakes before a pull request reaches staging, so you avoid a slower round trip through CI and a shared environment.

Illustrative estimate (assumed numbers, not a benchmark):

daily wait time per engineer = edits per day × seconds per edit ÷ 60

Assume 60 edits per day. Under a rebuild-and-redeploy loop, assume each edit costs 40 seconds. With live update, assume each costs 5 seconds:

  • Rebuild loop: 60 × 40 ÷ 60 = 40 minutes per day
  • Live update: 60 × 5 ÷ 60 = 5 minutes per day

If your current loop already uses bind mounts and an in-process reloader, the gap may be close to zero. Time your own loop before counting on savings.

When should you avoid Tilt, and what does adopting it really cost?

Tilt's fast loop assumes a working local Kubernetes cluster, and that is where onboarding usually breaks. New engineers hit cluster creation failures. Or the local registry is missing or misconfigured, so built images never reach the nodes. Or a kubectl context still points at a shared staging cluster, or the VM is capped at too little memory to schedule ten services. Each problem is solvable, but each one tends to land on someone's first day. If you don't deploy to Kubernetes, or most engineers only touch one or two services, Tilt adds that setup burden without much benefit.

The Tiltfile is also code. It is Starlark, it accumulates conditionals, and it needs an owner who reviews changes and fixes it when manifests move. Without that owner it decays faster than static YAML. Compose needs only Docker, and almost every engineer can read it. Its weakness is that once you need logic, teams bolt on Makefiles and shell wrappers, which become unowned code of a different kind.

Switching has concrete costs:

  • Both configs coexist during the transition and drift apart.
  • People need retraining.
  • CI pipelines still invoke Compose for integration tests.

Illustrative estimate (assumed numbers, not a benchmark):

break-even weeks = one-time migration hours ÷ (engineers × minutes saved per day × 5 ÷ 60 − weekly upkeep hours)

Assume 80 migration hours, 8 engineers, 5 minutes saved per engineer per day, and 1 hour per week of Tiltfile upkeep:

80 ÷ (8 × 5 × 5 ÷ 60 − 1) = 80 ÷ 2.33 ≈ 34 weeks

Measure your current loop time before assuming the savings exist.

Who should use Tilt, and who should use Docker Compose?

Docker Compose fits:

  • Teams whose production target is not Kubernetes, such as plain container hosts or managed container services configured outside Kubernetes manifests.
  • Teams where most engineers work in one or two services and need the rest only as running dependencies.
  • Projects in interpreted languages, where a bind mount and an in-process reloader already give a fast loop.
  • Teams that want the lowest setup cost and a config almost everyone can read and edit, including people who rarely touch infrastructure.
  • CI integration tests that need the whole system up, then torn down.

Tilt fits:

  • Teams that deploy to Kubernetes and want local runs to use the same manifests or Helm charts, so probe, config and limit mistakes show up early.
  • Engineers whose changes often span several services at once and who need all of them updating together.
  • Teams whose main complaint is waiting on image rebuilds and redeploys after every edit.
  • Teams with at least one person willing to own the Tiltfile and the local cluster setup.

Neither fits well when the full system doesn't fit on a laptop, or when local runs depend on data or services that only exist in a shared environment. In that case, the remote options in the next section matter more than the choice between these two.

What are the alternatives to Tilt and Docker Compose?

  • Compose's own file watching. Recent Compose releases support a develop section with watch rules, run with docker compose watch. Each rule maps a host path to an action: sync files into the container, sync and restart the container, or rebuild the image. This covers part of Tilt's live-update loop without Kubernetes. Check that your installed Compose version supports it before relying on it.
  • Plain scripts around kubectl and Helm. A Makefile or shell script that builds an image, loads it into the local cluster and runs kubectl apply or helm upgrade. It has no file watching or live update, and you own all the glue, but it has no new tool to learn.
  • Other Kubernetes inner-loop tools. Several tools follow the same pattern as Tilt: watch source, rebuild or sync, redeploy to a cluster. They differ in configuration format and in how much they also cover CI and deployment. Evaluate them against the same criteria used here: live-update reliability, parity with production manifests, and who maintains the config.
  • Running services natively on the host. Run the one or two services you're editing directly with their language tooling and debugger. Keep databases, brokers and the remaining services in Compose, then point the native processes at them through environment variables. This often gives the fastest loop and the simplest debugging, at the cost of less parity, because the native process doesn't run in its production image.
  • Remote or shared development clusters. Run the system in a cluster that a team owns, and either deploy your changed services into a personal namespace or route traffic from the cluster to a process on your laptop. This removes the laptop resource ceiling and adds network latency, cluster cost and an ownership burden.

Which should your team choose: Tilt, Docker Compose, or a hybrid?

The decision comes down to where production runs, how often changes cross service boundaries, and what your team already knows. Answer those three before comparing features.

Criterion Recommendation Why
Production is not Kubernetes Docker Compose Tilt's main advantage is reusing Kubernetes manifests. Without Kubernetes in production, you add a layer and gain no parity.
Few services, or services rarely change together Docker Compose Restarting one container is already fast, so live update has little latency to remove.
Team has little Kubernetes experience Docker Compose When a pod is stuck in a crash loop, the developer has to debug the cluster before the code.
Production is Kubernetes, cross-service changes are frequent, rebuild-and-redeploy latency is the top complaint Tilt Live update and a single dashboard target exactly that pain. The Tiltfile pays for itself.

The choice does not have to be all-or-nothing:

  • Hybrid. Keep Postgres, Redis and the message broker in Compose, and let Tilt manage only the application services. Backing stores rarely change, and they gain nothing from live update. Keeping them out of the cluster also cuts the memory and restart overhead covered earlier.
  • Tilt driving your existing Compose file. Tilt can load a Compose file directly. You get the dashboard and file watching right away, then move services to Kubernetes manifests one at a time. This spreads the migration hours from the estimate above across several sprints.
  • Shared remote dev environment. If ten services no longer fit on a laptop, neither tool solves the problem. Moving the workload to a remote cluster does, but it costs network latency and requires someone to own that cluster.

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 vs docker compose, 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.