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.
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
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)
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
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
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.
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
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
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.
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.
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.
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).
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 requestserror message.
Protocol Specification: By default, the Beeceptor Command Line Interface (CLI) establishes connections using the HTTP protocol. To force HTTPS, include the
--httpsoption when executing the CLI command.