BasicsPipelinesActions & ServicesEnvironmentsIntegrationsTargetsDomainsSelf-HostedAgents & TunnelsYAMLBuddy GitTroubleshootingAPI

Tunnels

A tunnel allows you to expose a local application or service to the internet through a hidden, secure remote connection. This enables developers to easily test and share their services without the need to deploy a full environment. Buddy offers two types of tunnels:

  • Ephemeral Tunnel
  • Persistent Tunnel

Ephemeral tunnel

Ephemeral Tunnel is a temporary tunnel that is launched on demand and remains active only for a limited time until the process is completed. Key features:

  • Short lifespan - The tunnel remains active only until the session is interrupted (e.g., terminal closed or process finished). Once the tunnel is shut down, all its parameters and the assigned URL are discarded.
  • Quick tests and demos - Perfect for one-time sharing of a local application for client presentations, manual testing, or quick debugging on a remote device.
  • Session-level security - The tunnel can be protected with a password (Basic Auth) and restricted by an allowlist of IP addresses and User-Agents.

Image loading...TCP ephemeral tunnel configuration

Persistent tunnel

Persistent tunnel - is a tunnel configured to operate continuously. Its configuration is retained across server restarts. Key features:

  • Stable, predictable URL - After configuring the tunnel, the URL does not change, which allows it to be conveniently used as a long-term endpoint.
  • Long-term test environment - Persistent Tunnel is suitable for environments where a specific path (address) needs to remain available for many days or weeks, e.g. during QA testing.
  • Permanent security configuration - After a one-time setup of verification rules (Basic Auth, IP/User-Agent whitelist), the same rules remain in effect continuously, with no need for reconfiguration.

How to add tunnels?

To create a new tunnel, select Tunnels from the main menu on the left, then click the Add Tunnel button on the right. A list of available options will expand, divided into two sections: Ephemeral Tunnel and Persistent Tunnel.

Image loading...Creating a new tunnel a Buddy

Ephemeral Tunnel

In this section, you will find instructions for running the tunnel on platforms such as:

  • Linux x64
  • Linux ARM64
  • macOS ARM64
  • Windows x64

By selecting the appropriate option, you download and run the client, which will establish a temporary tunnel to your application. Once the process or terminal is closed, the tunnel will automatically terminate.

As an example, we'll run a temporary tunnel via Homebrew:

bash
bdy HTTP --token <TOKEN> -l --useragent "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/137.0.0.0 Safari/537.36" -w 192.168.2.1 -b test-my-app -d ctrl.sh http://localhost:4000
$

After a successful execution the terminal will show:

Buddy

Status:                       OPEN
DNS:                          OK
Type:                         HTTP
Region:                       EU
Target:                       http://localhost:4000
HTTP:                         Ver. 1.1
Entry:                        https://test-my-app.eu-1.ctrl.sh

Latencies
  Region:                     27ms
  Target:                     1ms

Connections
  Current:                    1
  Total:                      21

Requests (use arrows ↑↓ to inspect & `enter` to retry)
-------------------------------------------------------------------------------------------------------
          GET /_next/image?url=%2Fassets%2Fimages%2Fnew%2Fmain%2Fphotos%2Fpipelines-3.png& 200 in 1ms
          GET /assets/images/new/main/cards/card-3.png                                     200 in 9ms
          GET /assets/images/new/main/cards/card-2.png                                     200 in 9ms

In the Dashboard, you can also view the configuration. You can modify or delete it directly from the Dashboard, as well as view the Requests Log.

Image loading...Ephemeral tunnel view

Persistent tunnel

  • Machine with pre-installed agent - If you already have a running Buddy agent, select this option to immediately connect this host as a tunnel endpoint.
  • Linux x64 - Adds an agent and creates persisten tunnel for Linux x64.
  • Linux ARM64 - Adds an agent and creates persisten tunnel for Linux ARM64.
  • macOS ARM64 - Adds an agent and creates persisten tunnel for macOS.
  • Windows x64 - Adds an agent and creates persisten tunnel for Windows.

Tunnel configuration

The tunnel configuration section allows you to define how the local service will be exposed externally. Below are descriptions of all available tunnel types and their fields.

1. Authenticated HTTP

Image loading...Authenticated HTTP tunnel

  • Subdomain + Domain - The minimum subdomain length is 5 characters. You can use one of the available domains or your own domain that you have purchased.
  • Target - Address of your server, e.g., http://localhost:4000/.
  • HTTP BA Username - Login for Basic Auth, np. user.
  • HTTP BA Password - Password for Basic Auth, np. P@ssw0rd123.
  • Flags (optional).
  • Whitelist IPs & Subnets - List of allowed addresses/IPs (CIDR), e.g. 192.168.2.0/24.
  • Whitelist User-Agents - User-Agent headers permitted to access the service.
  • Rewrite Host Header (optional) - If the backend requires a different host, e.g. mywebpage.com.
  • Request Header / Response Header (optional) - Additional HTTP headers to include in the request.
  • TLS CA Certificate for TLS Authentication (optional) - PEM file with CA certificate, if the backend uses a self-signed certificate.
  • Circuit Breaker (optional) - Error request threshold (in %) that triggers fast-fail, e.g. 10.
  • Timeout - Time (s) to wait for a server response, e.g. 30.
  • Region - Choose a region (e.g. Auto-detect, US, EU)

2. HTTP

Image loading...HTTP tunnel

  • Subdomain + Domain - The minimum subdomain length is 5 characters. You can use one of the available domains or your own domain that you have purchased.
  • Target - Address of your server, e.g., http://localhost:4000/.
  • Flags (optional).
  • Whitelist IPs & Subnets - List of allowed addresses/IPs (CIDR), e.g. 192.168.2.0/24.
  • Whitelist User-Agents - User-Agent headers permitted to access the service.
  • Rewrite Host Header (optional) - If the backend requires a different host, e.g. mywebpage.com.
  • Request Header / Response Header (optional) - Additional HTTP headers to include in the request.
  • TLS CA Certificate for TLS Authentication (optional) - PEM file with CA certificate, if the backend uses a self-signed certificate.
  • Circuit Breaker (optional) - Error request threshold (in %) that triggers fast-fail, e.g. 10.
  • Timeout - Time (s) to wait for a server response, e.g. 30.
  • Region - Choose a region (e.g. Auto-detect, US, EU)

3. TLS

Image loading...TLS tunnel

  • Subdomain + Domain - The minimum subdomain length is 5 characters. You can use one of the available domains or your own domain that you have purchased.
  • Target - Address of your server, e.g., http://localhost:4000/.
  • TLS Private Key (PEM)
  • TLS Certificate (PEM)
  • TLS CA Certificate for TLS Authentication (opcjonalnie)
  • TLS Termination at - Region / Agent / Target
  • Whitelist IPs & Subnets - List of allowed addresses/IPs (CIDR), e.g. 192.168.2.0/24.
  • Timeout - Time (s) to wait for a server response, e.g. 30.
  • Region - Choose a region (e.g. Auto-detect, US, EU)

4. TCP

Image loading...TCP tunnel

Uzupełnij pola:

  • Subdomain + Domain - The minimum subdomain length is 5 characters. You can use one of the available domains or your own domain that you have purchased.
  • Target - Address of your server, e.g., http://localhost:4000/.
  • Whitelist IPs & Subnets - List of allowed addresses/IPs (CIDR), e.g. 192.168.2.0/24.
  • Timeout - Time (s) to wait for a server response, e.g. 30.
  • Region - Choose a region (e.g. Auto-detect, US, EU)

Available domains

  • 24h.sh
  • ctrl.sh
  • edit.sh
  • key.sh
  • upload.sh

Flags

  • Verify certificate - Enabling this option makes the tunnel verify the TLS/SSL certificate before establishing a connection with the target server (backend). If the certificate is self-signed, expired, or not issued by a trusted CA, the connection will be rejected.

  • Compression - Enables compression (gzip/deflate) of data transmitted through the tunnel between the client and your application.

  • Force HTTP/2 - Forces the use of the HTTP/2 protocol for communication between the client and the tunnel server (and then further to the backend if it also supports HTTP/2).

  • Log requests - Enabling this option logs every incoming request to the tunnel (including HTTP method, path, headers, etc.).

Image loading...Tunnel logs

Last modified on Jul 3, 2025

Previous pageServer AgentsNext pageAgents & Tunnels CLI