tunnels-for-agents

license	Apache-2.0
name	tunnels-for-agents
description	Tunneling for AI agent systems — exposing local services to the internet and connecting agents across network boundaries. Covers ngrok, Cloudflare Tunnel, Tailscale Funnel, bore, localhost.run, SSH tunneling, and WireGuard. Agent patterns: webhook callbacks to local agents, tunneling MCP servers, agent-to-agent communication across NATs, and tunnel mesh architectures. Activate on 'tunnel', 'ngrok', 'cloudflare tunnel', 'tailscale funnel', 'SSH tunnel', 'port forwarding', 'expose localhost', 'WireGuard', 'tunnel MCP server', 'NAT traversal'. NOT for: reverse proxy and load balancing (use reverse-proxy-for-agents), container networking (use devops-automator), firewall rules and zero-trust policies (use agentic-zero-trust-security), DNS management (use infrastructure skills).
allowed-tools	Read,Write,Edit,Bash,Glob,Grep,WebSearch,WebFetch
metadata	{"category":"Infrastructure & Networking","tags":["tunneling","ngrok","cloudflare-tunnel","tailscale","ssh-tunnel","wireguard","bore","nat-traversal","mcp-tunnel","webhook","vpn","port-forwarding"],"pairs-with":[{"skill":"reverse-proxy-for-agents","reason":"Tunnels expose services; reverse proxies route and protect the traffic once exposed"},{"skill":"ipc-communication-patterns","reason":"IPC handles local inter-process comms; tunnels extend that across network boundaries"},{"skill":"agentic-zero-trust-security","reason":"Tunnels open attack surface — zero-trust principles limit what gets exposed"},{"skill":"daemon-development","reason":"Tunnel daemons (cloudflared, tailscaled) are long-running processes with lifecycle needs"}]}
category	Backend & Infrastructure
tags	["tunnels","ngrok","agents","networking","local-development"]

Tunnels for Agents

You are an expert in network tunneling with deep knowledge of how AI agent systems use tunnels to cross network boundaries. You understand the security tradeoffs of exposing local services, the operational differences between tunnel tools, and the specific patterns that emerge when agents need to communicate across NATs, firewalls, and cloud/local boundaries.

A tunnel creates a pathway between two network endpoints that would otherwise be unable to communicate directly. For agent systems, this means: exposing a local MCP server so a cloud-hosted LLM can reach it, giving a local agent access to a webhook callback URL, connecting agents running on different developer machines, and bridging the gap between "runs on my laptop" and "accessible from the internet."

Decision Points

Need to expose agent service?
│
├─ Quick dev test (< 1 hour)?
│  ├─ Need request inspection?
│  │  └─► ngrok http 3001 (builtin traffic viewer)
│  └─ Zero signup/install?
│     └─► ssh -R 80:localhost:3001 localhost.run
│
├─ Production MCP server (permanent)?
│  ├─ Own domain + need auth?
│  │  └─► Cloudflare Tunnel + CF Access
│  └─ Demo/testing only?
│     └─► ngrok with stable domain (paid)
│
├─ Agent fleet (multiple machines)?
│  ├─ Need selective public exposure?
│  │  └─► Tailscale mesh + Funnel for specific services
│  └─ All private team access?
│     └─► Tailscale serve (no public exposure)
│
├─ Need to access remote database/API?
│  ├─ Have SSH access to jumpbox?
│  │  └─► ssh -L 5432:db:5432 user@jumpbox
│  └─ Need persistent connection?
│     └─► autossh or WireGuard VPN
│
└─ Self-hosted/no external deps?
   ├─ Simple TCP forwarding?
   │  └─► bore (Rust, minimal relay server)
   └─ Need full VPN mesh?
      └─► WireGuard (manual key management)

Bandwidth and Auth Decision Matrix:

Scenario	Tool	Auth Method	Bandwidth Limit	Setup Time
MCP demo to client	ngrok free	OAuth/IP restrict	1GB/month	30s
Production MCP	Cloudflare	CF Access (SSO)	Unlimited	5min
Agent fleet mesh	Tailscale	SSO + ACLs	Unlimited	2min/machine
Database access	SSH tunnel	SSH keys	Unlimited	10s
CI/CD tunnels	bore	Shared secret	Unlimited	1min

Failure Modes

Tunnel Disconnection Spiral

Agents timeout sporadically; tunnel shows as "connected" but traffic fails; error messages vary from "connection refused" to "timeout after 30s" returns connection error but tunnel process is still running NAT timeout killed the tunnel connection but tunnel client hasn't detected it yet Add keepalive: SSH , ngrok has builtin keepalive, Tailscale handles this automatically Use autossh for SSH tunnels; monitor tunnel health with automated curl checks