tilt

Tilt Development Skill

Overview

Tilt is a local Kubernetes development tool that provides:

• Live updates: Code changes sync instantly without full rebuilds
• Multi-service orchestration: Manage complex microservice environments
• Visual dashboard: Real-time status, logs, and debugging in browser UI
• Extensible: Plugin ecosystem for Helm, databases, and custom workflows

Announce at start: "I'm using the tilt skill to help with local Kubernetes development."

When to Use This Skill

Use this skill when users need to:

• Create or modify Tiltfiles (Starlark configuration)
• Set up live update/​hot-reload for Kubernetes development
• Debug multi-service applications locally
• Configure port forwards, resource dependencies, or build triggers
• Integrate Tilt with Helm, Kustomize, or custom build systems
• Troubleshoot Tilt errors or slow builds

Quick Start

Minimal Tiltfile

# Tiltfile - Place in project root
docker_build('my-app', '.')
k8s_yaml('k8s/​deployment.yaml')
k8s_resource('my-app', port_forwards='8080:8080')

Core Commands

tilt up              # Start development session (opens UI at localhost:10350)
tilt down            # Stop all resources
tilt logs -f <name>  # Stream logs for a resource
tilt trigger <name>  # Force rebuild of a resource
tilt ci              # Run once and exit (for CI/​CD)

Tiltfile Authoring

Tiltfiles use Starlark (Python-like) syntax. Key functions:

docker_build() - Build Container Images

# Basic build
docker_build('my-app', '.')

# With live updates (hot reload)
docker_build('my-app', '.',
  live_update=[
    sync('.', '/​app'),
    run('pip install -r requirements.txt', trigger='requirements.txt'),
  ])

# Custom Dockerfile
docker_build('my-app', '.', dockerfile='Dockerfile.dev')

# Build arguments
docker_build('my-app', '.', build_args={'NODE_ENV': 'development'})

# Ignore files (faster builds)
docker_build('my-app', '.', ignore=['node_modules', '*.md', 'tests/'])

k8s_yaml() - Deploy Kubernetes Manifests

# Single file
k8s_yaml('k8s/​deployment.yaml')

# Multiple files
k8s_yaml(['k8s/​deployment.yaml', 'k8s/​service.yaml'])

# Glob patterns
k8s_yaml(glob('k8s/​*.yaml'))

# Kustomize
k8s_yaml(kustomize('k8s/​overlays/​dev'))

# Helm
k8s_yaml(helm('charts/​my-app', values=['values-dev.yaml']))

k8s_resource() - Configure Resources

# Port forwarding
k8s_resource('my-app', port_forwards='8080:8080')
k8s_resource('my-app', port_forwards=['8080:8080', '9090:9090'])

# Resource dependencies (start database before app)
k8s_resource('my-app', resource_deps=['postgres'])

# Custom labels for grouping in UI
k8s_resource('my-app', labels=['backend'])

# Trigger mode (manual vs auto rebuild)
k8s_resource('my-app', trigger_mode=TRIGGER_MODE_MANUAL)

local_resource() - Non-Kubernetes Tasks

# Run local commands
local_resource('npm-install',
  cmd='npm install',
  deps=['package.json'])

# Build frontend locally
local_resource('frontend-build',
  cmd='npm run build',
  deps=['src/'],
  resource_deps=['npm-install'])

# Serve local documentation
local_resource('docs',
  serve_cmd='mkdocs serve',
  deps=['docs/'])

live_update - Hot Reloading

docker_build('my-app', '.',
  live_update=[
    # Sync files from host to container
    sync('./​src', '/​app/​src'),

    # Run command when specific files change
    run('pip install -r requirements.txt', trigger='requirements.txt'),
    run('npm install', trigger=['package.json', 'package-lock.json']),

    # Restart process in container (needs restart_process extension)
    restart_container(),
  ])

Live update requirements:

• Container must already be running
• Synced paths must exist in container
• For interpreted languages (Python, Node), often no restart needed
• For compiled languages, use restart_container() or rebuild

Multi-Service Development

Resource Dependencies

# Database must start before app
k8s_yaml('k8s/​postgres.yaml')
k8s_resource('postgres', port_forwards='5432:5432')

k8s_yaml('k8s/​app.yaml')
k8s_resource('app',
  port_forwards='8080:8080',
  resource_deps=['postgres'])

Environment Variables

# Read from .env file
env = read_file('.env')

# Pass to build
docker_build('my-app', '.',
  build_args={'API_KEY': os.getenv('API_KEY')})

# Or use Kubernetes ConfigMaps/​Secrets in your manifests

Workload Groups

# Group resources in UI
k8s_resource('api', labels=['backend'])
k8s_resource('worker', labels=['backend'])
k8s_resource('frontend', labels=['frontend'])
k8s_resource('postgres', labels=['data'])
k8s_resource('redis', labels=['data'])

Debugging

Tilt Commands

# View all resources and their status
tilt get

# Detailed resource info
tilt describe <resource-name>

# Stream logs
tilt logs -f <resource-name>

# Force rebuild
tilt trigger <resource-name>

# Open UI (if not already)
tilt up --web-mode=browser

Common Issues

Build context too large / slow builds:

# Add ignore patterns
docker_build('my-app', '.',
  ignore=['node_modules/', '.git/', '*.md', 'tests/', '__pycache__/'])

# Or use .dockerignore file

Live update not syncing:

# Verify paths match container structure
live_update=[
  sync('./​src', '/​app/​src'),  # Host path -> Container path
]

# Check container path exists
# Run: kubectl exec -it <pod> -- ls /​app/

Image pull backoff:

# Check image name in k8s manifest matches docker_build
# Verify cluster can pull from your registry
kubectl describe pod <pod-name>

Resource stuck in pending:

# Check Kubernetes events
kubectl get events --sort-by='.lastTimestamp'
kubectl describe pod <pod-name>

# Common causes: resource limits, missing secrets, PVC issues

Port forward not working:

# Ensure service selector matches pod labels
# Check port numbers match (host:container)
k8s_resource('app', port_forwards='8080:8080')

Debug Mode

# Verbose logging
tilt up --debug

# Print Tiltfile evaluation
tilt up --print-config

Extensions

Load extensions for additional functionality:

helm_resource - Deploy Helm Charts

load('ext://helm_resource', 'helm_resource', 'helm_repo')

# Add helm repository
helm_repo('bitnami', 'https://charts.bitnami.com/bitnami')

# Deploy chart
helm_resource('postgres', 'bitnami/​postgresql',
  flags=['--set=auth.postgresPassword=devpass'])

restart_process - In-Place Restart

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

# Automatically restart process on sync (for compiled languages)
docker_build_with_restart('my-go-app', '.',
  entrypoint='/​app/​server',
  live_update=[sync('./​build', '/​app')])

namespace - Multi-Namespace Support

load('ext://namespace', 'namespace_create', 'namespace_inject')

# Create namespace
namespace_create('my-dev')

# Inject namespace into all resources
namespace_inject('my-dev')

configmap - ConfigMap from Files

load('ext://configmap', 'configmap_create')

# Create ConfigMap from directory
configmap_create('app-config', from_file=glob('config/​*'))

secret - Secret from Files

load('ext://secret', 'secret_create_generic')

# Create Secret
secret_create_generic('db-creds',
  from_literal={'username': 'admin', 'password': 'secret'})

See all extensions: https://github.com/tilt-dev/tilt-extensions

Integration with Other Tools

With kubectl

# Tilt manages deployments, kubectl for inspection
kubectl get pods -w        # Watch pod status
kubectl logs -f <pod>      # Alternative to tilt logs
kubectl exec -it <pod> sh  # Shell into container

With Helm

# Option 1: Generate manifests
k8s_yaml(helm('charts/​my-app', values=['values-dev.yaml']))

# Option 2: Use helm_resource extension for full chart lifecycle
load('ext://helm_resource', 'helm_resource')
helm_resource('my-app', 'charts/​my-app')

With Kustomize

k8s_yaml(kustomize('k8s/​overlays/​dev'))

With kubernetes-expert Agent

Use the kubernetes-expert agent for:

• RBAC and security issues
• Network policy debugging
• Production deployment patterns
• Cluster-level troubleshooting

The Tilt skill focuses on local development workflows.

With DevSpace

Both Tilt and DevSpace serve similar purposes:

• Tilt: Starlark config, visual UI, extension ecosystem
• DevSpace: YAML config, sync-focused, devcontainers

Choose based on team preference. Both integrate with the same Kubernetes clusters.

Complete Example

# Tiltfile for a Python Flask + PostgreSQL application

# Load extensions
load('ext://helm_resource', 'helm_resource', 'helm_repo')
load('ext://restart_process', 'docker_build_with_restart')

# Database (using Helm)
helm_repo('bitnami', 'https://charts.bitnami.com/bitnami')
helm_resource('postgres', 'bitnami/​postgresql',
  flags=[
    '--set=auth.postgresPassword=devpass',
    '--set=auth.database=myapp',
  ],
  port_forwards='5432:5432',
  labels=['data'])

# Application with live updates
docker_build('myapp-api', './​api',
  live_update=[
    sync('./​api', '/​app'),
    run('pip install -r requirements.txt', trigger='requirements.txt'),
  ])

k8s_yaml('k8s/​api.yaml')
k8s_resource('api',
  port_forwards='8080:8080',
  resource_deps=['postgres'],
  labels=['backend'])

# Frontend (local development)
local_resource('frontend',
  serve_cmd='cd frontend && npm run dev',
  deps=['frontend/​src'],
  labels=['frontend'])

# Custom resource grouping
config.define_string_list('to-run', args=True)
cfg = config.parse()
groups = {
  'backend': ['postgres', 'api'],
  'frontend': ['frontend'],
  'all': ['postgres', 'api', 'frontend'],
}
resources = cfg.get('to-run', ['all'])
for r in resources:
  if r in groups:
    config.set_enabled_resources(groups[r])

API & Scripting

Tilt has a Kubernetes-style API server for programmatic access:

# List all API resources
tilt api-resources

# Get resource status as JSON
tilt get uiresources -o json

# Query specific resource
tilt get uiresource my-app -o jsonpath='{.status.runtimeStatus}'

# REST API (when Tilt is running)
curl http://localhost:10350/apis

Use for: CI health checks, metrics scraping, IDE integration, notifications.

See references/​api-scripting.md for full scripting examples.

Resources

• Official Docs: https://docs.tilt.dev/
• Tiltfile API: https://docs.tilt.dev/api.html
• Server API: https://api.tilt.dev/
• Extensions: https://github.com/tilt-dev/tilt-extensions
• Examples: https://github.com/tilt-dev/tilt-example-html

Reference Files

• references/​tiltfile-api.md - Condensed Tiltfile API reference
• references/​extensions.md - Popular extensions guide
• references/​api-scripting.md - API server & scripting examples