Getting Started

Create Tailscale OAuth credentials

1. Go to the Tailscale OAuth clients settings.
2. Click + Credential.
3. Select OAuth and give it a description (e.g. “TSDProxy”).
4. Under Scopes, enable the required permissions:
   • General/Services: write (to create and manage Tailscale services/VIP)
   • Devices/Core: write (to create and manage Tailscale machines)
   • Keys/Auth Keys: write (to generate single use keys for services)
5. Assign tags to the OAuth client (e.g. tag:example) — Tailscale requires all OAuth-generated keys to have tags.
6. Click Generate client and copy the Client ID and Client Secret — you’ll need them in the config file.

Create a TSDProxy docker-compose.yaml

services:
  tsdproxy:
    image: almeidapaulopt/tsdproxy:2
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - datadir:/data
      - ./config:/config
    restart: unless-stopped
    ports:
      - "8080:8080"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    labels:
      tsdproxy.enable: "true"
      tsdproxy.name: "dash"
      tsdproxy.dash.visible: "false"

volumes:
  datadir:

Configure TSDProxy

Create the configuration file ./config/tsdproxy.yaml with the following:

defaultProxyProvider: default

docker:
  local:
    host: unix:///var/run/docker.sock
    targetHostname: host.docker.internal
    defaultProxyProvider: default

tailscale:
  providers:
    default:
      clientId: "your_client_id"
      clientSecret: "your_client_secret"
      tags: "tag:tsdproxy"
      services: true
      hostname: "tsdproxy"
      autoApproveDevices: true
      preventDuplicates: true
  dataDir: /data/

http:
  hostname: 0.0.0.0
  port: 8080

dashboard:
  adminAllowLocalhost: true

log:
  level: info
  json: false
  proxyAccessLog: true

Start the TSDProxy container

docker compose up -d

Run a sample service

Here we’ll use the nginx image to serve a sample service. The container name is sample-nginx, expose port 8111, and add the tsdproxy.enable label.

docker run -d --name sample-nginx -p 8111:80 --label "tsdproxy.enable=true" nginx:latest

Open Dashboard

1. Visit the dashboard at http://<IP_ADDRESS>:8080.
2. Sample-nginx should appear in the dashboard and start automatically (no manual authentication needed with OAuth).
3. After the proxy is running, the service is available at https://sample-nginx.<tailnet-name>.ts.net.