@labs-infinitum/tunnel-dev

Zero-config Cloudflare Tunnel for local development. Expose any local server through your own domain in one command — no manual dashboard setup, no port forwarding.

tunnel-dev bun run dev
# ✔ Tunnel ready! Public URL: https://alice-myapp.example.com
# Starting: bun run dev

• Automatic — creates the tunnel, DNS record, and ingress rule via Cloudflare API
• Multi-tunnel — define an array in tunnel.config.ts to start all tunnels in parallel
• Per-developer URLs — $USER interpolation gives every dev their own subdomain
• Multi-source config — package.json, tunnel.config.ts, env vars, or CLI flags
• CLI + Library — use as a command or call withTunnel() from your own scripts
• Zero unofficial deps — cloudflared binary downloaded directly from cloudflare/cloudflared releases

---

Prerequisites

You need a Cloudflare account with:

• A domain managed by Cloudflare DNS
• An API token with Zone:DNS:Edit and Account:Cloudflare Tunnel:Edit permissions

Set these three environment variables (add them to your .env):

CLOUDFLARE_API_TOKEN=your_api_token
CLOUDFLARE_ACCOUNT_ID=your_account_id
CLOUDFLARE_ZONE_ID=your_zone_id

---

Installation

# npm
npm install --save-dev @labs-infinitum/tunnel-dev

# bun
bun add -d @labs-infinitum/tunnel-dev

# pnpm
pnpm add -D @labs-infinitum/tunnel-dev

# or use without installing
npx @labs-infinitum/tunnel-dev bun run dev

---

Quick Start

Add a cloudflare block to your package.json and a dev:tunnel script:

{
  "scripts": {
    "dev": "vite dev",
    "dev:tunnel": "tunnel-dev bun run dev"
  },
  "cloudflare": {
    "name": "myapp-$USER",
    "hostname": "$USER-myapp.example.com",
    "target": "http://localhost:5173"
  }
}

Run it:

bun run dev:tunnel
# ✔ Tunnel ready! Public URL: https://alice-myapp.example.com
# Starting: bun run dev

$USER is replaced with your system username automatically, so each developer on the team gets their own isolated subdomain.

---

Config Sources

@labs-infinitum/tunnel-dev merges config from multiple sources. Higher entries win:

Priority	Source	Example
1 (highest)	CLI flags	--name, --hostname, --target
2	Programmatic options	withTunnel({ name, hostname, target })
3	tunnel.config.ts	export default defineConfig({...})
4	package.json cloudflare field	"cloudflare": { ... }
5 (lowest)	Environment variables	TUNNEL_NAME, TUNNEL_HOSTNAME, TUNNEL_TARGET

name and hostname support $VAR interpolation from process.env in any source.

---

Configuration

Option A — package.json field

The simplest option. Add a cloudflare block:

{
  "cloudflare": {
    "name": "myapp-$USER",
    "hostname": "$USER-myapp.example.com",
    "target": "http://localhost:3000"
  }
}

Field	Description
name	Tunnel name in Cloudflare dashboard. Must be unique per account.
hostname	Public URL to expose (must be on your Cloudflare zone).
target	Local server to forward traffic to.

Option B — tunnel.config.ts

For TypeScript config with full IDE autocomplete. Accepts a single tunnel or an array:

import { defineConfig } from "@labs-infinitum/tunnel-dev";

// Single tunnel
export default defineConfig({
  name: "myapp-$USER",
  hostname: "$USER-myapp.example.com",
  target: "http://localhost:3000",
});

import { defineConfig } from "@labs-infinitum/tunnel-dev";

// Multiple tunnels — all start in parallel before your command runs
export default defineConfig([
  {
    name: "web-$USER",
    hostname: "$USER-web.example.com",
    target: "http://localhost:3001",
  },
  {
    name: "api-$USER",
    hostname: "$USER-api.example.com",
    target: "http://localhost:3000",
  },
]);

Option C — Environment variables

Override any config field at runtime:

TUNNEL_NAME=myapp-alice \
TUNNEL_HOSTNAME=alice-myapp.example.com \
TUNNEL_TARGET=http://localhost:3000 \
tunnel-dev bun run dev

Option D — CLI flags

Pass config inline without any config file:

tunnel-dev \
  --name myapp-alice \
  --hostname alice-myapp.example.com \
  --target http://localhost:3000 \
  bun run dev

---

Monorepo Setup

There are two patterns for monorepos — pick what fits your workflow.

Pattern A — single tunnel.config.ts at the root

Define all tunnels in one place and run a single command to start them all in parallel:

my-monorepo/
├── apps/
│   ├── web/         ← React frontend on :3001
│   └── server/      ← API server on :3000
├── tunnel.config.ts ← all tunnels here
└── package.json

tunnel.config.ts

import { defineConfig } from "@labs-infinitum/tunnel-dev";

export default defineConfig([
  {
    name: "myapp-web-$USER",
    hostname: "$USER-web.example.com",
    target: "http://localhost:3001",
  },
  {
    name: "myapp-api-$USER",
    hostname: "$USER-api.example.com",
    target: "http://localhost:3000",
  },
]);

Root package.json

{
  "scripts": {
    "dev:tunnel": "tunnel-dev bun run dev"
  }
}

bun run dev:tunnel
# Setting up 2 tunnels in parallel...
#   Tunnel ready: https://alice-web.example.com
#   Tunnel ready: https://alice-api.example.com
# Starting: bun run dev

Pattern B — per-app config in package.json

Each app declares its own tunnel config. Invoke dev:tunnel from each app's directory (or via Turborepo).

apps/web/package.json

{
  "scripts": {
    "dev": "vite dev",
    "dev:tunnel": "tunnel-dev bun run dev"
  },
  "cloudflare": {
    "name": "myapp-web-$USER",
    "hostname": "$USER-web.example.com",
    "target": "http://localhost:3001"
  }
}

apps/server/package.json

{
  "scripts": {
    "dev": "node src/index.js",
    "dev:tunnel": "tunnel-dev node src/index.js"
  },
  "cloudflare": {
    "name": "myapp-api-$USER",
    "hostname": "$USER-api.example.com",
    "target": "http://localhost:3000"
  }
}

@labs-infinitum/tunnel-dev reads package.json from the current working directory, so each app picks up its own config automatically.

With Turborepo

Register dev:tunnel as a persistent task in turbo.json:

{
  "tasks": {
    "dev:tunnel": {
      "cache": false,
      "persistent": true
    }
  }
}

Then run per-app tunnels in parallel:

turbo run dev:tunnel --filter=web --filter=server

Shared domain across the team

Use $USER in your tunnel name and hostname so every developer gets a personal subdomain without conflicts:

{
  "cloudflare": {
    "name": "myapp-web-$USER",
    "hostname": "$USER-web.example.com",
    "target": "http://localhost:3001"
  }
}

Developer	Public URL
alice	https://alice-web.example.com
bob	https://bob-web.example.com
carol	https://carol-web.example.com

---

Programmatic API

Use @labs-infinitum/tunnel-dev as a library in your own scripts or tooling:

import { withTunnel } from "@labs-infinitum/tunnel-dev";

await withTunnel({
  // Tunnel config
  name: "myapp-dev",
  hostname: "dev.example.com",
  target: "http://localhost:3000",

  // Command to run after tunnel is ready
  command: ["bun", "run", "dev"],
});

Passing Cloudflare credentials programmatically

If you manage credentials outside of environment variables (e.g. pulled from a secrets manager at runtime), pass them directly:

import { withTunnel } from "@labs-infinitum/tunnel-dev";

const secrets = await mySecretsManager.get("cloudflare");

await withTunnel({
  apiToken: secrets.apiToken,
  accountId: secrets.accountId,
  zoneId: secrets.zoneId,

  name: "myapp-dev",
  hostname: "dev.example.com",
  target: "http://localhost:3000",

  command: ["bun", "run", "dev"],
});

TunnelOptions reference

interface TunnelOptions {
  // Tunnel config
  name?: string;      // Tunnel name (supports $VAR interpolation)
  hostname?: string;  // Public hostname (supports $VAR interpolation)
  target?: string;    // Local server URL, e.g. "http://localhost:3000"

  // Cloudflare API credentials (fall back to CLOUDFLARE_* env vars)
  apiToken?: string;
  accountId?: string;
  zoneId?: string;

  // Runtime
  command?: string[];  // Command to spawn after tunnel is ready
  verbose?: boolean;
}

defineConfig helper

Provides type safety and IDE autocomplete for tunnel.config.ts. Accepts a single config or an array:

import { defineConfig } from "@labs-infinitum/tunnel-dev";

// Single tunnel
export default defineConfig({ name, hostname, target });

// Multiple tunnels — started in parallel before your command
export default defineConfig([
  { name, hostname, target },
  { name, hostname, target },
]);

---

CLI Reference

tunnel-dev [options] <command...>

Flag	Description
--name	Tunnel name (overrides all config sources)
--hostname	Public hostname (overrides all config sources)
--target	Local server URL (overrides all config sources)
-v, --verbose	Verbose output
-h, --help	Show help

Everything after the options is treated as the command to run:

tunnel-dev --name my-tunnel bun run dev
tunnel-dev --hostname dev.example.com npm start
tunnel-dev --target http://localhost:8080 pnpm dev

---

How It Works

1. Reads and merges config from all sources (package.json → tunnel.config.ts → env vars → CLI flags)
2. For each tunnel: checks ~/.cloudflared/tunnels/<name>.json cache for an existing tunnel ID
3. Creates or reuses the tunnel via Cloudflare API
4. Configures the DNS CNAME record pointing to the tunnel
5. Sets the ingress rule routing your hostname to your local server
6. Downloads cloudflared binary from cloudflare/cloudflared (cached at ~/.cloudflared/bin/) and starts it
7. When multiple tunnels are configured, steps 2–6 run in parallel for all of them
8. Spawns your command once all tunnels are ready — everything shuts down together on Ctrl+C

Each tunnel is cached per-name at ~/.cloudflared/tunnels/<name>.json, so multiple projects never overwrite each other's tunnel state.

---

Environment Variables

Variable	Required	Description
CLOUDFLARE_API_TOKEN	Yes	Cloudflare API token with DNS and Tunnel permissions
CLOUDFLARE_ACCOUNT_ID	Yes	Your Cloudflare account ID
CLOUDFLARE_ZONE_ID	Yes	Zone ID of your domain
TUNNEL_NAME	No	Override tunnel name
TUNNEL_HOSTNAME	No	Override public hostname
TUNNEL_TARGET	No	Override local server target

---

License

Apache 2.0 — see LICENSE