tsdproxy

# TSDProxy

> Go reverse proxy that exposes services on your Tailscale network with automatic HTTPS. Works with Docker containers (via labels) and non-Docker services (via YAML list files). No sidecars, no per-service Tailscale installs, no manual cert management.

TSDProxy creates a Tailscale machine for each service via tsnet, giving every service its own HTTPS endpoint on your tailnet. Docker containers are exposed by adding `tsdproxy.enable=true` labels. Non-Docker services (bare-metal apps, VMs, remote hosts) are exposed by adding entries to a YAML list file. Both paths support multi-port configurations with per-port protocol control (HTTP, HTTPS, TCP, UDP), HTTP-to-HTTPS redirects, port ranges, Tailscale Funnel for public exposure, health monitoring with automatic recovery, webhook notifications (ntfy/Discord/Slack/Gotify), a REST API for programmatic control, role-based access (admin/viewer), shared Tailscale mode (multiple proxies on one tsnet.Server), and a real-time SSE dashboard. Configuration is live-reloaded from YAML without restarts. Stack: Go 1.26, templ, Vite/Bun, htmx 4, zerolog. MIT license.

## Getting Started

- [Quick Start](https://almeidapaulopt.github.io/tsdproxy/docs/getting-started/): One compose file, one label, under a minute
- [Docker Images](https://hub.docker.com/r/almeidapaulopt/tsdproxy): `almeidapaulopt/tsdproxy:2` for latest v2 release
- [Upgrading from v1](https://almeidapaulopt.github.io/tsdproxy/docs/upgrading/from-v1/): Migration guide for v1 users

## Configuration

- [Getting Started](https://almeidapaulopt.github.io/tsdproxy/docs/getting-started/): tsdproxy.yaml format, defaults, and live reload
- [Server Config](https://almeidapaulopt.github.io/tsdproxy/docs/serverconfig/): Full configuration reference
- [Tailscale Auth](https://almeidapaulopt.github.io/tsdproxy/docs/advanced/tailscale/): AuthKey and OAuth setup for headless operation
- [List Provider](https://almeidapaulopt.github.io/tsdproxy/docs/providers/lists/): Expose non-Docker services via YAML file

## Docker Labels

- [Docker Provider](https://almeidapaulopt.github.io/tsdproxy/docs/providers/docker/): All `tsdproxy.*` labels for container configuration
- [Port Configuration](https://almeidapaulopt.github.io/tsdproxy/docs/providers/docker/#port-configuration): Multi-port, TCP, UDP, redirect, ranges, and protocol options
- [Docker Reference](https://almeidapaulopt.github.io/tsdproxy/docs/providers/docker-reference/): Complete label reference

## Ports and Protocols

- [TCP Proxy](https://almeidapaulopt.github.io/tsdproxy/docs/advanced/tcp-proxy/): Proxy SSH, databases, and other TCP services
- [Funnel](https://almeidapaulopt.github.io/tsdproxy/docs/security/funnel/): Expose services to the public internet

## Operations

- [REST API](https://almeidapaulopt.github.io/tsdproxy/docs/operations/api/): Programmatic control over proxies — pause, resume, manage
- [Health Checks](https://almeidapaulopt.github.io/tsdproxy/docs/operations/health-check/): Automatic backend health probes with recovery and target re-resolution
- [Webhooks](https://almeidapaulopt.github.io/tsdproxy/docs/notifications/): Push events to ntfy, Discord, Slack, Gotify, or generic webhooks
- [Backup](https://almeidapaulopt.github.io/tsdproxy/docs/operations/backup/): Backup and restore

## Security

- [Admin Allowlist](https://almeidapaulopt.github.io/tsdproxy/docs/security/admin-allowlist/): Restrict admin access by IP
- [Auth Methods](https://almeidapaulopt.github.io/tsdproxy/docs/security/auth-methods/): Authentication options
- [Docker Socket Security](https://almeidapaulopt.github.io/tsdproxy/docs/security/docker-socket/): Docker socket considerations

## Architecture

- [GitHub Repository](https://github.com/almeidapaulopt/tsdproxy): Source code, issues, and releases
- [Contributing Guide](https://github.com/almeidapaulopt/tsdproxy/blob/main/CONTRIBUTING.md): Code style, project structure, and PR process

## Development

- [Contributing](https://github.com/almeidapaulopt/tsdproxy/blob/main/CONTRIBUTING.md): Setup with `make bootstrap`, dev with `make dev`, quality with `make audit`
- [Source Code](https://github.com/almeidapaulopt/tsdproxy): Go 1.26, templ UI, Vite/Bun frontend, Hugo docs

## Optional

- [Sponsor the Project](https://github.com/sponsors/almeidapaulopt): Support ongoing development
- [Tailscale](https://tailscale.com/): The mesh VPN platform TSDProxy builds on

More agent context in almeidapaulopt/tsdproxy

4 other files this repository gives its agents.