Professional tunneling CLI that exposes local development servers to the internet
npm install rail-tunnelA professional tunneling solution that exposes your local development servers to the internet through secure WebSocket connections.
- Secure Tunneling: WebSocket-based connection with real-time request proxying
- Easy Setup: One command to expose any local service
- Railway Integration: Designed to work seamlessly with Railway's infrastructure
- Real-time Logging: Monitor all incoming requests and responses
- Cross-Platform: Works on Windows, macOS, and Linux
bash
Install globally
npm install -g rail-tunnel-cliOr use with npx (recommended)
npx rail-tunnel --help
`$3
`bash
Tunnel your local development server
npx rail-tunnel tunnel --port 3000 --remote https://your-tunnel-server.railway.appTunnel a different port
npx rail-tunnel tunnel --port 8080 --remote https://your-tunnel-server.railway.appFor development/testing with local server
npx rail-tunnel tunnel --port 3000 --remote http://localhost:9000
`📋 Commands
$3
Create a secure tunnel to expose your local service to the internet.Required Options:
-
-p, --port - Local port to tunnel (e.g., 3000, 8080)
- -r, --remote - Tunnel server URL (e.g., https://my-tunnel.railway.app)Examples:
`bash
Tunnel local Next.js app (port 3000)
rail-tunnel tunnel --port 3000 --remote https://my-tunnel.railway.appTunnel local API server (port 8080)
rail-tunnel tunnel --port 8080 --remote https://api-tunnel.railway.appDevelopment testing with local tunnel server
rail-tunnel tunnel --port 3000 --remote http://localhost:9000
`$3
Show system information and verify CLI installation.`bash
rail-tunnel info
`🗗️ Architecture
`
[Browser] → [Rail Tunnel Server] → [WebSocket] → [CLI Client] → [Local Service]
`Flow:
1. CLI connects to tunnel server via WebSocket (
/_tunnel/ws/connect)
2. Browser requests are sent to tunnel server public URL
3. Server forwards HTTP requests to CLI via WebSocket
4. CLI proxies requests to your local service
5. Responses are sent back through the same WebSocket connection
6. Browser receives the response as if it came directly from your local service🔧 Development
$3
`bash
git clone https://github.com/isaui/rail-tunnel-cli.git
cd rail-tunnel-cli
npm install
`$3
`bash
Run from TypeScript source
npx ts-node src/cli.ts tunnel --port 3000 --remote http://localhost:9000Or use dev script
npm run dev tunnel --port 3000 --remote http://localhost:9000
`$3
`bash
Build TypeScript to JavaScript
npm run buildRun production build
node dist/cli.js tunnel --port 3000 --remote https://your-server.railway.app
`$3
`bash
Terminal 1: Start your local app
npm run dev # or python -m http.server 3000, etc.Terminal 2: Start tunnel server (for local testing)
cd ../rail-tunnel && go run main.goTerminal 3: Start tunnel client
npx ts-node src/cli.ts tunnel --port 3000 --remote http://localhost:9000Test: Open http://localhost:9000 in browser
`🌐 Server Requirements
The CLI connects to a compatible Rail Tunnel server that implements:
$3
- WS /_tunnel/ws/connect?port= - WebSocket connection for tunnel client
- GET /_tunnel/health - Health check endpoint
- GET /_tunnel/info - Server information$3
- ANY /* - All other traffic is proxied through the tunnel to your local service$3
`typescript
// Server → Client (HTTP Request)
{
type: "http_request",
requestId: string,
method: string,
url: string,
headers: object,
body: any
}// Client → Server (HTTP Response)
{
type: "http_response",
requestId: string,
statusCode: number,
headers: object,
body: any
}
// Client → Server (Keep-alive)
{
type: "ping",
timestamp: number
}
// Server → Client (Keep-alive response)
{
type: "pong",
timestamp: number
}
`🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
📄 License
MIT License - see LICENSE file for details.
🔗 Related
- Rail Tunnel Server - The companion server application
- Deploy your own tunnel server on Railway
🐛 Troubleshooting
$3
"Cannot reach server"
- Ensure the tunnel server is deployed and accessible
- Verify server URL with --remote option
- Check if server health endpoint responds: curl https://your-server.railway.app/_tunnel/health"WebSocket connection timeout"
- Check firewall/corporate network restrictions
- Try different network connection
- Verify WebSocket endpoint is accessible
$3
"Local request failed"
- Verify your local service is running on the specified port
- Test local accessibility: curl http://localhost:3000
- Check if the port is already in use by another application"502 Bad Gateway"
- Local service is not responding
- Port mismatch between CLI and actual service
- Local service crashed or stopped
$3
CLI crashes or exits unexpectedly
- Check Node.js version (requires Node 16+)
- Review error messages for specific issues
- Try running with --verbose` flag if availableBuilt with ❤️ for the Railway community