Skip to content

Use cases

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:

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

All use cases