# hoody-tunnel Subskill ## Overview ### What This Service Does Hoody-tunnel provides reverse tunneling capabilities for exposing HTTP, WebSocket, and TCP services running inside containers to the internet through Hoody's infrastructure. It creates secure, authenticated tunnels that allow external clients to access containerized services without direct network exposure. ### When to Use It - Exposing development servers (e.g., React, Vue, Next.js) for testing with external services - Providing webhooks to third-party APIs during development - Sharing local API endpoints with team members or clients - Testing mobile applications against local backend services - Accessing containerized services from external monitoring systems ### How It Fits Into Hoody Philosophy Hoody-tunnel embodies the core Hoody principles: - **Zero Configuration**: Automatic SSL termination and domain routing via Hoody Proxy - **Secure by Default**: Built-in authentication through Hoody API tokens - **Service Isolation**: Each tunnel is tied to a specific container instance - **Developer Experience**: Simple CLI commands replace complex networking setup The tunnel service integrates with the Hoody Proxy routing system, automatically creating routes at: `https://{projectId}-{containerId}-{serviceId}.hoody.com` ## Common Workflows ### 1. Basic Tunnel Operations #### Checking Tunnel Health Verify the tunnel service is operational before starting work: ``` # Check tunnel kit health hoody tunnel health -c ``` ``` { "status": "ready", "service": "hoody-tunnel", "built": "2025-01-15T10:30:00Z", "started": "2025-11-05T08:15:00Z", "memory": 256, "fds": 100, "pid": 1234, "ip": "10.0.0.15", "userAgent": "hoody-tunnel/1.0" } ``` #### Listing Active Tunnels View all active tunnels to understand current state: ``` # List all active tunnels (combined sessions + bindings) hoody tunnel list -c ``` ``` { "tunnels": [ { "sessionId": "sess-abc123", "bindings": [ { "bindId": "bind-def456", "kind": "EXPOSE", "mode": "http", "port": 3000, "subdomain": "my-app" } ], "streamCount": 5, "orphanCount": 0, "fdBudget": { "total": 1000, "used": 50 } } ] } ``` #### Listing Active Sessions View only active tunnel sessions: ``` # List active tunnel sessions hoody tunnel list --type sessions -c ``` ``` [ { "sessionId": "sess-abc123", "bindings": [ { "bindId": "bind-def456", "kind": "EXPOSE", "mode": "http", "port": 3000 } ], "streamCount": 5, "protocolVersion": "v2" } ] ``` ### 2. Tunnel Management #### Listing Active Bindings View all port bindings across sessions: ``` # List active bindings across all sessions hoody tunnel list --type bindings -c ``` ``` [ { "sessionId": "sess-abc123", "bindId": "bind-def456", "kind": "EXPOSE", "mode": "http", "port": 3000, "subdomain": "my-app" }, { "sessionId": "sess-abc123", "bindId": "bind-ghi789", "kind": "PULL", "mode": "tcp", "port": 5432 } ] ``` #### Terminating a Tunnel Session Clean up tunnels when no longer needed: ``` # Terminate a specific tunnel session hoody tunnel kill sess-abc123 -c ``` ``` { "status": "terminating", "sessionId": "sess-abc123", "gracePeriod": 30000 } ``` #### Monitoring Tunnel Metrics Check tunnel performance and resource usage: ``` # Get Prometheus metrics hoody tunnel metrics -c ``` ``` # HELP hoody_tunnel_active_sessions Current active tunnel sessions # TYPE hoody_tunnel_active_sessions gauge hoody_tunnel_active_sessions 3 # HELP hoody_tunnel_active_bindings Current active bindings # TYPE hoody_tunnel_active_bindings gauge hoody_tunnel_active_bindings 5 # HELP hoody_tunnel_fd_permits Available file descriptor permits # TYPE hoody_tunnel_fd_permits gauge hoody_tunnel_fd_permits 950 ``` ### 3. Container-Targeted Operations Every tunnel command targets a specific container. Use the container ID from your container creation: ``` # Example workflow with container targeting hoody tunnel health -c my-container-123 hoody tunnel list -c my-container-123 hoody tunnel metrics -c my-container-123 ``` ## Advanced Operations ### Complex Multi-Step Workflows #### Setting Up and Verifying a Development Tunnel ``` # 1. Verify container is running hoody container list # 2. Check tunnel service health hoody tunnel health -c # 3. View existing tunnels hoody tunnel list -c # 4. Monitor metrics during development hoody tunnel metrics -c # 5. Clean up when done hoody tunnel kill -c ``` #### Batch Operations with JSON Output ``` # Get all sessions in JSON for scripting hoody tunnel list -o json -c | jq '.[] | select(.streamCount > 0)' # Count active bindings hoody tunnel list --type bindings -o json -c | jq 'length' ``` ### Error Recovery Patterns #### Session Cleanup After Disconnection If a tunnel session becomes unresponsive: ``` # Check session status hoody tunnel list -c # Force terminate if stuck hoody tunnel kill --force -c # Verify cleanup hoody tunnel list -c ``` #### Handling Resource Exhaustion Monitor file descriptor usage to prevent connection issues: ``` # Check current metrics hoody tunnel metrics -c # If fd_permits is low, terminate unused sessions hoody tunnel kill -c ``` ### Performance Considerations #### Resource Monitoring Regular monitoring prevents service degradation: ``` # Create a monitoring script #!/bin/bash while true; do hoody tunnel metrics -c sleep 60 done ``` #### Session Management Best Practices 1. **Clean up unused tunnels** - Sessions consume file descriptors 2. **Monitor stream counts** - High stream counts may indicate connection leaks 3. **Check orphan counts** - Orphans indicate failed cleanup operations 4. **Use session IDs** - Track specific tunnels for debugging #### Scaling Considerations For high-traffic scenarios: - Monitor `fdBudget` in tunnel listings - Consider multiple containers for load distribution - Use session grouping for related services ## Quick Reference ### Essential Commands | Command | Description | |---------|-------------| | `hoody tunnel health -c ` | Check tunnel service health | | `hoody tunnel list -c ` | List all active tunnels | | `hoody tunnel list --type sessions -c ` | List active sessions only | | `hoody tunnel list --type bindings -c ` | List active bindings only | | `hoody tunnel kill -c ` | Terminate a session | | `hoody tunnel metrics -c ` | Get Prometheus metrics | ### Common Parameters - `-c ` or `HOODY_CONTAINER` env var: Target container - `-o json|yaml|table`: Output format - `--yes` for `kill` command: Skip confirmation ### Typical Response Formats **Health Check Response:** ``` { "status": "ready", "service": "hoody-tunnel", "built": "2025-01-15T10:30:00Z", "started": "2025-11-05T08:15:00Z", "memory": 256, "fds": 100, "pid": 1234, "ip": "10.0.0.15", "userAgent": "hoody-tunnel/1.0" } ``` **Session Termination Response:** ``` { "status": "terminating", "sessionId": "sess-abc123", "gracePeriod": 30000 } ``` ### Error Indicators - `status: "error"` in health checks - Increasing `orphanCount` in tunnel listings - Low `fdBudget.used` values approaching limits - Session IDs that fail to terminate