Skip to main content
The Tunnel Manager provides secure public internet access to Maestro’s web interface using Cloudflare’s cloudflared tunneling service.

​
Overview

Cloudflare tunnels create a secure HTTPS connection from your local Maestro instance to the internet without exposing your IP address or requiring port forwarding.
Tunnels are ideal for accessing Maestro from anywhere, sharing sessions with team members, or accessing from mobile devices outside your local network.

​
Prerequisites

1

Install cloudflared

Install Cloudflare’s tunnel client:
brew install cloudflare/cloudflare/cloudflared
2

Enable Web Interface

Enable Maestro’s web server from Settings → Web Interface

​
Starting a Tunnel

Maestro automatically manages the tunnel lifecycle:
1

Enable Tunnel

In Maestro settings, enable Use Cloudflare Tunnel
2

Tunnel Starts Automatically

Maestro starts cloudflared and waits for the tunnel URL (max 30 seconds)
3

Access Public URL

Copy the generated https://*.trycloudflare.com URL to access Maestro from anywhere

​
Tunnel Status

Check tunnel status programmatically: 
interface TunnelStatus {
  isRunning: boolean;
  url: string | null;
  error: string | null;
}

const status = tunnelManager.getStatus();
console.log('Tunnel URL:', status.url);
console.log('Running:', status.isRunning);

​
API Reference

​
start(port: number)

Start a new tunnel to the specified local port.
​
port
number
required
Local port number to tunnel (1-65535)
​
success
boolean
Whether tunnel started successfully
​
url
string
Public HTTPS URL (only present if success is true)
​
error
string
Error message (only present if success is false)
const result = await tunnelManager.start(8080);

if (result.success) {
  console.log('Tunnel URL:', result.url);
  // https://abc-123-def.trycloudflare.com
} else {
  console.error('Failed:', result.error);
}

​
stop()

Stop the currently running tunnel. 
await tunnelManager.stop();
console.log('Tunnel stopped');
The tunnel process receives SIGTERM and has 3 seconds to gracefully shutdown before receiving SIGKILL.

​
getStatus()

Get current tunnel status.
​
isRunning
boolean
Whether tunnel is currently active
​
url
string | null
Public HTTPS URL (null if not running)
​
error
string | null
Last error message (null if no errors)

​
Error Handling

The tunnel manager handles common error scenarios:
Error: cloudflared is not installedSolution: Install cloudflared using the instructions in Prerequisites
Error: Invalid port number: {port}Solution: Port must be between 1 and 65535
Error: Tunnel startup timed out (30s)Solution: Check network connectivity and try again. The timeout may occur on slow connections.
Error: Connection refusedSolution: Ensure the web server is running on the specified port before starting the tunnel

​
Implementation Details

The tunnel manager spawns cloudflared as a child process: 
cloudflared tunnel --url http://localhost:{port}
​
command
string
cloudflared (uses system PATH or configured custom path)
​
args
array
['tunnel', '--url', 'http://localhost:{port}']

​
URL Detection

The manager parses cloudflared’s stderr output to extract the tunnel URL: 
https://[a-z0-9-]+\.trycloudflare\.com
Cloudflare outputs the URL to stderr (not stdout). Maestro accumulates buffer chunks to handle URLs split across multiple writes.

​
Process Lifecycle

  1. Start: Spawn cloudflared with tunnel args
  2. Monitor: Listen for URL in stderr output (30s timeout)
  3. Running: Keep process alive and maintain URL reference
  4. Stop: Send SIGTERM, wait 3s, then SIGKILL if needed
Source: src/main/tunnel-manager.ts:1

​
Security Considerations

HTTPS by Default

All tunnel URLs use HTTPS with Cloudflare’s TLS certificates

Temporary URLs

Free trycloudflare.com URLs are temporary and change on restart

No IP Exposure

Your local IP address is never exposed to the internet

Token Required

Access still requires Maestro’s security token from the web server
Free Cloudflare tunnels are not suitable for production use. For persistent, custom domains, configure a Cloudflare account with named tunnels.

​
Advanced: Custom cloudflared Path

If cloudflared is not in your system PATH, Maestro will attempt to locate it in common installation directories. You can also specify a custom path in Maestro’s configuration. Source: src/main/utils/cliDetection.ts

Build docs developers (and LLMs) love

Get started for freeTalk to us