While running multiple agents and git worktrees with a Docker Compose setup, I kept running into host port, container name, and volume collisions. Before building this tool, I tried some combinations of -p to namespace the projects/hash the worktree path for a unique name, managing .env files with port variables and Caddy for reverse-proxying, but I still had some issues getting everything to play together automatically without me making any changes to my compose files or thinking about it. I also tried a bunch of tools that try to address this but you end up with a Docker-in-docker setup, or they requires you to rewrite your compose files.
Docktree solves these issues by dynamically generating Compose overrides without editing your compose file. It auto-allocates unique host ports, isolates networks and named volumes, and rewrites explicit container names so different branches of the same stack run simultaneously without manual tweaks. There's also an option where, for certain services like postgres/mysql that support "logical isolation" you can have only one database container, and run multiple databases in them isolated instead of isolated containers.
The CLI features a built-in reverse proxy that handles routing by hostname automatically (accessing apps via http://<worktree-name>.localhost), Cloudflare/ngrok sharing tunnels to expose worktrees externally. These are pretty useful since I can just have agents work on something end to end and return me a link I can use to investigate their work or they can send me screenshots/walkthroughs when combined with something like Vercel's agent-browser. Tool also has two skills and --json outputs for your agents to autonomously drive them. These are still containers at the end of day though so the existing docker tools agents are familiar with work out of the box.
- Repository: https://github.com/Bnjoroge1/docktree - Website: https://docktree.dev