relayy-tunnel

Create a public URL for your local server in seconds.

relayy-tunnel is a simple command line tool that opens a temporary public tunnel to your localhost app. It is useful for demos, webhook testing, and sharing local work without deployment.

Features

• One-command tunnel creation
• Human-friendly, shareable public URL
• Temporary tunnels with automatic expiry
• Works with any local HTTP app running on localhost
• Lightweight CLI experience with clear terminal output

Installation

Global install

npm install -g relayy-tunnel

Run without global install

npx relayy 3000

Quick Start

1. Start your local app on a port, for example 3000.
2. Run the CLI:

relayy 3000

3. Copy the public URL shown in terminal.
4. Open the URL in a browser or use it in webhook providers.

Usage

relayy <port>

Example:

relayy 5173

When connected successfully, you will see:

• A confirmation that the tunnel is live
• Your generated public URL
• Tunnel expiry time

Real Example

If your local API runs at:

• http://localhost:3000/api/health

and the CLI gives you this URL:

• https://relayy.up.railway.app/calm-lion-a1b2

Then this public URL will forward to your local endpoint:

• https://relayy.up.railway.app/calm-lion-a1b2/api/health

How It Works

1. The CLI opens a WebSocket connection to the relay server.
2. It sends a register message with your local port.
3. The server creates a tunnel ID and returns a public URL.
4. Incoming public requests are forwarded to your local app.
5. The CLI sends the local response back through the tunnel.

Requirements

• Node.js 18+
• A running local HTTP server on localhost
• Internet access (CLI connects to hosted relay server)

Behavior and Limitations (Current Version)

• Tunnel duration is temporary and expires automatically.
• If your local app is down, requests return a generic local server error.
• Response headers are not fully mirrored back yet.
• This version is optimized for simple HTTP forwarding workflows.

Troubleshooting

Command not found: relayy

Use one of these:

• Install globally: npm install -g relayy-tunnel
• Run with npx: npx relayy-tunnel 3000

Usage shown instead of starting

The CLI needs a port argument.

relayy 3000

Tunnel created but requests fail

Check:

• Your local app is running
• Correct port is passed to the CLI
• Local endpoint path exists

Tunnel expired message appears

Tunnels are temporary by design. Start a new tunnel by running the command again.

Security Notice

Do not expose sensitive local services or admin panels without authentication. Anyone with the public URL can access forwarded routes while the tunnel is active.

Contributing

Issues and improvements are welcome. If you find a bug, include:

• Your command used
• Node.js version
• Expected behavior
• Actual behavior

License

MIT