HTTP tunnel via Cloudflare Durable Objects

HTTP tunnel via Cloudflare Durable Objects and WebSockets. Expose local servers to the internet with a simple CLI. Infinitely scalable with support for Cloudflare CDN caching and password protection.

Ask AI about this page

Installation

bash

1npm install -g traforo

Usage

Expose a local server by pointing traforo at a port:

bash

1traforo -p 3000

Or let traforo auto-detect the port from a dev server command:

bash

12traforo -- pnpm dev
traforo -- next start

With a custom tunnel ID (only for services safe to expose publicly):

bash

1traforo -p 3000 -t my-app

Run a command and tunnel it:

bash

1234traforo -- next start
traforo -- pnpm dev
traforo -p 5173 -- vite
traforo -p 3000 -- next start    # explicit port overrides auto-detection

The tunnel URL will be:

bash

1https://{tunnel-id}-tunnel.traforo.dev

When you pass a command after --, traforo auto-detects the port from the process output so you don't need -p at all.

Options

bash

12345678-p, --port <port>          Local port to expose (optional with -- command)
-t, --tunnel-id [id]       Custom tunnel ID (prefer random default)
-c, --cache [key]          Enable edge caching (optional partition key)
--password <password>      Protect the tunnel with a password
-h, --host [host]          Local host (default: localhost)
-s, --server [url]         Custom tunnel server URL
--help                     Show help
--version                  Show version

Auto Port Detection

When you pass a command after --, traforo can detect the local port from the process output. It watches stdout and stderr for addresses like these:

bash

1234http://localhost:3000
localhost:5173
127.0.0.1:8080
0.0.0.0:4321

This works well with common dev servers that print their local URL when they start.

If you also pass -p, traforo uses that explicit port instead of auto-detecting from process output.

Edge Caching

Cache responses at Cloudflare's edge so repeat requests never hit your local machine:

bash

1traforo -p 3000 --cache

What gets cached:

GET requests where the origin sends cacheable Cache-Control headers (public, max-age, s-maxage)
Static asset extensions use Cloudflare-like default fallback TTLs when cache headers are missing: 200/301=120m, 302/303=20m, 404/410=3m

What never gets cached:

Non-GET requests
206 Partial Content responses (Cache API put() limitation)
Responses with Set-Cookie, Cache-Control: no-store/no-cache/private
Streaming responses (SSE, ndjson)
WebSocket connections

Requests with Authorization, Cache-Control: no-cache/no-store/max-age=0, or Pragma: no-cache bypass edge cache lookup.

The X-Traforo-Cache response header shows HIT, MISS, or BYPASS for debugging. When BYPASS/MISS comes from the local origin path, X-Traforo-Cache-Reason explains why.

Cache Partitioning

Cache partitioning lets you bust all cached content by changing the key:

bash

12traforo -p 3000 --cache v1     # first deployment
traforo -p 3000 --cache v2     # new deploy, fresh cache

Each key creates a separate cache namespace. Old entries expire via TTL.

Password Protection

Restrict tunnel access with a password:

bash

1traforo -p 3000 --password mysecret

Visitors in a browser see a login page. After entering the correct password a traforo-password cookie is set and they can browse normally.

Non-browser clients (curl, APIs) get a 401 Unauthorized response with instructions to pass the password as a cookie:

bash

1curl -b 'traforo-password=mysecret' https://{tunnel-id}-tunnel.traforo.dev

WebSocket upgrade requests without the correct cookie are rejected with close code 4013.

License Key

Hosted license keys cost $20/month. Buy one at https://traforo.dev/license, then save it once:

bash

123traforo login <key>
traforo -p 3000
traforo -- pnpm dev

The CLI saves your key locally with owner-only file permissions and reuses it on future runs. Run traforo login <new-key> to replace it. For CI, set TRAFORO_LICENSE_KEY instead; it takes priority over the saved key.

Saved keys are scoped to the server. Use the same --server option when logging in and opening tunnels against a custom server:

bash

12traforo login <key> --server wss://tunnel.example.com
traforo -p 3000 --server wss://tunnel.example.com

TRAFORO_BASE_DOMAIN also selects a separate saved key for each domain. The library reads licenseKey or TRAFORO_LICENSE_KEY, not the CLI's saved key.

When license enforcement is enabled, the server closes tunnels without a valid key with code 4402. The client prints where to buy one and does not retry. Enforcement is currently disabled on the hosted worker.

Self-hosted instances never ask for a key. Checks only run when the worker sets LICENSE_REQUIRED to "true" (see Self-Hosting).

TRAFORO_URL Environment Variable

When you run a command after --, traforo injects TRAFORO_URL into the child process environment with the full public tunnel URL:

bash

1TRAFORO_URL=https://{tunnel-id}-tunnel.traforo.dev

Your app can read it directly:

1const baseUrl = process.env.TRAFORO_URL

To remap it to a custom env var your app already uses, prefix the command:

bash

123traforo -p 3000 -- sh -c 'APP_URL=$TRAFORO_URL exec node server.js'
traforo -p 3000 -- sh -c 'NEXT_PUBLIC_URL=$TRAFORO_URL exec next dev'
traforo -p 3000 -- sh -c 'VITE_BASE_URL=$TRAFORO_URL exec vite'

Or set it in your .env / startup script and let traforo override only TRAFORO_URL, reading it where needed:

12// next.config.js
const baseUrl = process.env.APP_URL || process.env.TRAFORO_URL || 'http://localhost:3000'

To remap it to a custom env var your app already uses, prefix the command with sh -c and reference $TRAFORO_URL.

Stable Tuistory Restarts

When traforo runs inside a tuistory session, it uses tuistory's random TUISTORY_SESSION_ID as the default tunnel ID. The URL stays the same when the session restarts:

bash

12tuistory -s app -- traforo -- pnpm dev
tuistory -s app restart

Closing the session and launching a new one creates a new random URL. An explicit --tunnel-id still takes priority.

Path Inheritance

Package managers like pnpm and bun prepend node_modules/.bin to PATH. Traforo passes the full parent environment to child commands, so project-local binaries work without pnpm exec or npx:

bash

123pnpm traforo -- vite dev
pnpm traforo -- next start
bun traforo -- wrangler dev

Reverse Proxy Headers

Traforo injects standard reverse-proxy headers when forwarding requests to your local server:

bash

12X-Forwarded-Host:  {tunnel-id}-tunnel.traforo.dev
X-Forwarded-Proto: https

Frameworks like BetterAuth, Next.js, Express (with trust-proxy), and Hono use these to construct correct redirect URLs and absolute links instead of pointing back to localhost.

If your framework reads X-Forwarded-Host or X-Forwarded-Proto, redirects and OAuth callbacks will use the public tunnel URL automatically.

These headers are only added if not already present in the incoming request. No configuration needed.

Cloudflare Workers (Wrangler Dev)

When running a Cloudflare Workers project via traforo -- wrangler dev, traforo sets CLOUDFLARE_INCLUDE_PROCESS_ENV=true in the child process environment. This tells wrangler to pass parent env vars (including TRAFORO_URL) as local development bindings, so process.env.TRAFORO_URL works inside workerd.

bash

1traforo -- wrangler dev

12// Inside your worker:
const baseUrl = process.env.TRAFORO_URL

This only works when no .dev.vars file exists in the project. If you use .dev.vars, add TRAFORO_URL there manually or use a startup script that reads the env var.

How It Works

diagram

  CLI Client                Cloudflare Edge               Local Server
      │                          │                             │
      │  WebSocket connect       │                             │
      │ ────────────────────►    │                             │
      │                          │                             │
      │                    ┌─────┴─────┐                       │
      │                    │  Durable  │   HTTP request        │
      │                    │  Object   │ ◄─── browser/curl     │
      │                    └─────┬─────┘                       │
      │                          │                             │
      │  forward request via WS  │                             │
      │ ◄────────────────────    │                             │
      │                          │                             │
      │         http://localhost:PORT                          │
      │ ──────────────────────────────────────────────────►    │
      │                          │                             │
      │ ◄──────────────────────────────────────────────────    │
      │  response                │                             │
      │ ────────────────────►    │                             │
      │                    ┌─────┴─────┐                       │
      │                    │  respond  │ ───► browser/curl     │
      │                    └───────────┘                       │

Local client connects to Cloudflare Durable Object via WebSocket
HTTP requests to tunnel URL are forwarded to the DO
DO sends requests over WebSocket to local client
Local client makes request to localhost and returns response
WebSocket connections from users are also proxied through

API Endpoints

bash

1234/traforo-status         Check if tunnel is online
/traforo-upstream       WebSocket endpoint for local client
/traforo-login          POST endpoint for password login
/*                      All other paths proxied to local server

Library Usage

123456789101112import { TunnelClient } from 'traforo/client'
import { runTunnel } from 'traforo/run-tunnel'

const client = new TunnelClient({
  localPort: 3000,
  tunnelId: 'my-app',
  cacheKey: 'v1',       // optional: enable edge caching
  password: 'mysecret', // optional: password protection
  licenseKey: 'key',    // optional: default TRAFORO_LICENSE_KEY
})

await client.connect()

Self-Hosting

You can deploy your own traforo instance on Cloudflare. The worker uses Durable Objects for WebSocket coordination, so you need a Cloudflare account with the Workers Paid plan.

Prerequisites

A Cloudflare account with Workers Paid plan (Durable Objects require it)
A domain added to Cloudflare DNS (e.g. example.com)
Node.js 18+ and pnpm installed
wrangler CLI: npm install -g wrangler

1. Clone and install

bash

123git clone https://github.com/remorses/traforo.git
cd traforo
pnpm install

2. Configure your domain

Edit worker/wrangler.json and replace the routes with your domain:

json

12345678{
  "routes": [
    {
      "pattern": "*-tunnel.example.com/*",
      "zone_name": "example.com"
    }
  ]
}

Keep "LICENSE_REQUIRED": "false" in vars. With "true" the worker checks the hosted Traforo Polar license benefit (IDs hardcoded in src/tunnel.ts) on every tunnel connect (valid keys are cached for an hour; if Polar is down, the tunnel connects anyway).

3. Add a wildcard DNS record

In the Cloudflare dashboard for your domain, add a wildcard CNAME record:

bash

1234Type:    CNAME
Name:    *-tunnel
Target:  example.com
Proxy:   Proxied (orange cloud)

This routes all {id}-tunnel.example.com subdomains through Cloudflare to your worker.

4. Deploy the worker

bash

1wrangler deploy -c worker/wrangler.json

5. Use the CLI with your domain

Set the TRAFORO_BASE_DOMAIN environment variable to point the CLI at your instance:

bash

1234export TRAFORO_BASE_DOMAIN=example.com

traforo -p 3000
# Tunnel: https://{id}-tunnel.example.com

Add it to your shell profile (~/.zshrc, ~/.bashrc) to make it permanent:

bash

1echo 'export TRAFORO_BASE_DOMAIN=example.com' >> ~/.zshrc

Or pass it inline for one-off usage:

bash

1TRAFORO_BASE_DOMAIN=example.com traforo -- pnpm dev

Library usage with custom domain

When using the Node.js API, pass baseDomain directly or rely on the env variable:

12345678910import { TunnelClient } from 'traforo/client'

const client = new TunnelClient({
  localPort: 3000,
  tunnelId: 'my-app',
  baseDomain: 'example.com', // or set TRAFORO_BASE_DOMAIN
})

await client.connect()
// https://my-app-tunnel.example.com

License

MIT