Cloudflare Tunnel

Cloudflare Tunnel gives your local agent a public https:// URL without port forwarding or firewall changes. Traffic stays encrypted end to end and rides Cloudflare's network.

Why use a tunnel?

Local network only	Cloudflare Tunnel
Same Wi-Fi required	Access from anywhere
IP changes	Stable URL
ws:// only	wss:// by default
Router config needed	No router or firewall changes

Quick tunnel (temporary URL)

Install cloudflared

macOS

brew install cloudflared

Windows

Download from Cloudflare's releases page.

Linux

# Debian/Ubuntu
a=$(mktemp) \\
&& curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cloudflare-main.gpg \\
&& echo 'deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared any main' | sudo tee /etc/apt/sources.list.d/cloudflared.list \\
&& sudo apt update \\
&& sudo apt install cloudflared

Start your agent

npx -y supergateway --stdio "npx @google/gemini-cli --experimental-acp" --port 8765 --outputTransport ws

Create the tunnel

cloudflared tunnel --url http://localhost:8765

Cloudflare prints a URL like https://random-words.trycloudflare.com. Use it in Agmente with protocol wss and host random-words.trycloudflare.com/message.

warning

Quick tunnels generate a new URL every run. Use a named tunnel for a stable hostname.

Named tunnel (stable URL)

1. Login:

cloudflared tunnel login

2. Create the tunnel:

cloudflared tunnel create agmente-agent

Save the generated Tunnel ID.

3. Route DNS to the tunnel:

cloudflared tunnel route dns agmente-agent agent.yourdomain.com

4. Create ~/.cloudflared/config.yml:

tunnel: <YOUR_TUNNEL_ID>
credentials-file: /Users/yourname/.cloudflared/<TUNNEL_ID>.json

ingress:
  - hostname: agent.yourdomain.com
    service: http://localhost:8765
  - service: http_status:404

5. Run the tunnel:

cloudflared tunnel run agmente-agent

6. Connect from Agmente: Use protocol wss and host agent.yourdomain.com.

Run as a service

macOS

cloudflared service install
sudo launchctl start com.cloudflare.cloudflared

Linux

sudo cloudflared service install
sudo systemctl enable --now cloudflared

Windows

cloudflared service install
net start cloudflared

Architecture

• Outbound-only: cloudflared dials out; no inbound ports opened.
• TLS from Agmente to Cloudflare, then from cloudflared to your agent.
• Low latency via the nearest Cloudflare edge.

Troubleshooting

Tunnel connects but WebSocket fails

• Ensure the agent is running on the target port:

curl http://localhost:8765

DNS not resolving

• DNS may take a few minutes after cloudflared tunnel route dns. Verify with:

dig agent.yourdomain.com

Connection drops

• Check your internet stability.
• Increase the agent's WebSocket ping interval.
• Run cloudflared as a service for reliability.

Security

warning

A tunnel exposes your agent to the internet. Protect it with a non-guessable hostname and Cloudflare Access.

1. Use a unique subdomain (for example, gemini-abc123.yourdomain.com).
2. Add authentication with Access service tokens.
3. Monitor access logs in the Cloudflare dashboard.