跳到主要内容

Pinggy Tunnel

通过 Pinggy 使用 SSH 实现零安装的本地主机隧道。

技能元数据​

来源可选 — 使用 hermes skills install official/devops/pinggy-tunnel 安装
路径optional-skills/devops/pinggy-tunnel
版本0.1.0
作者Teknium (teknium1), Hermes Agent
许可证MIT
平台linux, macos, windows
标签Pinggy, Tunnel, Networking, SSH, Webhook, Localhost
相关技能cloudflared-quick-tunnel, webhook-subscriptions

参考：完整 SKILL.md​

信息

以下是 Hermes 在触发此技能时加载的完整技能定义。这是技能激活时代理看到的指令。

Pinggy Tunnel 技能

使用 Pinggy SSH 反向隧道将本地服务（开发服务器、Webhook 接收器、MCP 端点、演示）暴露给公共互联网。无需安装守护进程 — 用户的标准 SSH 客户端连接到 a.pinggy.io:443，Pinggy 会返回一个公共 HTTP/HTTPS URL。

免费层：60 分钟隧道，随机子域名，无需注册。专业层（$3/月）为可选功能，需使用令牌。

何时使用​

  • 用户要求“暴露此本地服务”、“分享我的开发服务器”、“使此 URL 公开”、“隧道端口 N”、“获取 Webhook 的公共 URL”
  • 需要在本地任务期间接收 Webhook 回调（Stripe、GitHub、Discord、AgentMail）
  • 与远程方共享一次性 HTTP 演示（MCP 服务器、Ollama/vLLM 端点、仪表板）
  • 主机拥有 SSH 但没有 cloudflared / ngrok 二进制文件，且安装它们过于繁琐

如果主机已配置 cloudflared，优先使用 cloudflared-quick-tunnel 技能 — Cloudflare 快速隧道不会在 60 分钟后过期。

前提条件​

  • PATH 中存在 ssh (ssh -V)。Linux、macOS 和 Windows 10+ 默认包含。无需其他安装。
  • 在隧道启动前，本地服务正在监听 127.0.0.1:<port>。Pinggy 将返回 URL，但在本地源站上线之前，这些 URL 将返回 502 错误。

可选：

  • 用于付费专业功能的 PINGGY_TOKEN 环境变量（持久子域名、自定义域名、多个隧道、无 60 分钟限制）。免费层无需凭据。

快速参考​

# Plain HTTP/HTTPS tunnel for port 8000 (free tier)
ssh -p 443 -o StrictHostKeyChecking=no -o ServerAliveInterval=30 \
    -R0:localhost:8000 free@a.pinggy.io

# TCP tunnel (databases, raw SSH, etc.)
ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:5432 tcp@a.pinggy.io

# TLS tunnel (Pinggy can't decrypt — bring your own certs at origin)
ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:443 tls@a.pinggy.io

# Basic auth gate (b:user:pass)
ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
    "b:admin:secret+free@a.pinggy.io"

# Bearer token gate (k:token)
ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
    "k:mysecrettoken+free@a.pinggy.io"

# IP whitelist (w:CIDR)
ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
    "w:203.0.113.0/24+free@a.pinggy.io"

# Enable CORS + force HTTPS redirect
ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
    "co+x:https+free@a.pinggy.io"

# Pro tier (persistent URL, no 60-min cap)
ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 "$PINGGY_TOKEN+a.pinggy.io"

流程 — 启动隧道并获取 URL​

模型应使用 terminal 工具。隧道必须在共享期间保持活跃，因此将其作为后台进程运行，并从 stdout 解析公共 URL。

1. 确认本地源站已上线​

curl -sI http://127.0.0.1:8000/ | head -1
# expect HTTP/1.x 200 (or any non-connection-refused response)

如果尚未有任何服务在监听，请先启动它（例如 python3 -m http.server 8000 --bind 127.0.0.1）。Pinggy 会乐意返回一个指向空内容的 URL — 在源站上线之前，用户将看到 502 错误。

2. 以后台进程方式启动隧道​

使用 terminal(background=True) 并将输出捕获到日志文件（Pinggy 在 stdout 上打印 URL，然后保持连接打开）：

LOG=/tmp/pinggy-8000.log
nohup ssh -p 443 \
    -o StrictHostKeyChecking=no \
    -o UserKnownHostsFile=/dev/null \
    -o ServerAliveInterval=30 \
    -o ServerAliveCountMax=3 \
    -R0:localhost:8000 free@a.pinggy.io \
    > "$LOG" 2>&1 &
echo $! > /tmp/pinggy-8000.pid

StrictHostKeyChecking=no + UserKnownHostsFile=/dev/null 跳过首次运行的主机密钥提示。ServerAliveInterval=30 防止 SSH 会话因 NAT 空闲而被断开。

3. 从日志中解析 URL​

sleep 4
grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/pinggy-8000.log | head -1

预期输出如下所示：

You are not authenticated.
Your tunnel will expire in 60 minutes.
http://yqycl-98-162-69-48.a.free.pinggy.link
https://yqycl-98-162-69-48.a.free.pinggy.link

将 https://...pinggy.link URL 交给用户。

4. 验证​

curl -sI https://<the-url>/ | head -3
# expect 200/302/whatever the local origin actually returns

如果收到 502 Bad Gateway，说明 SSH 会话已建立，但本地源站未在监听 — 请先修复步骤 1。

5. 清理​

kill "$(cat /tmp/pinggy-8000.pid)"
# or, if the pid file got lost:
pkill -f 'ssh -p 443 .* free@a\.pinggy\.io'

如果你从 terminal(background=True) 获得了 session_id，优先使用 process(action='kill', session_id=...)。

通过用户名关键字进行访问控制​

Pinggy 将通过 + 分隔的控制标志堆叠到 SSH 用户名中。当包含 + 时，始终引用整个 user@host 参数：

关键字效果
b:user:passHTTP 基本认证网关
k:tokenBearer 令牌头网关 (Authorization: Bearer <token>)
w:CIDRIP 白名单（单个 IP 或 CIDR，可重复）
co添加 Access-Control-Allow-Origin: * (CORS)
x:https强制 HTTPS — 自动将 HTTP 重定向到 HTTPS
a:Name:Value添加请求头
u:Name:Value更新请求头
r:Name移除请求头
qr将 URL 的二维码打印到 stdout（便于移动设备共享）

自由组合："b:admin:secret+co+x:https+free@a.pinggy.io"。

Web 调试器（可选）​

Pinggy 可以将入站流量镜像到 localhost:4300 以供检查。向 SSH 命令添加本地转发：

ssh -p 443 -L4300:localhost:4300 -R0:localhost:8000 free@a.pinggy.io

然后在浏览器中打开 http://localhost:4300 以查看实时的请求/响应对。

常见陷阱​

  • 免费层有 60 分钟的硬性上限。 SSH 会话将在 60 分钟时终止；URL 将失效。对于更长时间的共享，请使用 PINGGY_TOKEN（专业版）或通过 shell 循环自动重启（请注意，免费层每次重启时 URL 都会更改）。
  • 免费层的 URL 是随机的，且在重启时会更改。 不要将其加入书签，也不要将其粘贴到配置文件中。每次都要从日志中重新解析。
  • 每个源 IP 的并发免费隧道限制为一个。 从同一台机器启动第二个隧道通常会杀死第一个隧道。专业版解除了此限制。
  • 用户名中的 + 必须加引号。 裸写的 ssh ... b:admin:secret+free@a.pinggy.io 在 bash 中有效，但在将 + 视为特殊字符的 shell 中或以编程方式组装时会出错。始终用双引号包裹。
  • 不要在没有访问控制标志的情况下隧道传输任何敏感内容。 裸 HTTP 隧道可被任何拥有 URL 的人访问。对于非公共服务，请使用 b:、k: 或 w:。
  • process(action='log') 可能会遗漏 SSH banner 输出。 Pinggy 打印 URL，然后 SSH 会话进入交互模式。始终重定向到日志文件并直接 grep 该文件——与 cloudflared-quick-tunnel 相同的模式。
  • 首次运行时的主机密钥提示。 默认 OpenSSH 配置要求用户接受 Pinggy 的主机密钥。对于无人值守的运行，始终传递 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null。
  • TCP 和 TLS 隧道返回 <subdomain>.a.pinggy.online:<port> 对，而不是 https URL。 使用不同的正则表达式解析（tcp:// 和端口）。不要假设每个 Pinggy 隧道都是 HTTP。
  • 专业模式需要将令牌作为用户名，而不是作为标志。 使用 "$PINGGY_TOKEN+a.pinggy.io"（无 free@）。使用令牌时，还可以添加 :persistent 以获得稳定的子域名——参见 pinggy.io/docs/。

配方​

将本地源与 Pinggy 隧道相结合的复合模式。每个配方都是自包含的——启动源，启动隧道，解析 URL，将其交还给用户。

配方 1 — 接收 webhook 回调​

当外部服务（Stripe、GitHub、Discord、AgentMail 等）需要在本地任务期间 POST 到公开可达的 URL 时使用此方法。

# 1. Tiny capturing server: every request gets appended to /tmp/webhook-hits.log
cat >/tmp/webhook-server.py <<'PY'
import http.server, json, datetime, pathlib
LOG = pathlib.Path("/tmp/webhook-hits.log")
class H(http.server.BaseHTTPRequestHandler):
    def _capture(self):
        n = int(self.headers.get("content-length") or 0)
        body = self.rfile.read(n).decode("utf-8", "replace") if n else ""
        rec = {"t": datetime.datetime.utcnow().isoformat(), "path": self.path,
               "method": self.command, "headers": dict(self.headers), "body": body}
        with LOG.open("a") as f: f.write(json.dumps(rec) + "\n")
        self.send_response(200); self.send_header("content-type","application/json")
        self.end_headers(); self.wfile.write(b'{"ok":true}\n')
    def do_GET(self): self._capture()
    def do_POST(self): self._capture()
    def log_message(self,*a,**k): pass
http.server.HTTPServer(("127.0.0.1", 18080), H).serve_forever()
PY
nohup python3 /tmp/webhook-server.py >/tmp/webhook-server.log 2>&1 &
echo $! >/tmp/webhook-server.pid

# 2. Tunnel — bearer-token-gate so randos can't pollute the capture log
nohup ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
    -o ServerAliveInterval=30 \
    -R0:localhost:18080 "k:$(openssl rand -hex 12)+free@a.pinggy.io" \
    >/tmp/webhook-pinggy.log 2>&1 &
echo $! >/tmp/webhook-pinggy.pid
sleep 5
URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/webhook-pinggy.log | head -1)
echo "Webhook URL: $URL"

# 3. While the agent works, watch hits land
tail -f /tmp/webhook-hits.log

将 $URL 交给需要调用您的服务。 teardown：kill $(cat /tmp/webhook-server.pid) $(cat /tmp/webhook-pinggy.pid)。

配方 2 — 通过 HTTP/SSE 暴露 MCP 服务器​

当远程 MCP 客户端（另一台机器上的 Claude Desktop、队友的编辑器等）需要访问在本地机器上运行的 MCP 服务器时使用。仅适用于使用 HTTP 传输的 MCP 服务器——stdio 模式服务器无法通过隧道传输。

# 1. Start the MCP server in HTTP mode (example: a FastMCP server on port 8765)
nohup python3 my_mcp_server.py --transport http --port 8765 \
    >/tmp/mcp-server.log 2>&1 &
echo $! >/tmp/mcp-server.pid

# 2. Tunnel with a bearer token — MCP traffic should not be open to the internet
TOKEN=$(openssl rand -hex 16)
nohup ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
    -o ServerAliveInterval=30 \
    -R0:localhost:8765 "k:$TOKEN+free@a.pinggy.io" \
    >/tmp/mcp-pinggy.log 2>&1 &
echo $! >/tmp/mcp-pinggy.pid
sleep 5
URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/mcp-pinggy.log | head -1)
echo "MCP URL: $URL"
echo "Bearer token: $TOKEN"

远程客户端使用 Authorization: Bearer $TOKEN 连接到 $URL。Hermes 自己的原生 MCP 客户端配置：{"transport": "http", "url": "<URL>", "headers": {"Authorization": "Bearer <TOKEN>"}}。

配方 3 — 暴露本地 LLM 端点（Ollama / vLLM / llama.cpp）​

与远程调用者（另一个代理、手机、队友）共享本地模型。Ollama 监听 :11434，vLLM 和 llama.cpp 通常监听 :8000。

# Pre-req: the model server is already running on 127.0.0.1:11434 (Ollama default)
TOKEN=$(openssl rand -hex 16)
nohup ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
    -o ServerAliveInterval=30 \
    -R0:localhost:11434 "k:$TOKEN+co+free@a.pinggy.io" \
    >/tmp/llm-pinggy.log 2>&1 &
echo $! >/tmp/llm-pinggy.pid
sleep 5
URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/llm-pinggy.log | head -1)
echo "Endpoint: $URL"
echo "Token:    $TOKEN"

# Verify
curl -s "$URL/api/tags" -H "Authorization: Bearer $TOKEN" | head

co 启用 CORS，以便浏览器调用者可以访问端点。对于仅后端调用者，请去掉 co。对于兼容 OpenAI 的 vLLM/llama.cpp 端点，调用者使用基础 URL $URL/v1 和 Authorization: Bearer $TOKEN——但请注意 Pinggy 不会剥离/替换正文中的任何内容，因此模型服务器本身会看到 Pinggy 的令牌；本地服务器应配置为忽略身份验证（它已经在 127.0.0.1 上），让 Pinggy 进行 gating。

配方 4 — 使用一次性密码共享开发服务器​

最快的“让队友试探我正在运行的应用”模式。随机密码，打印一次，当您按 Ctrl-C 时失效。

PASS=$(openssl rand -base64 12 | tr -d '+/=' | head -c 12)
echo "Dev server password: $PASS"
ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
    -o ServerAliveInterval=30 \
    -R0:localhost:3000 "b:dev:$PASS+co+x:https+free@a.pinggy.io"
# URL prints to the terminal. Share URL + password. Ctrl-C to tear down.

b:dev:$PASS 使用 HTTP Basic auth 保护 URL。x:https 强制使用 TLS。co 为 SPA 前端添加 CORS。

验证​

# End-to-end: spin up a trivial origin, tunnel it, hit it, tear down
python3 -m http.server 18000 --bind 127.0.0.1 >/tmp/origin.log 2>&1 &
ORIGIN_PID=$!

nohup ssh -p 443 \
    -o StrictHostKeyChecking=no \
    -o UserKnownHostsFile=/dev/null \
    -R0:localhost:18000 free@a.pinggy.io >/tmp/pinggy-verify.log 2>&1 &
SSH_PID=$!

sleep 5
URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/pinggy-verify.log | head -1)
echo "URL: $URL"
curl -sI "$URL/" | head -1

kill "$SSH_PID" "$ORIGIN_PID"

预期：curl head 上出现 pinggy.link URL 和 HTTP/2 200。