TunnelFlow

Open-source, self-hostable localhost tunneling — expose any local port to the internet in seconds.

TunnelFlow is a full-stack tunneling platform you can run on your own server. It gives you a dashboard, a CLI tool, traffic inspection, webhook simulation, team support, and a built-in billing system — everything you'd expect from a hosted tunneling service, but self-hosted.

---

Features

• Instant tunnels — expose any local port via a public subdomain in seconds
• CLI tool (tflow) — one command to connect, no config file needed
• Traffic Inspector — live request/response log with search and filtering
• Breakpoints — pause and inspect HTTP traffic in real time, then forward or drop
• Diff View — compare requests side by side
• Webhook Simulator — replay and simulate webhook payloads
• Rules Engine — rewrite headers, block requests, inject latency
• Session Manager — save and replay captured request sessions
• Watch Mode — share a read-only live view of your tunnel traffic with anyone via a link
• Team support — invite members, share tunnels within a workspace
• Analytics — per-tunnel request metrics
• Stripe billing — Free and Pro tiers built in (can be disabled)
• GitHub OAuth — ready-to-use auth flow
• Wildcard TLS — automatic HTTPS via Caddy

---

Architecture

TunnelFlow/
├── server/      Express + WebSocket tunnel engine  (port 3001)
├── web/         Next.js App Router dashboard/landing (port 3000)
├── cli/         Standalone tflow CLI tool
├── Caddyfile    Wildcard TLS reverse proxy config
├── pm2.config.js  Process manager config
└── setup.sh     One-command server bootstrap

---

Self-Hosting

Prerequisites

• A Linux server with a public IP
• A domain you control (e.g. tunnel.yourdomain.com)
• Node.js 20+
• MySQL 8+
• Caddy v2 with your DNS provider plugin (for wildcard TLS)
• PM2: npm install -g pm2
• DNS: Point *.yourdomain.com and yourdomain.com to your server

1. Clone the repo

git clone https://github.com/tedddby/TunnelFlow.git
cd TunnelFlow

2. Configure environment

cp server/.env.example server/.env
cp web/.env.example    web/.env
# Edit both files and fill in your values

See the Environment Variables section for what each value does.

3. Run setup

chmod +x setup.sh
./setup.sh

This will:

• Create the MySQL database and tables
• Install all dependencies
• Build the Next.js app
• Start both services via PM2

4. Start Caddy

# Set your DNS provider API token (example uses Vultr)
export VULTR_API_TOKEN=your_token
caddy start --config Caddyfile

Update Caddyfile to use your domain and your DNS provider's Caddy module.

---

Development

# Terminal 1 — tunnel engine
cd server && npm install && cp .env.example .env
node server.js

# Terminal 2 — Next.js dashboard
cd web && npm install && cp .env.example .env
npm run dev

# Terminal 3 — test the CLI
cd cli && npm install
node tflow.js login <token-from-dashboard>
node tflow.js connect 3000

---

CLI Usage

npm install -g tflow

tflow login <your-auth-token>          # Authenticate with your token from the dashboard
tflow connect 3000                     # Expose port 3000
tflow connect 3000 --subdomain myapp  # Custom subdomain (Pro only)
tflow status                           # Show saved config
tflow logout                           # Remove saved token

---

Environment Variables

server/.env

Variable	Description
PORT	Tunnel engine port (default: 3001)
BASE_DOMAIN	Your root domain (e.g. tunnel.yourdomain.com)
DB_HOST	MySQL host
DB_USER	MySQL user
DB_PASSWORD	MySQL password
DB_NAME	MySQL database name
INTERNAL_SECRET	Shared secret for Next.js → server API calls

web/.env

Variable	Description
NEXTAUTH_URL	Public URL of the Next.js app
NEXTAUTH_SECRET	Random secret for JWT signing
GITHUB_ID / GITHUB_SECRET	GitHub OAuth App credentials
DB_HOST/USER/PASSWORD/NAME	MySQL connection settings
STRIPE_SECRET_KEY	Stripe secret key (leave blank to disable billing)
STRIPE_PRO_PRICE_ID	Stripe Price ID for the Pro plan
STRIPE_WEBHOOK_SECRET	Stripe webhook signing secret
INTERNAL_SECRET	Must match server/.env
NEXT_PUBLIC_BASE_DOMAIN	Domain shown in the dashboard UI

---

Stripe Setup (Optional)

Billing is optional. If you leave the Stripe variables empty, the Pro plan upgrade flow is simply disabled and all users get full access.

To enable billing:

1. Create a product in the Stripe Dashboard with a recurring monthly price.
2. Copy the Price ID → STRIPE_PRO_PRICE_ID.
3. Add a webhook endpoint pointing to https://yourdomain.com/api/webhook listening for:
   • checkout.session.completed
   • customer.subscription.deleted
   • invoice.payment_failed
4. Copy the Webhook Secret → STRIPE_WEBHOOK_SECRET.

---

Plan Limits

Feature	Free	Pro
Active tunnels	1	Unlimited
Custom subdomains	No	Yes
Price	$0	$5/mo

These limits are configurable in the server code.

---

Contributing

Contributions are welcome. To get started:

1. Fork the repo and create a branch: git checkout -b my-feature
2. Make your changes and test locally using the dev setup above
3. Open a pull request with a clear description of what you changed and why

For larger changes, open an issue first to discuss the approach.

---

License

TunnelFlow is licensed under the GNU Affero General Public License v3.0.

This means you can self-host, modify, and use TunnelFlow freely. If you run a modified version as a public service, you must also release your modifications under the same license.