TSDProxy - Tailscale Docker Proxy

The easiest way to expose Docker containers on your Tailscale network. One label. Zero sidecars.

Quick Start

Get running in under a minute. One compose file, one label.

Step 1: Create docker-compose.yml

services:
  tsdproxy:
    image: almeidapaulopt/tsdproxy:2
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - tsdproxy-data:/data
      - ./config:/config
    ports:
      - "8080:8080"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: unless-stopped

  myapp:
    image: nginx:alpine
    labels:
      tsdproxy.enable: "true"
      tsdproxy.name: "myapp"

volumes:
  tsdproxy-data:

Step 2: Start it up

docker compose up -d

TSDProxy creates a default config at /config/tsdproxy.yaml on first run. Open the dashboard at http://localhost:8080, click the proxy card, and authenticate with Tailscale.

Your container is now available at https://myapp.<tailnet-name>.ts.net with automatic HTTPS.

For automated (headless) setup, configure an AuthKey or OAuth before adding services.

Key Features

How It Works

graph LR
    A[Docker Containers] -->|tsdproxy.enable label| B[TSDProxy]
    B -->|creates tsnet.Server| C[Tailscale Network]
    C -->|automatic HTTPS| D[Secure URLs]
    D -->|reverse proxy| A

Under the hood:

1. Container Scanning - TSDProxy watches your Docker daemon for containers tagged with tsdproxy.enable=true.
2. Machine Creation - When a tagged container appears, TSDProxy spins up a Tailscale machine via tsnet.
3. Hostname Assignment - The machine gets a hostname from the tsdproxy.name label or the container name.
4. Port Mapping - TSDProxy maps the container's internal port to the Tailscale machine.
5. Traffic Routing - Incoming requests to https://myapp.<tailnet>.ts.net are reverse-proxied to the container.
6. Dynamic Cleanup - When a container stops, its Tailscale machine and routes are removed automatically.

Port Configuration

Expose multiple ports with per-port protocol and options:

labels:
  tsdproxy.enable: "true"
  tsdproxy.name: "myservice"

  # HTTPS on 443 -> container port 80
  tsdproxy.port.1: "443/https:80/http"

  # HTTP on 80 -> container port 8080
  tsdproxy.port.2: "80/http:8080/http"

  # HTTP redirect to HTTPS
  tsdproxy.port.3: "81/http->https://myservice.tailnet.ts.net"

  # TCP proxy for SSH
  tsdproxy.port.4: "22/tcp:22/tcp"

  # UDP proxy (e.g. game server, VoIP)
  tsdproxy.port.5: "5060/udp:5060/udp"

  # Port range (TCP ports 2222 through 2230)
  tsdproxy.port.6: "2222-2230/tcp:2222-2230/tcp"

Docker Images

Documentation

Full setup guides, configuration reference, and advanced usage:

almeidapaulopt.github.io/tsdproxy

Key docs: Getting Started | Docker Labels | Port Configuration | List Provider | TCP Proxy | Funnel | REST API | Health Checks | Webhooks | Admin Allowlist | Upgrading from v1

Contributing

Bug reports, feature requests, documentation improvements, and pull requests are all welcome. See CONTRIBUTING.md for guidelines.

If you'd rather support the project financially, sponsorships help keep development going.

License

This project is licensed under the MIT License. See the LICENSE file for details.