sztwiorok/tunnel

Buddy Tunnels

Expose local services to the internet via secure Buddy tunnels. Ideal for webhook testing, client demos, mobile testing, and temporary service sharing.

CRITICAL: AI Agent Requirements

STOP: Read this section completely before creating any tunnel.

1. Run tunnels in background (MANDATORY)

Tunnel commands run in foreground and WILL BLOCK your execution. You MUST use run_in_background: true parameter in Bash tool:

Bash tool call:
  command: bdy tunnel http localhost:3000
  run_in_background: true

2. Ask about HTTP authentication (MANDATORY)

Before creating ANY HTTP tunnel, you MUST use AskUserQuestionTool to ask about authentication.

DO NOT skip this step. DO NOT proceed until user has made a choice.

Question: "Do you want to protect this HTTP tunnel with authentication?"

Options:

1. "HTTP Basic Auth (username:password)" → use -a username:password flag
2. "Buddy Authentication" → use --buddy flag
3. "No authentication (public access)" → proceed without auth

3. Docker: Verify app binds to 0.0.0.0

If running in Docker, the containerized app MUST bind to 0.0.0.0 so the host can reach it. For regular local development (not Docker), 127.0.0.1 works fine with tunnels.

Authentication Errors

If any bdy command returns Token not provided or Not logged in, ask the user to run bdy login in a separate terminal (interactive browser auth — AI cannot do it).

Quick Start

HTTP Tunnel (most common)

bdy tunnel http localhost:3000                    # basic
bdy tunnel http localhost:3000 -a user:pass       # with HTTP basic auth
bdy tunnel http localhost:3000 --buddy            # with Buddy auth
bdy tunnel http localhost:3000 -n my-tunnel       # named tunnel

TCP Tunnel (databases, SSH)

bdy tunnel tcp localhost:5432    # PostgreSQL
bdy tunnel tcp localhost:3306    # MySQL
bdy tunnel tcp localhost:22      # SSH

TLS Tunnel (custom certificates)

bdy tunnel tls localhost:8443 --key key.pem --cert cert.pem

Common Options

| Option | Description | |--------|-------------| | -n, --name | Named tunnel for identification | | -a, --auth user:pass | HTTP basic authentication | | --buddy | Buddy account authentication | | -r, --region eu\|us\|as | Regional endpoint | | -w, --whitelist | IP CIDR restrictions | | -t, --timeout | Connection timeout (seconds) |

Troubleshooting

Connection Refused

• Verify app is running on specified port
• If using Docker, check app binds to 0.0.0.0 inside the container

Authentication Failed

• If error contains Token not provided or Not logged in, user must run bdy login in a separate terminal

References

For detailed options, configurations, and examples see:

• references/commands.md - Complete command reference with all flags
• references/examples.md - Use cases: webhooks, demos, databases, etc.