fbi-proxy

FBI-Proxy provides easy HTTPS access to your local services with intelligent domain routing.

Features

Current Features ✅

• Intelligent Domain Routing: Multiple routing patterns for flexible service access
  • Port-based routing (e.g., 3000.fbi.com → localhost:3000)
  • Host--Port routing (e.g., api--3001.fbi.com → api:3001)
  • Subdomain routing with Host headers (e.g., admin.app.fbi.com → app:80)
  • Direct host forwarding (e.g., myserver.fbi.com → myserver:80)
• WebSocket Support: Full WebSocket connection support for all routing patterns
• High Performance: Built with Rust for optimal performance and low resource usage
• Easy Setup: Simple one-command installation and startup
• Docker Support: Available as a Docker image for containerized deployments
• Flexible Configuration: Environment variables and CLI options for customization
• Cross-Platform: Works on macOS, Linux, and Windows
• Integration Ready: Compatible with reverse proxies like Caddy for HTTPS

Roadmap

Shipped ✅

• Auto Caddy Setup - One-command bootstrap that generates a Caddyfile for the chosen domain and supervises Caddy alongside fbi-proxy and fbi-auth (bunx fbi-proxy --with-caddy --with-auth --domain example.dev). Caddy binary is auto-downloaded from GitHub Releases on first run (SHA-512 verified against the release's checksums.txt), cached at ~/.fbi-proxy/bin/caddy. Set FBI_CADDY_AUTO_DOWNLOAD=false to opt out. See docs/auth/setup.md.

Next Up 🚧

• Custom Domain Wizard - Interactive setup that prints the DNS records to add (*.example.dev → <ip>) and generates the matching Caddyfile / DNS-01 TLS block
• Built-in HTTPS (optional) - Native TLS termination via rustls + ACME so Caddy becomes optional for simple setups
• Configuration File Support - YAML/JSON config for persistent routing rules
• Access Control - Domain filtering, host/port whitelisting
• Request Logging - Basic access logs for debugging
• Health Checks - Simple upstream service availability monitoring

Future Improvements 🔮

• Load Balancing - Round-robin between multiple upstream targets
• Metrics - Basic statistics (requests, response times, errors)
• Hot Reload - Update configuration without restart
• Custom Headers - Add/modify headers for specific routes
• Cloudflare Tunnel / ngrok Integration - Expose *.your-domain to the public internet without owning a static IP
• Auth Gateway - Built-in basic auth / OIDC so public exposure is safe by default

Routing Examples

# Port forwarding
https://3000.fbi.com        → localhost:3000
https://8080.fbi.com        → localhost:8080

# Host--Port forwarding
https://api--3001.fbi.com   → api:3001
https://db--5432.fbi.com    → db:5432

# Subdomain routing (with Host header)
https://admin.app.fbi.com   → app:80 (Host: admin)
https://v2.api.fbi.com      → api:80 (Host: v2)

# Direct host forwarding
https://myserver.fbi.com    → myserver:80

WebSocket connections are supported for all patterns.

🕶️ Why fbi.com? — The Story

Slip on your shades and look at this. 🕶️

There's a public DNS quirk that makes fbi.com ridiculously fun for local dev: every *.fbi.com wildcard A record resolves to 127.0.0.1. No /etc/hosts edits. No DNS server. Just open https://3000.fbi.com and your browser is already talking to your laptop.

That's why bunx fbi-proxy defaults to fbi.com — it's the path of least resistance to a working demo. Spin up a dev server on :3000, run the proxy, and you've got a real-looking subdomain pointing at it instantly.

🕶️ …but please don't ship on it

This is a toy for testing and playing, not infrastructure:

• It's somebody else's DNS. Whoever owns fbi.com can change those records any time. Your "production" disappears the moment they do.
• Caddy's tls internal CA is local-only. The root cert is installed into the trust store of the machine running Caddy. Anyone else who visits your *.fbi.com site sees a TLS warning. It cannot be shared with teammates, mobile devices, or end users.
• Anyone can issue certs for *.fbi.com. Because the apex isn't yours, you have zero control over who else asks Let's Encrypt for a cert on the same name.

🕶️ For anything real — bring your own domain

bunx fbi-proxy --domain example.dev

Then point *.example.dev at your server's IP, run Caddy with proper public-CA TLS (Let's Encrypt via HTTP-01 or DNS-01), and you own the whole stack end-to-end. Production-grade. Shareable. Trustworthy.

fbi.com is the costume sunglasses. Your own domain is the prescription pair.

🕶️ Cousins in the wild: *.vercel.app, *.pages.dev

You've probably noticed *.fbi.com looks a lot like *.vercel.app or *.pages.dev — same wildcard-DNS trick, very different tradeoffs.

Same shape — public wildcard apex points at something — but *.fbi.com points it at your machine, while *.vercel.app and *.pages.dev point it at someone else's machines running your code for you. fbi-proxy is the DIY-at-home cousin of those platforms' subdomain UX.

Usage

# launch
bunx fbi-proxy

# expose to LAN
bunx fbi-proxy --host 0.0.0.0 --port=2432

# run with docker
docker run --rm --name fbi-proxy --network=host snomiao/fbi-proxy

Using with Caddy (Optional)

FBI-Proxy focuses on the core proxy functionality. For HTTPS and advanced routing, you can use Caddy as a reverse proxy:

Install Caddy

# macOS
brew install caddy

# Ubuntu/Debian
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

# Or download from https://caddyserver.com/download

Caddyfile Example

Create a Caddyfile to route *.fbi.com to FBI-Proxy:

*.fbi.com {
    reverse_proxy localhost:2432
    tls internal
}

Run Both Services

# Terminal 1: Start FBI-Proxy
bunx fbi-proxy

# Terminal 2: Start Caddy
caddy run --config Caddyfile

Now you can access your services via HTTPS at https://*.fbi.com!

Development

# Install dependencies
bun install

# Start development
bun run dev

# Or production
bun run build && bun run start

Prerequisites

• Bun: https://bun.sh/
• Rust: https://rustup.rs/

Configuration

Environment Variables

FBI-Proxy supports the following environment variables for configuration:

Command-line arguments take precedence over environment variables.

CLI Options

• Default domain: fbi.com (change with --fbihost)
• Host binding: --host or FBI_PROXY_HOST env var
• Port binding: --port or FBI_PROXY_PORT env var

Alternatives & Tradeoffs

fbi-proxy isn't the only way to get https://myapp.something → localhost:port. Below are five well-known alternatives covering the two halves of the problem: subdomain → loopback resolution (Group A) and forward-auth gateways (Group B).

When to use which

• Pure local dev, one laptop, throwaway demo — fbi-proxy's default fbi.com mode or portless are both fine. portless wins on TLS-trusted-out-of-the-box; fbi-proxy wins if you want pattern routing (<port>.<host>) without registering each service.
• LAN-wide / teammates on the same Wi-Fi — dnsmasq or Pi-hole for the DNS half, then put fbi-proxy (or Caddy directly) in front for TLS + routing. mDNS works for hostname discovery but not wildcards.
• Production / public domain — fbi-proxy with --domain yourdomain.com + Caddy for ACME TLS. Pair with tinyauth (lightweight) or Authelia (full IAM) for real auth.
• Honest tradeoffs: fbi-proxy's default *.fbi.com is a toy meant for demos — for anything serious you need --domain and a real TLS terminator (Caddy is the documented path). It does not replace an SSO server, a DNS server, or a CDN; it's the glue that wires subdomain → port and optionally calls out to one of the above.

License

MIT License - see LICENSE file for details