Direct

Add External Tunnel and Alias SupportDirect

The user aimed to add support for managing external tunnels and portless aliases in their proxy server tool. They successfully implemented new commands, integrated tunnel handling throughout the system, updated documentation, and ensured comprehensive testing. After auditing and fixing a critical bug related to alias watching and improving CLI tests, all changes passed validation and were ready for final commit and pull request creation.

Agent

OpenCode

Model

Claude Opus 4.6

Shared

Mar 11, 1:55 PM

Messages423

can we figure out what it would take to make ngrok and cloudflare tunnels work with portless? https://github.com/vercel-labs/portless/issues/43

Let me gather context from the issue and the codebase in parallel.

Readhttps://github.com/vercel-labs/portless/issues/43

Ran sub-agentExplore portless tunnel architecture

Good, I have a solid picture now. Let me dig into the specific integration points more closely.

Now I have a complete picture. Here's my analysis and proposed plan.

Analysis

The core problem: Tunnel providers (ngrok, Cloudflare Tunnel) create a public URL (e.g., abc123.ngrok-free.app) and forward traffic to a local port. When forwarded to portless's proxy port (1355), the request arrives with the tunnel's Host header, not the .localhost hostname portless expects. findRoute() at proxy.ts:76-83 finds no match, and the user gets a 404.

Current code path:

Request arrives at proxy with Host: abc123.ngrok-free.app
findRoute() looks for exact match or wildcard subdomain match in registered .localhost routes
No match -- returns 404

There's zero tunnel infrastructure in the codebase today. The only runtime dependency is chalk.

Proposed plan (3 phases, each independently shippable)

Phase 1: Default-route fallback (minimal, solves the 80% case)

When there's exactly one registered route and the incoming Host doesn't match any route, fall back to that single route. This covers the common "I'm developing one app and want to tunnel it" scenario.

Changes:

proxy.ts:findRoute() -- add a fallback: if no match and routes.length === 1, return routes[0]
Optionally, gate this behind a --tunnel-passthrough flag on portless proxy start or a PORTLESS_TUNNEL_PASSTHROUGH=1 env var (to avoid surprising behavior)
No new dependencies, no new files

Trade-offs:

Only works when one app is registered (multi-app needs Phase 2)
The child app still gets PORTLESS_URL=http://myapp.localhost:1355, not the tunnel URL (no way to know it)
Very low risk, ~20 lines of code

Phase 2: Tunnel hostname aliasing (`portless alias`)

Allow mapping external hostnames to portless routes so multi-app tunneling works.

Changes:

New aliases.json in state dir (or extend routes.json with an aliases field)
routes.ts -- RouteStore gains addAlias(externalHostname, portlessName) / removeAlias()
proxy.ts:findRoute() -- check aliases before returning 404
cli.ts -- new portless alias <name> <external-hostname> and portless alias remove <external-hostname> commands
Update help text, README, SKILL.md

Example workflow:

portless myapp next dev                         # -> http://myapp.localhost:1355
ngrok http 1355                                 # starts tunnel
portless alias myapp abc123.ngrok-free.app      # teach proxy about the tunnel hostname
# Now abc123.ngrok-free.app routes to myapp's port

Trade-offs:

Works with multi-app setups
Manual step required (user must run portless alias after starting the tunnel)
ngrok free tier generates random URLs on each restart, so alias must be re-set

Phase 3: Managed tunnel integration (`--tunnel`)

Portless spawns and manages the tunnel process, auto-discovers the tunnel URL, and exposes it via env vars.

Changes:

New file: tunnel.ts -- tunnel provider abstraction + implementations
ts
Providers to implement:
- ngrok: spawn ngrok http <port>, hit the local ngrok API (http://127.0.0.1:4040/api/tunnels) to get the public URL
- cloudflare: spawn cloudflared tunnel --url http://localhost:<port>, parse URL from stderr output
cli.ts -- new --tunnel [provider] flag on portless <name> <cmd>
On app start:
1. Start app + register route as usual
2. Start tunnel pointing at the proxy port
3. Auto-register alias for the tunnel hostname
4. Set PORTLESS_TUNNEL_URL env var on the child process (alongside PORTLESS_URL)
5. On exit, kill tunnel process + remove alias
Update help text, README, SKILL.md

Example workflow:

portless myapp --tunnel ngrok next dev
# Output:
#   -> http://myapp.localhost:1355
#   -> https://abc123.ngrok-free.app (tunnel)
# Child process gets:
#   PORT=4123  HOST=127.0.0.1
#   PORTLESS_URL=http://myapp.localhost:1355
#   PORTLESS_TUNNEL_URL=https://abc123.ngrok-free.app

Trade-offs:

Best UX -- one command does everything
Requires ngrok/cloudflared to be installed (portless would check and give a clear error if not)
More complex (process management, URL parsing, provider-specific quirks)
Could add ngrok/cloudflare as optional peer dependencies or just shell out

Open questions for you

Used Question

Great, all three phases it is. Let me finalize the detailed implementation plan.

Updated todos

Here's the full implementation plan:

Phase 1: Default-route fallback

Goal: When a request arrives with a non-portless Host header and exactly one app is registered, route to it automatically.

File: proxy.ts -- modify findRoute() (line 76):

This means:

myapp.localhost -> normal routing
unknown.localhost -> 404 with "active apps" page (existing behavior)
abc123.ngrok-free.app -> falls back to the single registered app
Multiple apps registered + unknown host -> 404 (requires Phase 2 alias)

Thread tldSuffix (already available as a local in createProxyServer) into the two findRoute() call sites at lines 146 and ~280 (WebSocket handler).

~15 lines changed, zero new dependencies.

Phase 2: Tunnel hostname aliasing

Goal: Map external hostnames to portless routes so multi-app tunneling works.

New: `aliases.json` in state dir

json

File: `routes.ts` -- extend `RouteStore`

Add methods:

addAlias(externalHostname: string, portlessHostname: string) -- writes to aliases.json with file locking
removeAlias(externalHostname: string) -- removes entry
removeAliasesForRoute(portlessHostname: string) -- removes all aliases pointing at a route
loadAliases(): Record<string, string> -- reads aliases.json

File: `proxy.ts` -- extend route resolution

File: `cli.ts` -- new `portless alias` command

portless alias <name> <hostname>     Map external hostname to a portless app
portless alias remove <hostname>     Remove a hostname alias
portless alias list                  Show all aliases

Example: portless alias myapp abc123.ngrok-free.app

File: `cli.ts` -- wire aliases into proxy startup

In startProxyServer(), load and cache aliases alongside routes, watch aliases.json for changes.

Phase 3: Managed tunnel integration

Goal: portless myapp --tunnel ngrok next dev handles everything.

New file: `tunnel.ts`

ngrok provider:

Availability check: ngrok version (exit code 0)
Start: ngrok http <proxyPort> --log=stdout --log-format=json
URL discovery: poll http://127.0.0.1:4040/api/tunnels (ngrok's local API)
Stop: kill process, which closes the tunnel

cloudflare provider:

Availability check: cloudflared version (exit code 0)
Start: cloudflared tunnel --url http://localhost:<proxyPort>
URL discovery: parse *.trycloudflare.com URL from stderr output
Stop: kill process

File: `cli.ts` -- new `--tunnel` flag

--tunnel <provider>    Start a tunnel (ngrok, cloudflare)

New env var: PORTLESS_TUNNEL=ngrok (alternative to flag).

File: `cli.ts` -- `runApp()` changes

After registering the route and before spawning the child:

Start the tunnel provider pointing at proxyPort
Wait for the tunnel URL (with timeout + error handling)
Auto-register alias: store.addAlias(tunnelHostname, hostname)
Print tunnel URL alongside local URL
Set PORTLESS_TUNNEL_URL on child env
On cleanup: stop tunnel + remove alias

New child process env vars:

PORTLESS_TUNNEL_URL=https://abc123.ngrok-free.app

End-user experience

$ portless myapp --tunnel ngrok next dev

portless

-- myapp.localhost (auto-resolves to 127.0.0.1)
-- Name "myapp" (from package.json)
-- Proxy is running
-- Using port 4123
-- Starting ngrok tunnel...

  -> http://myapp.localhost:1355        (local)
  -> https://abc123.ngrok-free.app      (tunnel)

Running: PORT=4123 HOST=127.0.0.1 PORTLESS_URL=http://myapp.localhost:1355 PORTLESS_TUNNEL_URL=https://abc123.ngrok-free.app next dev

Files touched (summary)

File	Phase	Changes
`proxy.ts`	1, 2	`findRoute()` gains fallback + alias lookup
`types.ts`	2	`ProxyServerOptions` gains `getAliases`
`routes.ts`	2	`RouteStore` gains alias methods
`tunnel.ts`	3	New file: provider abstraction + ngrok/cloudflare impls
`cli.ts`	1, 2, 3	Wire everything up, new commands/flags, help text
`index.ts`	3	Export `tunnel.ts`
`README.md`	1, 2, 3	Document tunnel features
`skills/portless/SKILL.md`	1, 2, 3	Agent skill updates
Tests	1, 2, 3	Unit tests for each phase

Want me to start implementing?

lets create a feature branch and get to it

Updated todos

Starting with Phase 1. Let me read the exact code I need to modify.

Now let me see the WebSocket handler where findRoute is also called:

Good. Now I have both call sites. Let me implement Phase 1:

Editedproxy.ts

Now update both call sites to pass tldSuffix:

Editedproxy.ts

Phase 1 is done. Let me verify it compiles:

Typechecks clean. Let me also run existing tests:

The proxy tests (most relevant to Phase 1) pass. CLI tests need a build first -- let me build and rerun:

All 287 tests pass. Now Phase 2.

Updated todos

Phase 2 needs changes to routes.ts (alias storage), types.ts (new option), proxy.ts (wire aliases), and cli.ts (alias command). Let me read the full routes.ts first:

Now let me add alias support to RouteStore:

Editedroutes.ts

Now add the getAliasesPath() method and alias I/O methods at the end of the class, before the closing }:

Editedroutes.ts

Now add getAliases to ProxyServerOptions in types.ts:

Editedtypes.ts

Now wire getAliases into createProxyServer in proxy.ts:

Editedproxy.ts

Now update both findRoute call sites to pass aliases:

Editedproxy.ts

Now wire aliases into the proxy startup in cli.ts. Let me read the relevant section:

Now I need to add alias caching and watching to startProxyServer, and pass getAliases to createProxyServer:

Editedcli.ts

Now pass getAliases to createProxyServer:

Editedcli.ts

Now update the cleanup function to also close the alias watcher:

Editedcli.ts

Good. Now add the portless alias CLI command. Let me find where the other commands are dispatched:

GreppedhandleAlias|handleHosts|handleList|handleGet

There's already a handleAlias at line 908. Let me read it:

The existing alias command is for mapping portless names to local ports (static route registration). I need a separate tunnel subcommand for external hostname mapping. Let me check the command dispatch:

Now let me also check the reserved names list:

GreppedRESERVED_NAMES|reserved

Good. Now I'll add the handleTunnel command and its dispatch. Let me add it right after handleAlias:

Editedcli.ts

Now add the dispatch for tunnel in the main function:

Editedcli.ts

Update the reserved names reference in help text and the comment:

Editedcli.ts

Now typecheck and run tests:

All 287 tests pass. Now Phase 3 -- managed tunnel integration.

Updated todos

Now create tunnel.ts with the provider abstraction and implementations:

Now export it from index.ts:

Editedindex.ts

Now wire the --tunnel flag into cli.ts. I need to modify the arg parsing and runApp function. Let me read the arg parsing for named mode:

I need to add --tunnel to ParsedRunArgs and both parse functions. Let me update the interfaces and parsing:

Editedcli.ts

Now update parseRunArgs to accept --tunnel:

Editedcli.ts

Now update parseAppArgs similarly:

Editedcli.ts

Now find the post-name flag parsing in parseAppArgs:

Editedcli.ts

Now add the parseTunnelArg and tunnelFromEnv helper functions. Let me find a good place to add them near the other parse helpers:

Editedcli.ts

Now add the import for tunnel at the top of cli.ts:

Readcli.ts20 lines

200 of 423

Analysis

Proposed plan (3 phases, each independently shippable)

Phase 1: Default-route fallback (minimal, solves the 80% case)

Phase 2: Tunnel hostname aliasing (portless alias)

Phase 3: Managed tunnel integration (--tunnel)

Open questions for you

Phase 1: Default-route fallback

Phase 2: Tunnel hostname aliasing

New: aliases.json in state dir

File: routes.ts -- extend RouteStore

File: proxy.ts -- extend route resolution

File: cli.ts -- new portless alias command

File: cli.ts -- wire aliases into proxy startup

Phase 3: Managed tunnel integration

New file: tunnel.ts

File: cli.ts -- new --tunnel flag

File: cli.ts -- runApp() changes

End-user experience

Files touched (summary)

Analysis

Proposed plan (3 phases, each independently shippable)

Phase 1: Default-route fallback (minimal, solves the 80% case)

Phase 2: Tunnel hostname aliasing (portless alias)

Phase 3: Managed tunnel integration (--tunnel)

Open questions for you

Phase 1: Default-route fallback

Phase 2: Tunnel hostname aliasing

New: aliases.json in state dir

File: routes.ts -- extend RouteStore

File: proxy.ts -- extend route resolution

File: cli.ts -- new portless alias command

File: cli.ts -- wire aliases into proxy startup

Phase 3: Managed tunnel integration

New file: tunnel.ts

File: cli.ts -- new --tunnel flag

File: cli.ts -- runApp() changes

End-user experience

Files touched (summary)

Phase 2: Tunnel hostname aliasing (`portless alias`)

Phase 3: Managed tunnel integration (`--tunnel`)

New: `aliases.json` in state dir

File: `routes.ts` -- extend `RouteStore`

File: `proxy.ts` -- extend route resolution

File: `cli.ts` -- new `portless alias` command

File: `cli.ts` -- wire aliases into proxy startup

New file: `tunnel.ts`

File: `cli.ts` -- new `--tunnel` flag

File: `cli.ts` -- `runApp()` changes

Phase 2: Tunnel hostname aliasing (`portless alias`)

Phase 3: Managed tunnel integration (`--tunnel`)

New: `aliases.json` in state dir

File: `routes.ts` -- extend `RouteStore`

File: `proxy.ts` -- extend route resolution

File: `cli.ts` -- new `portless alias` command

File: `cli.ts` -- wire aliases into proxy startup

New file: `tunnel.ts`

File: `cli.ts` -- new `--tunnel` flag

File: `cli.ts` -- `runApp()` changes