docktree.yml

Configuration reference for docktree.yml.

Docktree works with zero configuration — sensible defaults are provided. Create a docktree.yml in your repo root to customize behavior.

Full example

compose:
  files:
    - docker-compose.yml

worktrees:
  root: "../${repo}.worktrees"

setup:
  copy:
    - .env
  symlink:
    - node_modules
  run:
    - echo "worktree ready"

shared:
  services:
    postgres:
      kind: postgres
      tenancy: per_database

volumes:
  share:
    - shared_data

ports:
  bind_host: 127.0.0.1
  range: 41000-49999

state:
  directory: .docktree

transforms:
  container_name: strip
  built_image: rewrite
  docker_socket: warn

proxy:
  port: 8320
  host: 127.0.0.1
  tld: localhost

tunnel:
  provider: cloudflare
  port: 0

Reference

Section	Key	Default	Purpose
compose.files	—	auto-detected	Explicit compose file list
worktrees.root	—	../${repo}.worktrees	Where new worktrees are created (supports ${repo}, ${branch}, ${branch_slug})
setup.copy	—	[".env"]	Files copied from main repo to each worktree
setup.symlink	—	["node_modules"]	Symlinks created in worktrees pointing to main repo
setup.run	—	—	Shell commands run during setup
shared.services	—	—	Platform-tier shared services (kind: postgres/mysql/mongodb/redis/s3/generic; tenancy: per_database/full_share)
volumes.share	—	—	Volumes shared across all worktrees
ports.bind_host	—	127.0.0.1	Host interface for port bindings
ports.range	—	41000-49999	Port allocation range
state.directory	—	.docktree	Where Docktree stores instance state
transforms.*	—	strip/rewrite/warn	How container names, built images, docker sockets are transformed
proxy.port	—	8320	Reverse proxy listen port
proxy.host	—	127.0.0.1	Reverse proxy listen host
proxy.tld	—	localhost	Top-level domain for routing (e.g. localhost, test)
tunnel.provider	—	cloudflare	Default tunnel provider (cloudflare or ngrok)
tunnel.port	—	0	Default local port to tunnel (0 dynamically detects first HTTP port)

Shared services

Shared services run once at the platform tier and serve all worktrees. Supported kinds: postgres, mysql, mongodb, redis, s3, generic.

Tenancy modes:

• per_database — each worktree gets its own database namespace within a shared instance
• full_share — all worktrees share the same data

See the platform command for managing the platform stack.