Skip to content

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

docs: use .localhost subdomains instead of .lvh.me for Caddy routing (#1343)

worktrunk-bot2e29a275ddd5
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 3a85e66ab..816490016 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -240,7 +240,7 @@ The `sanitize` filter makes branch names safe for filesystem paths. The `sanitiz
```toml
[post-start]
-dev = "npm run dev -- --host {{ branch }}.lvh.me --port {{ branch | hash_port }}"
+dev = "npm run dev -- --host {{ branch }}.localhost --port {{ branch | hash_port }}"
```
Hash any string, including concatenations:
@@ -346,11 +346,11 @@ The port is stable across machines and restarts — `feature-api` always gets th
url = "http://localhost:{{ branch | hash_port }}"
```
-For subdomain-based routing (useful for cookies/CORS), use `lvh.me` which resolves to 127.0.0.1:
+For subdomain-based routing (useful for cookies/CORS), use `.localhost` subdomains which resolve to 127.0.0.1:
```toml
[post-start]
-server = "npm run dev -- --host {{ branch | sanitize }}.lvh.me --port {{ branch | hash_port }}"
+server = "npm run dev -- --host {{ branch | sanitize }}.localhost --port {{ branch | hash_port }}"
```
### Databases
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index 3e3464701..610aefc0d 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -268,9 +268,9 @@ wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'
```
## Subdomain routing with Caddy
-<!-- Hand-tested 2025-01-15 -->
+<!-- Hand-tested 2026-03-07 -->
-Clean URLs like `http://feature-auth.myproject.lvh.me` without port numbers. Useful for cookies, CORS, and matching production URL structure.
+Clean URLs like `http://feature-auth.myproject.localhost` without port numbers. Useful for cookies, CORS, and matching production URL structure.
**Prerequisites:** [Caddy](https://caddyserver.com/docs/install) (`brew install caddy`)
@@ -285,22 +285,22 @@ proxy = """
-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 }}"}]}]}'
+ -d '{"@id":"wt:{{ repo }}:{{ branch | sanitize }}","match":[{"host":["{{ branch | sanitize }}.{{ repo }}.localhost"]}],"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"
+url = "http://{{ branch | sanitize }}.{{ repo }}.localhost: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
+3. `*.localhost` resolves to `127.0.0.1` via the OS
+4. Visiting `http://feature-auth.myproject.localhost:8080`: Caddy matches the subdomain and proxies to the dev server
## Monitor hook logs
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index c1bf5245b..55b402098 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -231,7 +231,7 @@ The `sanitize` filter makes branch names safe for filesystem paths. The `sanitiz
```toml
[post-start]
-dev = "npm run dev -- --host {{ branch }}.lvh.me --port {{ branch | hash_port }}"
+dev = "npm run dev -- --host {{ branch }}.localhost --port {{ branch | hash_port }}"
```
Hash any string, including concatenations:
@@ -337,11 +337,11 @@ The port is stable across machines and restarts — `feature-api` always gets th
url = "http://localhost:{{ branch | hash_port }}"
```
-For subdomain-based routing (useful for cookies/CORS), use `lvh.me` which resolves to 127.0.0.1:
+For subdomain-based routing (useful for cookies/CORS), use `.localhost` subdomains which resolve to 127.0.0.1:
```toml
[post-start]
-server = "npm run dev -- --host {{ branch | sanitize }}.lvh.me --port {{ branch | hash_port }}"
+server = "npm run dev -- --host {{ branch | sanitize }}.localhost --port {{ branch | hash_port }}"
```
### Databases
diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.md
index 9e73ff42a..62b726d43 100644
--- a/skills/worktrunk/reference/tips-patterns.md
+++ b/skills/worktrunk/reference/tips-patterns.md
@@ -257,9 +257,9 @@ wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'
```
## Subdomain routing with Caddy
-<!-- Hand-tested 2025-01-15 -->
+<!-- Hand-tested 2026-03-07 -->
-Clean URLs like `http://feature-auth.myproject.lvh.me` without port numbers. Useful for cookies, CORS, and matching production URL structure.
+Clean URLs like `http://feature-auth.myproject.localhost` without port numbers. Useful for cookies, CORS, and matching production URL structure.
**Prerequisites:** [Caddy](https://caddyserver.com/docs/install) (`brew install caddy`)
@@ -274,22 +274,22 @@ proxy = """
-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 }}"}]}]}'
+ -d '{"@id":"wt:{{ repo }}:{{ branch | sanitize }}","match":[{"host":["{{ branch | sanitize }}.{{ repo }}.localhost"]}],"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"
+url = "http://{{ branch | sanitize }}.{{ repo }}.localhost: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
+3. `*.localhost` resolves to `127.0.0.1` via the OS
+4. Visiting `http://feature-auth.myproject.localhost:8080`: Caddy matches the subdomain and proxies to the dev server
## Monitor hook logs
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 3e9bdfd48..fc7d3b1b0 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1281,7 +1281,7 @@ The `sanitize` filter makes branch names safe for filesystem paths. The `sanitiz
```toml
[post-start]
-dev = "npm run dev -- --host {{ branch }}.lvh.me --port {{ branch | hash_port }}"
+dev = "npm run dev -- --host {{ branch }}.localhost --port {{ branch | hash_port }}"
```
Hash any string, including concatenations:
@@ -1387,11 +1387,11 @@ The port is stable across machines and restarts — `feature-api` always gets th
url = "http://localhost:{{ branch | hash_port }}"
```
-For subdomain-based routing (useful for cookies/CORS), use `lvh.me` which resolves to 127.0.0.1:
+For subdomain-based routing (useful for cookies/CORS), use `.localhost` subdomains which resolve to 127.0.0.1:
```toml
[post-start]
-server = "npm run dev -- --host {{ branch | sanitize }}.lvh.me --port {{ branch | hash_port }}"
+server = "npm run dev -- --host {{ branch | sanitize }}.localhost --port {{ branch | hash_port }}"
```
### Databases
diff --git a/tests/integration_tests/doc_templates.rs b/tests/integration_tests/doc_templates.rs
index aa6d0da09..7ac65f4a6 100644
--- a/tests/integration_tests/doc_templates.rs
+++ b/tests/integration_tests/doc_templates.rs
@@ -396,20 +396,20 @@ fn test_doc_example_database_url(repo: TestRepo) {
#[rstest]
fn test_doc_example_dev_server(repo: TestRepo) {
// From docs/content/hook.md lines 168-170:
- // dev = "npm run dev -- --host {{ branch }}.lvh.me --port {{ branch | hash_port }}"
+ // dev = "npm run dev -- --host {{ branch }}.localhost --port {{ branch | hash_port }}"
let repository = Repository::at(repo.root_path()).unwrap();
let mut vars = HashMap::new();
vars.insert("branch", "feature-auth");
- let template = "npm run dev -- --host {{ branch }}.lvh.me --port {{ branch | hash_port }}";
+ let template = "npm run dev -- --host {{ branch }}.localhost --port {{ branch | hash_port }}";
let result = expand_template(template, &vars, false, &repository, "test").unwrap();
let expected_port = hash_port("feature-auth");
assert_eq!(
result,
- format!("npm run dev -- --host feature-auth.lvh.me --port {expected_port}")
+ format!("npm run dev -- --host feature-auth.localhost --port {expected_port}")
);
}
diff --git a/tests/integration_tests/shell_wrapper.rs b/tests/integration_tests/shell_wrapper.rs
index 8dd997a5d..42856c76c 100644
--- a/tests/integration_tests/shell_wrapper.rs
+++ b/tests/integration_tests/shell_wrapper.rs
@@ -739,6 +739,9 @@ const STANDARD_TEST_ENV: &[(&str, &str)] = &[
("LANG", "C"),
("LC_ALL", "C"),
("WORKTRUNK_TEST_EPOCH", "1735776000"),
+ // Suppress delayed-stream progress output so git worktree add doesn't
+ // produce extra lines when the system is under load (>400ms threshold).
+ ("WORKTRUNK_TEST_DELAYED_STREAM_MS", "-1"),
];
/// Build standard test env vars with config and approvals paths