Skip to main content

Local Tunneling

Local Tunneling is a great way to bind a web service running on your localhost to a public endpoint. This is mainly useful when you want to expose the service running on your development machine to a dependent team member (like UI developers). In addition, this is quite helpful when you are developing a callback or a webhook to receive notifications from external services.

Tunneling with Beeceptor​

Beeceptor enables this use-case by giving you a public URL on the Internet. All the requests hitting the Beeceptor endpoint will be routed to the local machine's port, and the response will be served back to the caller.

All of the requests and responses are visible on the endpoint dashboard as usual. Any request that gets matched up with a mocking rule will get a mocked response (i.e., it won't go through tunneling). The Beeceptor CLI is an easy-to-install developer tool that helps you connect your localhost port with Beeceptor's endpoint. It works on all platforms (macOS, Windows, Linux). You can install it using NPM or download it as an independent executable file.

beeceptor--port-forwarding

Beeceptor's Local Tunnel establishes a secure connection from your local server to the internet, allowing external access without complex network configuration. It uses port 443 for all communications.

Step 1: Enable tunneling​

If you are on a Free plan, this step is not required. For convenience, Beeceptor CLI manages this for you.

Open the endpoint dashboard and enable tunneling for the endpoint.

enable-tunneling-for-endpoint

Step 2: Installation​

The Beeceptor CLI is a developer tool to help you connect the localhost port with Beeceptor's public endpoint. It is easy to install, and works on all platforms (macOS, Windows, and Linux). The Beeceptor CLI can be installed using NPM or downloaded as an independent executable file.

Option 1: Install via NPM (Node package manager)​

You can install Beeceptor CLI using Node's package manager. It is published on NPM as beeceptor-cli. If you have NPM/NodeJs installed, copy and run the following command:

npm i beeceptor-cli -g

or

yarn global add beeceptor-cli

Refer to npmjs.com/package/beeceptor-cli for more details.

Option 2: Download standalone executable​

You can download the Beeceptor CLI by clicking on the following links. Ensure that you pick the right platform.

Download Links (size ~17MB)

Decompress

The downloaded file is a tar.gz file. You can decompress it using the following command:

tar -xvf \<path-to-tar-file.tag.gz\>

Step 3: Run the Beeceptor CLI​

If you have installed via NPM simply type the following to get started:

beeceptor-cli -p port-number

beeceptor-local-tunnel-create-endpoint

Note: You may be asked to update the CLI if it is an obsolete version.

Run from downloaded binaries​

Run the CLI using following command. Here you pass the localhost port using -p parameter.

Windows: Open Power Shell or Command Prompt to run the following:

beeceptor-cli-windows -p port-number

Mac: Open Terminal app and run the following:

./beeceptor-cli-macos -p port-number

Linux: Open bash or shell and run the following:

./beeceptor-cli-linux -p port-number

Step 4: Pick an endpoint​

Create a new free endpoint​

When you pick this, the CLI will assign you a unique endpoint that will route all requests to your localhost at specified port.

localhost-tunnel-free

Note: This option follows the Free plan's limits (50 requests/day). If you need more requests, consider upgrading and authorize the upgraded endpoint.

Authorize an existing endpoint​

After installing the Beeceptor CLI, you must connect it with your Beeceptor endpoint. To do so, run the following command in the terminal with -p option and specify a port number on localhost.

Next, you are required to authorize. You’ll be prompted to launch your web-browser. Once logged in, you can grant or link a Beeceptor endpoint with this client-machine's authentication request. When you see a message "Now tunneling requests from... to this machine's port xxxx.", you are all set to receive requests from Internet to your local machine.

Example command to run: ./beeceptor-cli-macos -p 9006

authorize-cli

Step 5: Ready to receive requests​

You are all set! Any request sent to your Beeceptor's endpoint will now be routed to this port on localhost. The response served by the local service, will be sent back to the caller.

Key considerations​

  1. Timeout Handling: The service running on the local port must respond within 60 seconds. Failure to respond within this timeframe results in a timeout, leading to an error response.

  2. Mocking Rule Priority: Mocking rules take precedence over local tunneling. If an incoming request matches a predefined mocking rule, it is processed accordingly, and does not proceed to the local service. This feature is useful for selectively mocking specific requests while handling others locally.

  3. Connection Errors: If the local service is inaccessible, you may encounter errors indicating a failure to connect, such as Failed to connect to host (refused).

  4. Concurrency and Rate Limiting: The system permits a maximum of 5 simultaneous requests for tunneling. Exceeding this cap triggers rate limiting, denoted by a 429 - Too many requests error message.

  5. Protocol Specification: By default, the Beeceptor Command Line Interface (CLI) establishes connections using the HTTP protocol. To force HTTPS, include the --https option when executing the CLI command.

  6. Headless Mode: If you're using Beeceptor CLI on a server that doesn't have a user interface or web browser, use the --headless option. This approach prints the authentication token URL in the shell. You can copy this URL and open it on a device with web access to complete the authentication process.