Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Gateway

What is the gateway?

The gateway is a local reverse proxy that bundles your development apps under a single port with readable subdomain URLs. Instead of remembering localhost:3000, localhost:3001, localhost:8080, you access everything through subdomains:

http://frontend.localhost:54846
http://api.localhost:54846
http://diff.localhost:54846

How it works

When you run gwt gateway start:

  1. gwt reads the [[gateway.apps]] from your config
  2. Each app is started as a child process with a dynamically assigned port
  3. The gateway listens on a single port (default: 54846) and routes requests by subdomain
  4. A dashboard at http://localhost:54846 shows all running apps and their status

The gateway monitors each app for readiness using the configured ready-pattern — a string to look for in the app’s stdout (e.g., "localhost" or "ready").

Built-in apps

The gateway automatically registers a diff app accessible at http://diff.localhost:<port> whenever the managed diffity runtime is healthy. No configuration needed. If the runtime is unhealthy or uninstalled, the dashboard shows the diff app as Unavailable — run gwt doctor --fix to repair it.

Managed Diffity Runtime

The built-in diff app is powered by diffity, which is a Node.js CLI with a native dependency (better-sqlite3). To avoid Node-version-mismatch crashes (common on machines with multiple Node versions via nvm/asdf/homebrew), gwt ships its own pinned Node and installs diffity into an isolated tree at ~/.gwt/node-runtime/.

This happens automatically during gwt init. The gateway always invokes that exact Node, never your system node or npx. If the install fails (offline, disk full, unsupported platform), gwt init continues but the diff app shows Unavailable in the dashboard — run gwt doctor --fix to retry.

After a gwt upgrade with new pinned versions, gwt gateway start will warn and disable the diff app until you run gwt doctor --fix.

Dashboard

Accessing http://localhost:<port> (without a subdomain) shows the gateway dashboard. It provides:

  • A list of all running apps with their status (starting, ready, crashed, stopped)
  • Direct links to each app’s subdomain URL
  • Real-time status updates via WebSocket

URL Pane

Every worktree tab opened by gwt attach includes a dedicated urls pane that automatically runs gwt dashboard-url. This pane stays alive for the lifetime of the tab and displays the dashboard URL plus one line per configured app. It refreshes automatically whenever the gateway starts, stops, or its port changes — no manual action required.

Port Detection

By default the gateway uses ready-pattern (a plain string) to detect when an app is ready. For apps that print their bound port in startup output you can use ready-regex instead: a regular expression with one capture group whose match is parsed as the port number. This lets the gateway record the exact port the app chose rather than the one it was assigned.

Example: ready-regex = "listening on localhost:(\\d+)" captures the port from output like listening on localhost:3742.

Commands

gwt gateway start [--port <port>]   # Start all apps and the proxy
gwt gateway stop                     # Graceful shutdown (SIGTERM)
gwt gateway kill                     # Force kill (SIGKILL)
gwt gateway status                   # Show running apps and ports
gwt gateway logs [app] [-n <lines>]  # View app logs

Configuration

See gateway configuration for all options including app definitions.