Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs: add Caddy subdomain routing pattern (#676)

Maximilian Roos01b2b8bf8d71
diff --git a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md
index 4ddf544c5..9210ab308 100644
--- a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md
+++ b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md
@@ -52,13 +52,6 @@ The URL column in `wt list` shows each worktree's dev server:
Ports are deterministic — `fix-auth` always gets port 16460, regardless of which machine or when. The URL dims if the server isn't running.
-For subdomain-based routing (useful for cookies and CORS), use `lvh.me` which resolves to 127.0.0.1:
-
-```toml
-[post-start]
-server = "npm run dev -- --host {{ branch | sanitize }}.lvh.me --port {{ branch | hash_port }}"
-```
-
## Database per worktree
Each worktree can have its own isolated database. Docker containers get unique names and ports:
@@ -248,6 +241,41 @@ To create a worktree and immediately attach:
wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'
```
+## Subdomain routing with Caddy
+<!-- Hand-tested 2025-01-15 -->
+
+Clean URLs like `http://feature-auth.myproject.lvh.me` without port numbers. Useful for cookies, CORS, and matching production URL structure.
+
+**Prerequisites:** [Caddy](https://caddyserver.com/docs/install) (`brew install caddy`)
+
+```toml
+# .config/wt.toml
+[post-start]
+server = "npm run dev -- --port {{ branch | hash_port }}"
+proxy = """
+ curl -sf --max-time 0.5 http://localhost:2019/config/ || caddy start
+ curl -sf http://localhost:2019/config/apps/http/servers/wt || \
+ curl -sfX PUT http://localhost:2019/config/apps/http/servers/wt -H 'Content-Type: application/json' \
+ -d '{"listen":[":8080"],"automatic_https":{"disable":true},"routes":[]}'
+ curl -sf -X DELETE http://localhost:2019/id/wt:{{ repo }}:{{ branch | sanitize }} || true
+ curl -sfX PUT http://localhost:2019/config/apps/http/servers/wt/routes/0 -H 'Content-Type: application/json' \
+ -d '{"@id":"wt:{{ repo }}:{{ branch | sanitize }}","match":[{"host":["{{ branch | sanitize }}.{{ repo }}.lvh.me"]}],"handle":[{"handler":"reverse_proxy","upstreams":[{"dial":"127.0.0.1:{{ branch | hash_port }}"}]}]}'
+"""
+
+[pre-remove]
+proxy = "curl -sf -X DELETE http://localhost:2019/id/wt:{{ repo }}:{{ branch | sanitize }} || true"
+
+[list]
+url = "http://{{ branch | sanitize }}.{{ repo }}.lvh.me:8080"
+```
+
+**How it works:**
+
+1. `wt switch --create feature-auth` runs the `post-start` hook, starting the dev server on a deterministic port (`{{ branch | hash_port }}` → 16460)
+2. The hook starts Caddy if needed and registers a route using the same port: `feature-auth.myproject` → `localhost:16460`
+3. `lvh.me` is a public domain with wildcard DNS — `*.lvh.me` resolves to `127.0.0.1`
+4. Visiting `http://feature-auth.myproject.lvh.me:8080`: Caddy matches the subdomain and proxies to the dev server
+
## Bare repository layout
An alternative to the default sibling layout (`myproject.feature/`) uses a bare repository with worktrees as subdirectories:
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index fba3f89d9..6fd6e0e5b 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -64,13 +64,6 @@ The URL column in `wt list` shows each worktree's dev server:
Ports are deterministic — `fix-auth` always gets port 16460, regardless of which machine or when. The URL dims if the server isn't running.
-For subdomain-based routing (useful for cookies and CORS), use `lvh.me` which resolves to 127.0.0.1:
-
-```toml
-[post-start]
-server = "npm run dev -- --host {{ branch | sanitize }}.lvh.me --port {{ branch | hash_port }}"
-```
-
## Database per worktree
Each worktree can have its own isolated database. Docker containers get unique names and ports:
@@ -260,6 +253,41 @@ To create a worktree and immediately attach:
wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'
```
+## Subdomain routing with Caddy
+<!-- Hand-tested 2025-01-15 -->
+
+Clean URLs like `http://feature-auth.myproject.lvh.me` without port numbers. Useful for cookies, CORS, and matching production URL structure.
+
+**Prerequisites:** [Caddy](https://caddyserver.com/docs/install) (`brew install caddy`)
+
+```toml
+# .config/wt.toml
+[post-start]
+server = "npm run dev -- --port {{ branch | hash_port }}"
+proxy = """
+ curl -sf --max-time 0.5 http://localhost:2019/config/ || caddy start
+ curl -sf http://localhost:2019/config/apps/http/servers/wt || \
+ curl -sfX PUT http://localhost:2019/config/apps/http/servers/wt -H 'Content-Type: application/json' \
+ -d '{"listen":[":8080"],"automatic_https":{"disable":true},"routes":[]}'
+ curl -sf -X DELETE http://localhost:2019/id/wt:{{ repo }}:{{ branch | sanitize }} || true
+ curl -sfX PUT http://localhost:2019/config/apps/http/servers/wt/routes/0 -H 'Content-Type: application/json' \
+ -d '{"@id":"wt:{{ repo }}:{{ branch | sanitize }}","match":[{"host":["{{ branch | sanitize }}.{{ repo }}.lvh.me"]}],"handle":[{"handler":"reverse_proxy","upstreams":[{"dial":"127.0.0.1:{{ branch | hash_port }}"}]}]}'
+"""
+
+[pre-remove]
+proxy = "curl -sf -X DELETE http://localhost:2019/id/wt:{{ repo }}:{{ branch | sanitize }} || true"
+
+[list]
+url = "http://{{ branch | sanitize }}.{{ repo }}.lvh.me:8080"
+```
+
+**How it works:**
+
+1. `wt switch --create feature-auth` runs the `post-start` hook, starting the dev server on a deterministic port (`{{ branch | hash_port }}` → 16460)
+2. The hook starts Caddy if needed and registers a route using the same port: `feature-auth.myproject` → `localhost:16460`
+3. `lvh.me` is a public domain with wildcard DNS — `*.lvh.me` resolves to `127.0.0.1`
+4. Visiting `http://feature-auth.myproject.lvh.me:8080`: Caddy matches the subdomain and proxies to the dev server
+
## Bare repository layout
An alternative to the default sibling layout (`myproject.feature/`) uses a bare repository with worktrees as subdirectories: