Fanout Tunnels

Q: How do several developers receive the same webhook at once?

Create a tunnel with Delivery set to Fanout , add your teammates to the team, and have each of them run the connect command against their own local port. Register the tunnel's address with the sending platform once. Every incoming request is then delivered to every connected device at the same moment.

Q: Which device replies to the platform sending the traffic?

The primary device. The first device to connect takes that role, Set primary on the Devices tab moves it, and another device takes over if the primary disconnects. Every other device receives a complete copy of the request and its response is discarded. The sender receives one answer.

Q: Can I convert an existing tunnel to Fanout?

Yes. Open the tunnel's settings and change Delivery mode to Fanout . The address, the subdomain and every other setting stay as they were. Release a reserved port and disconnect any TCP or TLS device first. Changing delivery needs the Admin role.

Q: How do I keep unwanted callers off the URL?

Turn on Signature Verification in the tunnel's settings and supply the signing secret from the platform. Requests without a valid signature are refused before any device receives them. An IP allowlist restricts the address to the ranges the platform publishes, and Header Authentication checks a header of your own on scripts and API clients.

Summary

A Fanout tunnel gives your team one permanent HTTPS address such as https://example.eu.localport.dev. Register it once with Stripe, GitHub, Shopify or any platform that sends you events, and every teammate who connects receives a copy of each request on their own machine.

What is a Fanout tunnel?#

A Fanout tunnel is a public HTTPS address that delivers a copy of every incoming request to every connected device. It carries HTTP traffic only.

One request arrives at the tunnel address, and every connected device receives its own copy.

Fanout is one of two delivery modes on a tunnel. Standard delivery carries each request to one device. Fanout carries it to all of them, with the original headers and body, at the same moment.

Create a Fanout tunnel#

1. Open dashboard.localport.io and go to Tunnels.

2. Click Create tunnel.

3. Enter a name, choose a region, select Fanout under Delivery, and click Create Tunnel.

Every field here can be changed later, and so can the delivery mode.

Name identifies the tunnel in the dashboard. It does not appear in the public address.
Region is EU, US or Asia Pacific, and it forms part of the address. Choose the one closest to your team.
Custom Domain serves the tunnel on a domain you own. Optional, and can be attached later.
Delivery set to Fanout gives every connected device its own copy of each request.
Force HTTPS redirects plain http:// requests to the secure address. On by default.

Delivery starts on Standard. Select Fanout, then copy the command the dashboard builds for you.

Get your connect command#

Creating the tunnel opens the Connect step, which builds the command. The Connect button on the tunnel reopens it, and every teammate copies their own command from the same place.

Each machine that connects runs the Localport agent. The agent is open source. Read what runs on your machine before you run it. See Installation.

Preset fills in the protocol and port for you. Select your framework, or select Custom and enter them yourself.
Protocol is http, the only option on a Fanout tunnel.
Local Address is where the agent delivers traffic. It defaults to localhost and accepts another machine on your network.
Name labels this connection in the agent output and names the row on the Devices tab. Optional.
Run without the live UI replaces the live panel with plain log lines. Use it on a server, in CI, and inside Docker or systemd.
Token is the tunnel's credential, shared by everyone who connects to it. Treat it like a password.

localport http 3000 --token tok_k8f2 --region eu

The port is per machine. One teammate serves on 3000 and another on 8080, and each agent delivers to the port that person passed. Every flag is documented in the CLI reference.

Keep the token off shared command lines

On a machine other people use, a token passed as an argument appears in the process list. Set LOCALPORT_TOKEN instead, or point LOCALPORT_TOKEN_FILE at a file only your user can read. See Environment Variables.

Run the tunnel#

Run the command in a terminal.

Run the command and the shared address appears under Forwarding, the same on every machine.

Forwarding is the address, and it is identical on every machine connected to this tunnel. Local is the port on your own machine. Press Ctrl+C to disconnect that machine. The tunnel keeps serving every other connected device.

Choose the address your team registers#

Every tunnel is created with a generated address. To set your own, enter it in the Subdomain field of the tunnel's settings. The dashboard checks availability as you type.

Check whether the subdomain you want is available before you save it.

A subdomain is 12 characters or more, and a label is unique across every region. To serve the tunnel on a domain you own, see Custom Domains.

The address survives restarts and reconnects, and it stays yours through periods when nobody is connected. Register it with the platform once.

https://example.eu.localport.dev/webhooks/stripe

Use a domain you own

Attach a domain and the endpoint becomes https://hooks.acme.com/webhooks/stripe, on a name that outlives any single tunnel. Detailed guide: Custom Domains.

The primary device#

One device is the primary. Its response is the one returned to the sender, and every other connected device receives the same request in full while its response is discarded.

The first device to connect becomes the primary. Set primary on the Devices tab moves the role. If the primary disconnects, one of the remaining devices takes over.

The Devices tab lists everyone connected, and Set primary moves which device answers.

The Devices tab appears once a tunnel's delivery is Fanout. Each row shows the device name, how long it has been connected and the address it connected from. The header above them carries the tunnel's live connections and its total requests processed. Disconnect drops one device and Disconnect all clears the tunnel.

Every device runs the request

A full copy of each request reaches every connected device, so anything your code writes or sends happens on all of them. A handler that charges a card, sends an email or inserts a row does it once per connected device.

Adding teammates#

An Invite teammates row appears under the connect command as soon as a Fanout tunnel is created. Enter an email address, choose Developer or Admin, and send it. You can also invite people from the team's Members page.

Once someone accepts, they open the tunnel, click Connect, and run the command the dashboard builds for their own port.

A Developer can open the tunnel, copy the command, connect and watch the Devices tab. An Admin can also create tunnels, change the delivery mode, move the primary and disconnect devices.

Connections are independent of each other.

A device that connects while the tunnel is running receives from the next request onward.
Ctrl+C disconnects that one device. Everyone still connected keeps receiving.
With nobody connected, the tunnel and its address stay saved to your account. A request arriving then is refused, and nothing is stored or replayed.

Each connected device counts as an active tunnel on your plan. See pricing.

Access controls#

Anyone with the address, until you restrict it. A Fanout tunnel carries the same controls as any HTTP tunnel, and every one of them is checked before any device receives a copy.

Control	What it does
Signature Verification	Checks the signature GitHub, Stripe, Shopify or Slack attaches to a webhook, against your signing secret. Webhook Signature Verification
Inbound IP Whitelist	Admits only the addresses and CIDR ranges you list, such as the ranges the sending platform publishes. IP Allowlists
Header Authentication	Requires a header you name, carrying a value you set. Suits scripts and API clients. Header Authentication
Network IPs	Limits the addresses your team may connect the agent from, such as an office range or a VPN.

Signature verification fits a webhook endpoint. The sender proves the request with its own HMAC and needs no credential from you. Basic Authentication is available too, and most platforms will not send credentials, so confirm the sender supports it first. The full set is covered in HTTP Tunnels.

A request is checked against the IP allowlist, then the password, then your header rules, then the webhook signature. The first refusal ends the request and no device sees it.

Control access by identity

A fleet is a group of your machines that is private by default. Every caller proves who it is before the connection is accepted, and reaches only the devices you grant it. Detailed guide: Remote Access.

Switch an existing tunnel to Fanout#

Open the tunnel's Settings, set Delivery mode to Fanout, and save. The address, the subdomain and every other setting are unchanged. Switch to Fanout in the row menu on the Tunnels list does the same thing.

Saving asks you to confirm. Your connected devices then reconnect on their own under the new mode. Changing delivery is an Admin action.

Fanout works on HTTP only. The conversion is refused while the tunnel holds a reserved port, and while a device is connected over TCP or TLS. Release the port and disconnect the device first.

Switching back to Standard while several devices are connected is refused, and the dashboard names the devices to disconnect.

Common uses#

Webhooks from Stripe, GitHub, Slack or Twilio, delivered to everyone working on the integration.
A tester triggers a flow once and the developer sees the same request arrive on their own machine.
A staging server connected alongside a laptop, receiving the same traffic.
Several people debugging one handler, each with their own breakpoints.

Frequently asked questions#

How do several developers receive the same webhook at once?

Create a tunnel with Delivery set to Fanout, add your teammates to the team, and have each of them run the connect command against their own local port. Register the tunnel's address with the sending platform once. Every incoming request is then delivered to every connected device at the same moment.

Which device replies to the platform sending the traffic?

The primary device. The first device to connect takes that role, Set primary on the Devices tab moves it, and another device takes over if the primary disconnects. Every other device receives a complete copy of the request and its response is discarded. The sender receives one answer.

Does the URL change when someone joins or leaves?

No. The address belongs to the tunnel and is saved to your account. It survives restarts, reconnects and periods with nobody connected. An endpoint registered with a platform never needs editing.

Does everyone need to use the same local port?

No. The port is per machine. One teammate can serve on 3000 and another on 8080, and each agent delivers traffic to the port that person passed on the command line.

Can I convert an existing tunnel to Fanout?

Yes. Open the tunnel's settings and change Delivery mode to Fanout. The address, the subdomain and every other setting stay as they were. Release a reserved port and disconnect any TCP or TLS device first. Changing delivery needs the Admin role.

Does Fanout use more bandwidth than a Standard tunnel?

Yes. Every connected device receives a full copy of each request, and each copy counts toward the bandwidth your plan includes. See pricing for the allowance on your plan.

Do WebSockets work on a Fanout tunnel?

A request that asks to switch protocols, such as a WebSocket handshake, is served by the primary device alone for the rest of that connection. A live bidirectional stream cannot be split across machines. Ordinary HTTP requests on the same tunnel continue to reach every connected device.

Can a Fanout tunnel carry TCP?

No. Fanout copies each request, and a raw stream has no request boundary to copy. A device connecting as tcp or tls to a Fanout tunnel is refused. Use a TCP tunnel for a database, SSH or a game server, where the whole connection reaches one device.

How do I keep unwanted callers off the URL?

Turn on Signature Verification in the tunnel's settings and supply the signing secret from the platform. Requests without a valid signature are refused before any device receives them. An IP allowlist restricts the address to the ranges the platform publishes, and Header Authentication checks a header of your own on scripts and API clients.

What is the difference between a Fanout tunnel and a fleet?

A Fanout tunnel is one address that every connected device receives. On a fleet, each device has its own address, callers present a certificate you issued, and a request reaches the one device it was addressed to.