Public Access to ServBay Local Development Environment Using FRP (NAT Traversal)

FRP is a high-performance, easy-to-use reverse proxy tool, especially suitable for securely and efficiently exposing local development services such as websites, APIs, and databases to the public internet. With its client-server (frpc and frps) architecture, FRP excels at network penetration through NAT and firewalls.

This guide will walk ServBay users—especially on macOS—through configuring and using the FRP client (frpc) to create secure tunnels, enabling public network access to local web services running within ServBay. Typical scenarios include remote demos, collaborative development, receiving webhook requests, and testing external APIs.

Technical Overview

FRP’s core principle is building an encrypted tunnel from your internal network machine (running frpc, i.e., your ServBay host) to a publicly accessible server (running frps). When an external user accesses your service through the public internet, their request first hits the frps public server. The frps server then relays the request via the pre-established tunnel to your internal frpc, which in turn forwards it to the local service running in ServBay (such as your website or API). The service’s response is returned by the same path in reverse to the external user.

This technique neatly bypasses internal firewall and router restrictions, enabling the exposure of internal services to the outside world. FRP supports protocols like TCP/UDP/HTTP/HTTPS, providing robust remote access capabilities for the ServBay development environment.

Application Scenarios

Combining ServBay and FRP allows you to effortlessly handle these development scenarios:

• Remote Demonstration & Collaboration: Present local in-development websites or apps to team members or clients without deploying to a remote server.
• Webhook Testing: Receive webhook notifications from third-party services (such as GitHub, Stripe, WeChat Pay, etc.) and debug handler logic locally.
• API Integration Testing: Expose local backend APIs to external frontend developers or partners for joint testing.
• Mobile Development Testing: Access the local ServBay environment directly from mobile devices for cross-device compatibility checks.
• Temporary Sharing: Quickly share local files or services without complex configurations.

Prerequisites

Before setting up FRP, ensure you meet these requirements:

1. ServBay Installed & Running: ServBay is successfully installed and running on your macOS machine, and the local service you wish to expose (e.g., your website) is configured and accessible via local browser.
2. A Publicly Accessible FRP Server (frps): You need a server with a public IP address, where the FRP server (frps) is deployed and running. This guide focuses on client (frpc) configuration.
3. Public Domain Name (Optional, Recommended for HTTP/HTTPS): If you plan to access your service by domain, you should own a domain name and be able to set its DNS records.
4. FRPC Client Installed: The FRPC client is not included with ServBay—you must download and install it separately.

Environment Preparation & FRPC Client Installation

Follow these steps to install the FRPC client (frpc) on your macOS machine running ServBay.

1. Download the FRP Client: Visit the FRP GitHub Releases page and download the latest version of FRP for your macOS architecture.

   • For Apple Silicon (M1/M2/M3, etc.), download the frp_*.darwin_arm64.tar.gz file.
   • For Intel architecture, download the frp_*.darwin_amd64.tar.gz file.

2. Install the FRP Client: Extract the downloaded file and copy the frpc executable to a directory in your system PATH, such as /usr/local/bin, allowing you to run frpc from any terminal location.

   Note: The version (0.52.3 at the time of writing) and architecture (darwin_arm64) in the following commands may become outdated—please adjust according to the file you downloaded.

   # Suppose you downloaded frp_0.52.3_darwin_arm64.tar.gz
   # Switch to your download directory
   cd ~/Downloads
   
   # Extract the file (replace with your actual filename)
   tar -zxvf frp_0.52.3_darwin_arm64.tar.gz
   
   # Enter the extracted directory (replace with your directory name)
   cd frp_0.52.3_darwin_arm64
   
   # Copy the frpc executable to /usr/local/bin
   sudo cp frpc /usr/local/bin/
   
   # (Optional) You may copy the frpc.toml example to your home directory
   # cp frpc.toml ~/

   Enter your user password when prompted by the sudo command.

3. Verify Installation: Open a new terminal window and confirm that frpc is installed and in the PATH:

   frpc -v
   # Expected output: frpc version 0.52.3

   If you see the version, installation was successful.

Configuring the FRP Client Tunnel

FRP client configuration is mainly done via a file called frpc.toml (TOML format is recommended for recent FRP versions). You’ll create or edit this file to specify how frpc connects to your FRP server (frps), and how to map your local ServBay service to the public internet.

frpc.toml Configuration Explained

Below is a basic sample structure of an frpc.toml file, demonstrating connection details and how to define one proxy:

# frpc.toml - Example FRP client configuration

# [common] section: Client-to-server connection config
serverAddr = "your-frps-server.com" # FRP server’s public IP or domain
serverPort = 7000 # Server port for client connections (default 7000)

# Authentication config (recommended: use token)
auth.method = "token"
auth.token = "your_authentication_token" # Must match FRP server’s authentication token

# Optional: Enable TLS encryption for client-server connection for enhanced security
# tls_enable = true

# [[proxies]] section: Define one or more proxy tunnel configs
[[proxies]]
name = "my-web-service" # Unique proxy name within this .toml file
type = "http" # Proxy type: http, https, tcp, udp, stcp, xtcp, etc.
localIP = "127.0.0.1" # IP of your local service, defaults to 127.0.0.1
localPort = 80 # Port of your local service (e.g., default HTTP port in ServBay)
customDomains = ["servbay.your-domain.com"] # Public domain for access (http/https only). **Domain must resolve (DNS) to your FRP server**.

# More proxies can be added via additional [[proxies]] sections
# [[proxies]]
# ... (another service’s proxy config)

Setting	Section	Description
serverAddr	[common]	FRP server (frps) public IP or domain.
serverPort	[common]	Server port for client connection, default 7000. Adjust to match your server’s config.
auth.method	[common]	Authentication method to connect to server, commonly token. Must match server config.
auth.token	auth (under [common])	Authentication token matching server value—keep it secret.
tls_enable	[common]	Enable TLS encrypted connection (recommended: true for higher security).
[[proxies]]	Root	Define one or more proxy tunnels (array). Each [[proxies]] block represents a unique mapping rule.
name	[[proxies]]	Name of the current proxy tunnel—must be unique within the file. Recommend meaningful names.
type	[[proxies]]	Proxy protocol type. Common: http, https, tcp, udp. Use the type matching your local service.
localIP	[[proxies]]	IP for the local service—defaults to 127.0.0.1 (rarely changed).
localPort	[[proxies]]	Local service port. For example, ServBay HTTP defaults to 80, HTTPS to 443. Other services: MySQL 3306, PostgreSQL 5432, etc.
remotePort	[[proxies]]	(For tcp/udp only) The external port on the FRP server. Users access via serverAddr:remotePort.
customDomains	[[proxies]]	(For http/https only) The domain(s) through which your service is accessed. Must be DNS-resolved to your FRP server’s public IP.
subdomain	[[proxies]]	(For http/https only, if server supports) If subdomain_host is set on server, use this to specify a subdomain, accessed as sub.subdomain_host. Mutually exclusive with customDomains.
[proxies.plugin]	[[proxies]]	Configure special plugins such as https2https for handling local HTTPS services.
hostHeaderRewrite	[proxies.plugin] or [[proxies]] (depends on type/plugin)	Rewrite Host header on forwarded requests—critical for domain-based virtual host (vhost) configs in ServBay. Must match the domain set in ServBay.

Typical Example: Mapping a ServBay HTTPS Website

By default, ServBay configures your sites with HTTPS and manages the SSL certificates. To expose your local HTTPS service publicly via FRP, you’d typically use the https proxy type, often with the https2https plugin, or simply forward port 443 with a tcp proxy. Given that ServBay’s vhost setup depends on the Host header, the most common approach is using a https proxy with hostHeaderRewrite.

Here’s how to expose a ServBay HTTPS site (e.g., a local website at servbay.test) to a public domain (e.g., test-frp.servbay.app) via FRP. Ensure your public domain resolves (via DNS CNAME or A record) to your FRP server (frps.servbay.demo)'s public IP.

Create a frpc.toml file (e.g., at ~/frpc.toml) and add:

# Example frpc.toml – Map ServBay HTTPS Website

# [common]: FRP server connection config
serverAddr = "frps.servbay.demo" # Replace with your FRP server address (IP or domain)
serverPort = 7000 # Replace with your FRP server port

auth.method = "token"
auth.token = "servbay_demo_token" # Replace with the authentication token set on your server

# Recommended: Enable TLS encryption between client and server
tls_enable = true

# [[proxies]]: Map ServBay HTTPS site
[[proxies]]
name = "servbay-website-https" # Proxy name, can customize (e.g., servbay-test-site)
type = "https" # Proxy type is HTTPS

# Configure exposed public domain. Ensure domain resolves to FRP server IP.
customDomains = ["test-frp.servbay.app"] # Replace with your public domain

# Forwarding details to the local ServBay service
localIP = "127.0.0.1" # ServBay normally listens on loopback
localPort = 443 # ServBay’s default HTTPS port

# IMPORTANT: Rewrite Host header to match the ServBay local domain
# ServBay’s web server (e.g., Nginx/Caddy) uses this header for vhost routing.
hostHeaderRewrite = "servbay.test" # Replace with your ServBay local site domain

# Optional: Set custom header for backend to identify tunnel source
[proxies.requestHeaders.set]
x-from-where = "frp-tunnel"

Update serverAddr, serverPort, auth.token, customDomains, and hostHeaderRewrite to match your actual configuration.

Why is hostHeaderRewrite Important?
ServBay leverages a web server (such as Nginx or Caddy) to serve your local websites, usually routing based on the Host header. When a request comes through the FRP tunnel, the original Host header reflects the public domain (test-frp.servbay.app) instead of the internal domain (servbay.test). If you don't set hostHeaderRewrite, ServBay’s web server may not find the correct vhost, resulting in a 404 error or wrong site output. Setting hostHeaderRewrite to your local ServBay website domain is essential.

Launching FRP Client Service

Once your frpc.toml is saved, open a terminal, change directory to where the file is located (if in your home directory as ~/frpc.toml, you can specify the full path anywhere), then run:

# If frpc.toml is in the current directory
frpc -c frpc.toml

# If frpc.toml is in your home directory
# frpc -c ~/frpc.toml

This runs frpc in the foreground and attempts to connect to the frps server. Upon success, you’ll see logs indicating the tunnel is established and services are being proxied.

If you’d like frpc to run in the background, use nohup or macOS’s launchctl. For example, with nohup:

# If frpc.toml is in your home directory
nohup frpc -c ~/frpc.toml &

nohup redirects output to the nohup.out file and detaches the process. Note: launchctl is more appropriate for background Unix services on macOS, but setup is more complex and outside the scope of this guide.

Service Verification & Log Diagnostics

Service Verification

After you start frpc and the logs indicate a successful connection, open a browser and visit the public domain you set in frpc.toml (e.g., https://test-frp.servbay.app). Check the following:

• Browser loads your page without connection or certificate errors (for HTTPS).
• HTTP 200 or other expected status code is returned.
• Content matches what you see when accessing https://servbay.test locally in ServBay.
• For HTTPS, confirm that the browser shows a secure padlock and the SSL certificate is valid for your public domain.

Log Diagnostics

FRP client logs are critical for diagnosing connection and proxying issues. By default, running frpc -c frpc.toml outputs logs to the terminal. Watch these logs for errors or warnings.

For more detailed output useful for troubleshooting, run in debug mode:

frpc -c frpc.toml --log_level debug

If you have log_file set in your frpc.toml (e.g., log_file = "/var/log/frpc.log"), logs go to the specified file. You can monitor them in real time with tail -f /path/to/your/frpc.log.

Common Issue Troubleshooting

If you encounter issues while configuring or using FRP, refer to these common problems and solutions:

Symptom	Solution
Failed to authenticate to FRP server	Check if [common]’s auth.token and auth.method in frpc.toml exactly match the server (frps) settings. Also check server logs for authentication errors.
Public domain can’t be accessed or resolves incorrectly	Ensure that the domain in customDomains in frpc.toml is correctly set in DNS (CNAME/A record) to your FRP server's public IP. Use ping your-frp-domain.com or an online tool to verify DNS.
Public domain returns FRP welcome page	Generally means DNS is correct but FRP isn’t proxying the domain. Check that customDomains in frpc.toml matches the accessed domain, proxy type is correct (http/https), and server is configured to allow that domain.
Local port occupied or service not running	Ensure ServBay is running and that the service you’re exposing (e.g., website) is started and listening on the localPort you set. Use lsof -i :PORT to check if something is using that port.
Tunnel disconnects or is unstable	Check network stability of both your ServBay host and the FRP server. Consider increasing heartbeat timeout (e.g., heartbeat_timeout = 30), or pool_count in [common]. Check for resource limits or server issues.
HTTP access redirects to HTTPS	Check your site’s local web server (Nginx/Caddy) config in ServBay—if it forces HTTP to HTTPS. To expose HTTP, use type = http and remove plugin configs. For HTTPS, ensure correct type and certificate usage.
HTTPS certificate errors (browser warning)	If your local ServBay site uses a self-signed or ServBay CA cert, browsers may warn about trust. This is expected. To avoid warnings, install the ServBay User CA on your device, or use https2http/https2https plugin and specify cert files, or consider getting a valid public certificate on the server. Note that when using the https type with hostHeaderRewrite, ServBay handles SSL; browser warnings depend on whether the local certificate is trusted.
404 errors when accessing	Check if hostHeaderRewrite in frpc.toml matches your ServBay local site domain (e.g., servbay.test). Host header mismatch prevents web server from finding the right vhost.
FRP server firewall blocks connections	Make sure your FRP server allows inbound connections on serverPort (default 7000) and any ports you set for services (e.g., HTTP 80, HTTPS 443, or remotePort for TCP/UDP).
Mac firewall blocks connections	Ensure your macOS machine isn't blocking outbound connections to FRP server’s serverPort. Also, make sure there are no local rules blocking ServBay’s service ports (localPort) for 127.0.0.1.
FRPC log shows successful connection but service unreachable	May be a server-side configuration issue or a network problem between server and client. Check FRP (frps) server logs for errors or clues. Confirm relevant forwarding or domain mapping rules exist on the server.

Benefits & Security Advice for FRP in ServBay Environments

Combining FRP with ServBay offers tremendous flexibility and convenience for developers:

• Multi-Protocol Support: FRP handles HTTP, HTTPS, TCP, UDP, etc.—not just web services, but also databases (MySQL/PostgreSQL/MongoDB), Redis, SSH, and more within ServBay.
• Flexible Configuration: Easily configure multiple proxy tunnels via a simple TOML file, exposing multiple sites or services at once.
• Open Source & Control: FRP is a mature open-source project, giving you full control over your network tunneling and reducing dependence on third-party platforms.
• Security: With support for auth tokens, TLS encrypted tunnels (tls_enable = true), and ServBay’s own security features (like SSL management), you can build a highly secure development setup.

Security Recommendations:

• Enable TLS Encryption: Strongly recommended—set tls_enable = true in [common] to encrypt client-server communication.
• Use Strong Auth Tokens: Choose complex, hard-to-guess auth.token values, and rotate them periodically.
• Limit Exposed Services: Only expose ports/services that need public access.
• Prefer Domains over Public IP: For HTTP/HTTPS, use customDomains for domain-based access rather than direct IP/port access (when possible).
• FRP Server Security: Lock down your FRP server—only open necessary ports and set firewall rules.
• Consider Access Controls: Where supported, restrict access based on IP or other advanced rules.

By following these steps and best practices, you should be able to successfully and securely expose local development services in ServBay to the public internet via FRP, greatly streamlining your workflow.