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.

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.

Things to consider​

  1. If the service running on the local port didn't respond within 60 seconds, the request times-out and error response will be served.
  2. The mocking rule gets precedence over local tunneling. If a mocking rule is matched, the request never reaches to the localhost's port. This helps you mock some requests and serve rest from the localhost.
  3. You shall see errors like Failed to connect to host (refused) if the service on the local port is not reachable.
  4. By default the Beeceptor CLI connects via HTTP protocol. You can pass --https as an argument to enforce HTTPS protocol.
  5. Max 5 concurrent (open) requests are allowed for tunneling currently. When this limit is hit, the requests are served with 429 - Too many requests error.