Why port 3000 stays free
OAuth callbacks, mapping API origin restrictions, and CORS allowlists may be configured for localhost:3000. That works when you have one copy of the app. It breaks the moment you run two.
The problem
Git worktrees let you work on multiple branches at the same time, each in its own directory. But each copy of the app needs its own port — branch A on 3000, branch B on 3010, branch C on 3020. The moment branch B starts on port 3010:
- OAuth redirects are configured for
localhost:3000/auth/callback— the provider rejects the redirect from:3010 - Mapbox / Google Maps validate the page origin — tile requests from
localhost:3010are denied - Stripe CLI forwarding points at
localhost:3000/webhooks— events never reach the branch B server - CORS policies allowlist
localhost:3000— API calls from:3010are blocked
You’re forced to choose: run on the “right” port and stop all other branches, or reconfigure every third-party dashboard for every branch. Neither scales.
The design decision
Dynamic allocation skips common development ports such as 3000, 4000, 5000, 8000, and 8080, unless you explicitly reserve them. Worktree servers bind to ports in a managed range that the developer never needs to type. That leaves port 3000 available for the proxy.
gtl proxy 3000 sits on the port that third-party services expect and routes traffic to whichever worktree you’re working on. Your browser and local forwarding tools keep using localhost:3000. You rotate what’s behind it.
$ gtl proxy 3000
Proxying :3000 → :4010 (feature-auth)
# OAuth callback → :4010 ✓
# Stripe webhook → :4010 ✓
# Mapbox origin → :4010 ✓
# CORS passes → :4010 ✓
Two layers, one config
The proxy provides a fixed local port. Branch-named URLs provide local HTTPS, while a tunnel lets public services reach your machine. They can run simultaneously:
| Audience | URL | How |
|---|---|---|
| Your browser | myapp-feature.prt.dev | gtl serve |
| Browser callbacks / origin allowlists / Stripe CLI | localhost:3000 | gtl proxy |
| Public internet (webhooks, CI) | myapp-feature.example.dev | gtl tunnel |
| A colleague or client | Disposable token-gated URL | gtl share |
What the developer sees
# Create a worktree — treeline allocates port 4010
$ gtl new feature/oauth-refactor
Allocated port 4010, cloned database, wrote .env
# Start the server — runs on 4010, not 3000
$ gtl start
==> https://myapp-feature-oauth-refactor.prt.dev
# In another terminal, route port 3000 to this worktree
$ gtl proxy 3000
Proxying :3000 → :4010
Keep browser callbacks and origin allowlists on a stable local origin while switching the worktree behind it. For local Stripe testing, run stripe listen --forward-to localhost:3000/webhooks. To register a webhook endpoint in Stripe, use a publicly accessible HTTPS URL from gtl tunnel.
Read next
- Networking feature page — deep dive on all four commands:
serve,proxy,tunnel, andshare - Docs: networking — config options, port forwarding rules, and Safari workarounds
- Multi-repo — when the problem is cross-project service resolution, not external URLs