TSDProxy Documentation

TSDProxy is an open-source application that automatically creates reverse proxies to virtual addresses in your Tailscale network. It simplifies traffic redirection to services running inside Docker containers using either Docker container labels or YAML proxy lists.

Key benefits include:

• No extra containers: You do not need a separate Tailscale container for every service you want to expose.
• Label-driven configuration: You can configure proxies simply by adding Docker labels to your existing containers.
• Automatic HTTPS: It leverages Tailscale's built-in Let's Encrypt certificate support via MagicDNS.
• Multiple discovery methods: Supports both automatic Docker container discovery and manual YAML proxy list files.
• Monitoring: Includes a real-time web dashboard with SSE (Server-Sent Events) streaming to monitor all active proxies.

TSDProxy is a lightweight, open-source proxy designed to facilitate virtual services within a Tailscale network. It allows you to proxy traffic to virtual Tailscale addresses using Docker container labels, eliminating the need to run a dedicated Tailscale container for every individual service.

Key capabilities include:

• Automatic TLS Support: Automatically handles Tailscale/Let's Encrypt certificates via MagicDNS.
• Simplified Configuration: Uses Docker container labels to route traffic, avoiding the need to manually configure virtual hosts in your Tailscale network.
• Efficiency: Lightweight design that reduces resource overhead compared to per-service Tailscale instances.

TSDProxy provides several advanced features for Tailscale-based proxying:

• Multi-port per proxy: Each Tailscale machine can expose multiple ports with independent protocols.
• TCP proxying: Supports raw TCP forwarding for SSH, databases, gRPC, and other non-HTTP protocols.
• Tailscale Funnel support: Expose services to the public internet by adding the tailscale_funnel option to a port.
• Dashboard: A real-time web UI for monitoring proxies, status, and authentication.
• List provider: Allows proxying non-Docker services via a YAML configuration.
• Dynamic lifecycle: Automatically reacts to container starts, stops, and removals in real time.
• Live config reload: Configuration changes take effect without restarting the TSDProxy container.

TSDProxy v3 provides the following capabilities:

• Easy to Use: Creates virtual Tailscale addresses using Docker container labels.
• Really Easy to Use: Creates virtual Tailscale addresses using a proxy list.
• Lightweight: Avoids the overhead of spinning up a dedicated Tailscale container for every service.
• Quick deploy: Removes the need to manually configure virtual hosts in your Tailscale network.
• Automatically supports TLS: Automatically handles Tailscale/Let's Encrypt certificates when using MagicDNS.

TSDProxy can be deployed using two primary methods depending on your infrastructure requirements:

1. Standalone Binary: Run TSDProxy directly on the host machine without using Docker. This is suitable for simple setups or environments where container orchestration is not desired.
2. Docker Swarm: Deploy TSDProxy across a Swarm cluster. This method utilizes service labels to manage deployment and configuration across multiple nodes.

TSDProxy sends messages to Slack using Slack's Block Kit format.

Fallback text: TSDProxy: Proxy 'myapp' status changed to Running

Block content structure:

*TSDProxy Status Update*
Proxy: `myapp`
Status: `Running`
Previous: `Starting`

Note on @mentions: If a proxy name contains an @ character, TSDProxy automatically inserts a zero-width space to prevent the proxy name from triggering accidental user mentions in Slack.

TSDProxy can proxy raw TCP and UDP connections through your Tailscale network. This allows you to expose services like SSH, databases (PostgreSQL, MySQL, Redis), gRPC, or game servers without HTTP overhead.

Key Characteristics:

• No HTTP Parsing/TLS Termination: For TCP/UDP, TSDProxy forwards raw bytes bidirectionally. The target service is responsible for its own encryption (e.g., SSH handles its own key exchange).
• Tailnet Only: TCP ports are only accessible within your Tailscale network; Tailscale Funnel does not support raw TCP listeners.
• Docker Networking: When proxying to containers, TSDProxy connects directly to the container IP. For this to work, the TSDProxy container and the target container must share the same Docker network.

TSDProxy uses two modes for timing re-resolution attempts after a failure:

1. Exponential Backoff (Default)

When healthCheckCooldown is set to 0, TSDProxy uses exponential backoff. With default settings (30s interval, 3 failures), the timeline looks like this:

• 1st attempt: ~90s after initial failure (3 × 30s consecutive failures)
• 2nd attempt: 30s delay
• 3rd attempt: 60s delay
• 4th attempt: 2min delay
• 5th attempt: 4min delay
• 6th+ attempt: 8min, 16min, etc., capped at 24h.

2. Fixed Cooldown

If you set a specific value for healthCheckCooldown (e.g., 120), TSDProxy will attempt re-resolution every 120 seconds as long as the target remains unhealthy, bypassing the exponential backoff logic.