LocalBridge

A reliable, self-hosted localhost tunneling solution to securely expose your local development server to the internet. Similar to ngrok and localtunnel, but designed to be more reliable and user-friendly.

Features

• 🚀 Easy to Use - Simple CLI commands and programmatic API
• 🔒 Secure Tunnels - WebSocket-based secure connections
• 🔄 Auto-Reconnect - Automatically reconnects on connection loss
• 💪 Reliable - Built-in heartbeat and timeout handling
• 🎯 Custom Subdomains - Support for custom subdomain names
• 🔑 Authentication - Optional token-based authentication
• 📊 Status Monitoring - Check active tunnels with a single command
• 🌐 Self-Hosted - Deploy your own server for full control
• 📦 NPM Module - Easy installation and integration

Installation

npm install -g @able_k_saju/local-bridge

Or as a local dependency:

npm install @able_k_saju/local-bridge

Quick Start

Tunnel a Local App

If you already have a LocalBridge server running locally or configured with LOCALBRIDGE_SERVER_URL, tunnel your local app with:

localbridge 3000 --subdomain myapp

The CLI command stays localbridge even though the npm package is scoped.

Local Testing

Start both server and tunnel in one command:

localbridge start 3000 --subdomain myapp

Hosted Server

Terminal 1 - Start the server:

localbridge server --domain bridge.example.com --public-protocol https --public-port 443

Terminal 2 - Create a tunnel:

localbridge 3000 --subdomain myapp --server wss://bridge.example.com

To avoid typing --server every time, set:

localbridge config wss://bridge.example.com
localbridge 3000 --subdomain myapp

You can also use LOCALBRIDGE_SERVER_URL=wss://bridge.example.com in automation or CI.

CLI Commands

<port>

Create a tunnel to a local port.

localbridge 3000
localbridge 3000 --subdomain myapp
localbridge 3000 --server wss://bridge.example.com
localbridge 3000 --host 192.168.1.100 --protocol https

tunnel <port> (alias: t)

Create a tunnel to a local port.

localbridge tunnel 3000
localbridge tunnel 3000 --subdomain myapp
localbridge tunnel 3000 --server wss://bridge.example.com
localbridge tunnel 3000 --host 192.168.1.100 --protocol https

Options:

• -s, --subdomain <subdomain> - Custom subdomain for the tunnel
• --server <url> - LocalBridge server URL (default: LOCALBRIDGE_SERVER_URL or ws://127.0.0.1:8080)
• --host <host> - Local host to forward to (default: localhost)
• --protocol <protocol> - Protocol for local server: http or https (default: http)
• --auth <token> - Authentication token for the tunnel

server (alias: s)

Start the LocalBridge server.

localbridge server
localbridge server --port 9000 --domain my-tunnels.com
localbridge server --domain bridge.example.com --public-protocol https --public-port 443

Options:

• -p, --port <port> - Server port (default: 8080)
• -h, --host <host> - Server host (default: 0.0.0.0)
• -d, --domain <domain> - Domain for tunnels (default: localhost)
• --public-protocol <protocol> - Protocol shown in public tunnel URLs (default: http, or https on Render)
• --public-port <port> - Public port shown in tunnel URLs (default: server port, or 443 for HTTPS)

start <port> (alias: run)

Start both server and tunnel (for local testing).

localbridge start 3000
localbridge start 3000 --subdomain myapp --server-port 9000

Options:

• --subdomain <subdomain> - Custom subdomain for the tunnel
• --host <host> - Local host to forward to (default: localhost)
• --protocol <protocol> - Protocol for local server (default: http)
• --server-port <port> - Server port (default: 8080)

status

Show status of active tunnels.

localbridge status
localbridge status --server http://custom-server.com:8080

config [serverUrl]

Show or save the default hosted LocalBridge server URL.

localbridge config
localbridge config wss://bridge.example.com

list

List all available commands with examples.

localbridge list

Programmatic Usage

LocalBridge can also be used as a Node.js module:

const localbridge = require('@able_k_saju/local-bridge');

// Create a tunnel
const client = await localbridge.tunnel(3000, {
    serverUrl: 'ws://your-server.com:8080',
    subdomain: 'myapp',
    authToken: 'secret-token'
});

console.log('Public URL:', client.publicUrl);

// Keep the process running
setTimeout(() => {}, Infinity);

Starting a Server Programmatically

const localbridge = require('@able_k_saju/local-bridge');

const server = await localbridge.createServer({
    port: 8080,
    domain: 'your-domain.com'
});

console.log('Server started');

Using Classes Directly

const { LocalBridgeServer, LocalBridgeClient } = require('@able_k_saju/local-bridge');

// Create server
const server = new LocalBridgeServer({ port: 8080 });
await server.start();

// Create client
const client = new LocalBridgeClient({
    serverUrl: 'ws://localhost:8080',
    localPort: 3000
});
await client.connect();

Configuration

Server Configuration

| Option | Default | Description | |--------|---------|-------------| | port | 8080 | Port for the server to listen on | | host | 0.0.0.0 | Host address to bind to | | domain | localhost | Domain used for tunnel URLs |

Client Configuration

| Option | Default | Description | |--------|---------|-------------| | serverUrl | ws://localhost:8080 | WebSocket URL of the server | | localPort | 3000 | Local port to forward to | | localHost | localhost | Local host to forward to | | subdomain | Random | Custom subdomain for the tunnel | | authToken | null | Authentication token | | protocol | http | Protocol for local server (http/https) | | reconnectInterval | 3000 | Milliseconds between reconnect attempts | | maxReconnectAttempts | Infinity | Maximum reconnection attempts | | requestTimeout | 30000 | Request timeout in milliseconds |

Security

Authentication

LocalBridge supports optional token-based authentication. Set an auth token when creating a tunnel:

localbridge tunnel 3000 --auth my-secret-token

Self-Hosted

One of the key advantages of LocalBridge is that you can host your own server, giving you full control over your data and tunnels.

HTTPS Support

For production use, you should:

1. Deploy LocalBridge as a long-running Node.js web service
2. Point both bridge.example.com and *.bridge.example.com to that service
3. Use HTTPS/WSS at the public edge
4. Start the server with --public-protocol https --public-port 443

Render is a good fit because it supports long-running Node.js web services and WebSockets. Vercel and Netlify serverless functions are not a good fit for the LocalBridge server because the tunnel depends on persistent WebSocket connections.

Example Render start command:

localbridge server --port $PORT --domain bridge.example.com --public-protocol https --public-port 443

Architecture

┌─────────────────┐         WebSocket         ┌─────────────────┐
│                 │  ═══════════════════════> │                 │
│  External User  │                           │  LocalBridge    │
│                 │  <═══════════════════════ │     Client      │
└────────┬────────┘         HTTP/HTTPS        └────────┬────────┘
         │                                             │
         │ HTTP/HTTPS                                  │ HTTP/HTTPS
         ▼                                             ▼
┌─────────────────┐                           ┌─────────────────┐
│                 │                           │                 │
│ LocalBridge     │                           │   Your Local    │
│     Server      │                           │     Server      │
│                 │                           │   (localhost)   │
└─────────────────┘                           └─────────────────┘

1. External User makes a request to the public tunnel URL
2. LocalBridge Server receives the request and forwards it through the WebSocket tunnel
3. LocalBridge Client receives the request and forwards it to the local server
4. Your Local Server processes the request and sends the response back
5. The response flows back through the same path to the external user

Troubleshooting

Connection Refused

If you see "Connection refused" errors:

1. Make sure the LocalBridge server is running
2. Check that the server URL is correct
3. Verify the port is not blocked by a firewall

Tunnel Not Available

If you see "Tunnel not available":

1. Check that the client is connected
2. Verify the subdomain is correct
3. Try creating a new tunnel with a different subdomain

Timeout Errors

If requests are timing out:

1. Check that your local server is responding
2. Increase the request timeout: --request-timeout 60000
3. Verify network connectivity

Reconnection Issues

If the tunnel keeps disconnecting:

1. Check network stability
2. Increase reconnect interval: Create client with reconnectInterval: 5000
3. Check server logs for errors

Comparison with Similar Tools

| Feature | LocalBridge | ngrok | localtunnel | |---------|-------------|-------|-------------| | Self-hosted | ✅ Yes | ❌ No (paid) | ✅ Yes | | Free | ✅ Yes | ❌ Limited | ✅ Yes | | Custom domains | ✅ Yes | ❌ Paid | ❌ No | | Auto-reconnect | ✅ Yes | ✅ Yes | ⚠️ Unreliable | | Authentication | ✅ Yes | ✅ Yes | ❌ No | | Easy CLI | ✅ Yes | ✅ Yes | ✅ Yes | | NPM module | ✅ Yes | ✅ Yes | ✅ Yes |

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details.

Support

If you encounter any issues or have questions:

• Open an issue on GitHub
• Check the documentation

Changelog

v1.0.0

• Initial release
• CLI with tunnel, server, start, and status commands
• WebSocket-based tunneling
• Auto-reconnect functionality
• Authentication support
• Programmatic API