Overview

This proposes a Pinggy skill that teaches Hermes Agent how to expose local services to the internet using Pinggy SSH tunnels. Pinggy is unique among tunneling tools because it requires zero installation -- it uses the system's built-in SSH client (ssh -p 443 -R0:localhost:PORT free@a.pinggy.io), making it the perfect fit for an agent that needs to quickly share a local server, receive webhooks, or expose services without installing anything.

Tested and confirmed working: a single SSH command produces both HTTP and HTTPS public URLs instantly, with free Let's Encrypt certificates. No signup needed for the free tier (60-minute tunnels).

This fills a clear gap -- there are currently no tunneling/localhost-exposure skills or tools in Hermes Agent, yet agents frequently need to expose local services (dev servers, webhook receivers, MCP servers, AI model endpoints, demos).

Research Findings

How Pinggy Works

Pinggy uses SSH reverse port forwarding. The user's SSH client connects to Pinggy's edge server on port 443 (firewall-friendly), and Pinggy allocates a public subdomain that routes traffic back through the SSH tunnel to the local port.

Core command:

ssh -p 443 -R0:localhost:8000 -o StrictHostKeyChecking=no free@a.pinggy.io

Output (confirmed via testing):

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

Tunnel Types

Access Control (via SSH username keywords)

All access controls are appended to the username field, separated by +:

# Basic auth: b:user:password
ssh -p 443 -R0:localhost:8000 "b:admin:secret+free@a.pinggy.io"

# Bearer token: k:token
ssh -p 443 -R0:localhost:8000 "k:mytoken123+free@a.pinggy.io"

# IP whitelist: w:IP/CIDR
ssh -p 443 -R0:localhost:8000 "w:203.0.113.0/24+free@a.pinggy.io"

# QR code display: qr (shows QR code in terminal for mobile access)
ssh -p 443 -R0:localhost:8000 "qr+free@a.pinggy.io"

Header Manipulation

HTTP headers can be modified via username keywords:

# Add header: a:Name:Value
# Remove header: r:Name  
# Update header: u:Name:Value
# Enable CORS: co (adds Access-Control-Allow-Origin: *)
# Force HTTPS redirect: x:https

ssh -p 443 -R0:localhost:8000 "a:X-Custom:value+co+x:https+free@a.pinggy.io"

Web Debugger

Pinggy provides a local web debugger at localhost:4300 that shows live request/response inspection. Enable with -L4300:localhost:4300 in the SSH command.

Pricing & Limitations

Comparison to Alternatives

• vs ngrok ($10/mo): Pinggy is cheaper, requires no install, has unlimited bandwidth. ngrok has a larger ecosystem and OAuth/SAML support.
• vs Cloudflare Tunnel (free): Cloudflare requires cloudflared binary install. No UDP support. More complex setup but free for unlimited use.
• vs localtunnel (free): HTTP-only, no auth features, less reliable. Both are zero-install but Pinggy is more feature-rich.

Pinggy's killer advantage for Hermes: zero installation. SSH is already available on every system the agent runs on.

SDKs Available

• Python SDK: pip install pinggy -- programmatic tunnel creation with URL retrieval, auto-reconnect, auth. Apache 2.0. (Note: during testing the SDK had import timeout issues; the SSH approach is more reliable.)
• Node.js SDK: npm install @pinggy/pinggy
• Go SDK: github.com/Pinggy-io/pinggy-go

Current State in Hermes Agent

• Zero existing tunnel/exposure skills or tools -- no ngrok, cloudflare, localtunnel, or pinggy integration
• No existing issues related to tunneling, localhost exposure, or port forwarding
• Related issues that would benefit from tunneling:
  • Feature: Hermes Agent as MCP Server — Expose Tools to the MCP Ecosystem #342 (Hermes Agent as MCP Server) -- could use Pinggy to expose MCP server to remote clients
  • Feature: AgentMail Integration — Agent-Owned Email Inboxes #329 (AgentMail) -- webhook receiving could use tunnels
  • Feature: Dogfood Skill — Agent-Driven Exploratory QA for Web Applications #315 (Dogfood Skill) -- sharing QA test servers with users

Relevant existing capabilities:

• Terminal tool can run SSH commands and manage background processes
• Process management (background=true, poll, kill) can manage tunnel lifecycle
• The agent already knows how to parse command output

Implementation Plan

Skill vs. Tool Classification

This should be a skill because:

• The capability is entirely expressible as SSH commands via the existing terminal tool
• It wraps an external service (Pinggy) that the agent calls via shell commands
• No custom Python integration, API key management, or binary data handling needed
• The agent just needs to know the right command format and how to parse the URL output

Should it be bundled? Yes -- localhost tunneling is broadly useful across development workflows (sharing servers, webhook testing, exposing services, demos). It's not niche or specialized.

What the Skill Would Cover

1. Creating HTTP/HTTPS tunnels -- expose local web servers
2. Creating TCP tunnels -- expose databases, SSH, raw services
3. Creating TLS tunnels -- end-to-end encrypted exposure
4. Access control -- basic auth, bearer tokens, IP whitelisting
5. Header manipulation -- CORS, custom headers, HTTPS redirect
6. Lifecycle management -- running tunnels in background, checking status, teardown
7. URL retrieval -- parsing tunnel URLs from SSH output
8. Web debugger -- enabling request inspection at localhost:4300
9. Pro features -- persistent subdomains, custom domains (when token available)

Phased Rollout

Phase 1: Core Skill

• SKILL.md with instructions for HTTP/HTTPS tunnels via SSH
• Background process management pattern (start tunnel, parse URL, keep alive)
• Basic auth and access control instructions
• Tested command templates for common scenarios
• Troubleshooting: host key prompts, password bypass, connection drops

Phase 2: Advanced Features

• TCP/TLS tunnel instructions
• Header manipulation recipes
• Web debugger setup
• QR code display for mobile sharing
• Pro tier integration (token-based auth, persistent subdomains)
• Auto-reconnection pattern using shell loops

Phase 3: Integration Recipes

• "Expose MCP server" recipe (ties to Feature: Hermes Agent as MCP Server — Expose Tools to the MCP Ecosystem #342)
• "Webhook receiver" recipe (start HTTP server + tunnel + receive callbacks)
• "Share dev server" recipe (tunnel + basic auth + share URL)
• "Expose AI model endpoint" recipe (Ollama/vLLM + tunnel)

Pros & Cons

Pros

• Zero install -- SSH is already available on every system the agent runs on. No pip install, no binary download, no PATH configuration
• Instant setup -- One command, tunnel is live in <2 seconds
• Free tier sufficient -- 60-minute tunnels with no signup cover most agent tasks (demos, webhook testing, quick shares)
• Security options -- Basic auth, bearer tokens, and IP whitelisting provide real access control
• Firewall friendly -- Uses port 443, looks like HTTPS traffic, works through corporate firewalls
• HTTPS included -- Free Let's Encrypt certificates on all HTTP tunnels
• Low maintenance -- The skill just documents SSH command patterns; no code to maintain
• Broad utility -- Fills a gap that many development workflows need

Cons / Risks

• 60-minute free tier limit -- Tunnels expire; for persistent exposure, users need Pro ($3/mo)
• Vendor dependency -- Relies on Pinggy's infrastructure being available
• No official SLA -- Pinggy is a smaller service compared to ngrok/Cloudflare
• SSH process management -- Background SSH processes need proper lifecycle management (the agent already handles this via the process tool, but it's a consideration)
• URL changes on restart -- Free tier generates new URLs each time; users can't bookmark them without Pro

Open Questions

• Should the skill also cover alternatives (ngrok, cloudflare) as fallbacks, or focus purely on Pinggy?
• Should we recommend the Python SDK as an alternative approach, or keep it SSH-only for simplicity?
• Is there value in a tunnel tool (not just a skill) that manages tunnel lifecycle more tightly?
• Should the skill include a pattern for auto-reconnecting dropped tunnels?

References

• Pinggy homepage
• Pinggy documentation
• Pinggy usage docs
• Pinggy Python SDK -- Apache 2.0
• Pinggy vs ngrok comparison
• Hands-on test confirmed: SSH tunnel creates HTTP+HTTPS URLs instantly with zero install
• Related: Feature: Hermes Agent as MCP Server — Expose Tools to the MCP Ecosystem #342 (Hermes as MCP Server), Feature: AgentMail Integration — Agent-Owned Email Inboxes #329 (AgentMail webhooks), Feature: Dogfood Skill — Agent-Driven Exploratory QA for Web Applications #315 (Dogfood Skill)