### New and Start Proxy Workflow

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/internal/proxymanager/AGENTS.md

Describes the steps involved in creating and starting a new proxy, including provider resolution and setup.

```go
`newAndStartProxy`: resolve auth key → `proxyProvider.NewProxy()` → create `Proxy` → `resolveAndSetProviders()` → `setupDomainForProxy()` (DNS create + TLS provision + hostname assignment) → `proxy.Start()` → register in `pm.Proxies`.
```

--------------------------------

### Install Mise and Project Tools

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/CONTRIBUTING.md

Installs mise, a tool manager, and then uses it to install all project-specific development tools.

```bash
curl https://mise.run | sh
eval "$(mise activate bash)"  # or zsh/fish
mise install
```

--------------------------------

### CLI Management Commands Example

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/advanced/roadmap.md

Examples of using the TSDProxy CLI to list services or restart a specific proxy instance, utilizing existing HTTP endpoints.

```bash
tsdproxy --config /config/tsdproxy.yaml list
tsdproxy --config /config/tsdproxy.yaml restart myproxy
```

--------------------------------

### Documentation Commands

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/AGENTS.md

Command to start the Hugo documentation server.

```bash
# Docs
make docs                   # Hugo docs server (localhost:1313)
```

--------------------------------

### Docker Compose Example for Headscale and TSDProxy

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/advanced/headscale.md

A complete docker-compose.yml file to run Headscale and TSDProxy together on a shared Docker network. This setup allows TSDProxy to reach Headscale internally without exposing ports externally.

```yaml
services:
  headscale:
    image: headscale/headscale:latest
    volumes:
      - ./headscale/config:/etc/headscale
      - ./headscale/data:/var/lib/headscale
    ports:
      - "8080:8080"
    networks:
      - tsdproxy-net

  tsdproxy:
    image: almeidapaulopt/tsdproxy:2
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./tsdproxy-data:/data
      - ./tsdproxy-config:/config
    networks:
      - tsdproxy-net
    depends_on:
      - headscale

networks:
  tsdproxy-net:
```

--------------------------------

### Development Commands

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/AGENTS.md

Commands for local development, including starting containers, building binaries, and running the application.

```bash
# Development
make dev                    # Start docker containers + assets + server with hot reload (air)
make build                  # Build binary to ./tmp/tsdproxy (ldflags version injection)
make run                    # Build + run (needs make bootstrap first)
```

--------------------------------

### HTTP Server Lifecycle

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/internal/core/AGENTS.md

Outlines the sequence of operations for creating, configuring, starting, and shutting down the HTTP server.

```go
NewHTTPServer(log)         → creates mux
HTTPServer.Use(mw...)      → adds middleware to chain
HTTPServer.Handle(pattern, handler) → registers with wrapped handler
HTTPServer.StartServer(ln) → http.Server.Serve(ln)
                            → health.SetReady() on success
Shutdown(ctx, 10s timeout) → health.SetNotReady() → server.Shutdown()
```

--------------------------------

### Start TSDProxy with Docker Compose

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/README.md

Command to start the services defined in the docker-compose.yml file in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Basic Docker Compose with Auth Key

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/static/llms-full.txt

A basic Docker Compose setup for TSDProxy, including volume mounts for Docker socket, TSDProxy data, and configuration files, along with port mappings and example services labeled for TSDProxy.

```yaml
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

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

  api:
    image: myapi:latest
    labels:
      tsdproxy.enable: "true"
      tsdproxy.name: "api"
      tsdproxy.port.1: "443/https:3000/http"

volumes:
  tsdproxy-data:
```

--------------------------------

### User Access Control Configuration Example

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/advanced/roadmap.md

Proposed configuration for restricting access to a proxy based on allowed Tailscale users.

```yaml
# Proposed label
tsdproxy.port.1: "443/https:80/http, allow_users=alice,bob"
```

--------------------------------

### TCP Proxying Configuration

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/advanced/roadmap.md

Configuration example for enabling raw TCP proxying on a specific port.

```yaml
tsdproxy.port.1: "5432/tcp:5432"
```

--------------------------------

### Run TSDProxy Standalone

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/deployment/standalone.md

Execute the TSDProxy binary with a specified configuration file. Ensure the configuration path is correct for your setup.

```bash
tsdproxy --config /etc/tsdproxy/tsdproxy.yaml
```

--------------------------------

### Event Lifecycle Handling

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/internal/proxymanager/AGENTS.md

Outlines the event handling flow from watching target provider events to starting and stopping proxies.

```go
TargetProvider.WatchEvents() → eventsChan
  → HandleProxyEvent(event)
      getTargetLock(event.ID)     // per-ID mutex from sync.Map
      ActionStartProxy  → eventStart()  → newAndStartProxy()
      ActionStopProxy   → eventStop()   → closeAndRemoveProxy()
      ActionRestartProxy → stop then start
```

--------------------------------

### Frontend Development Commands

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/AGENTS.md

Commands for the web frontend, including starting the Vite dev server and building for production.

```bash
# Frontend
cd web && bun run dev       # Vite dev server (proxies to Go backend on :8080)
cd web && bun run build     # Build frontend to web/dist/
```

--------------------------------

### Structured Logging Example

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/static/llms-full.txt

Utilize zerolog for structured logging by creating a logger with specific fields. This ensures logs are machine-readable and easily filterable.

```go
log.With().Str("key", val).Logger()
```

--------------------------------

### Proxy Template Configuration

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/advanced/roadmap.md

Example of defining a reusable proxy template in the main configuration and applying it using Docker labels.

```yaml
# /config/tsdproxy.yaml
templates:
  webapp:
    ports:
      - "443/https"
    options: "no_autodetect"

# Docker label
tsdproxy.template: "webapp"
tsdproxy.port.1: "443/https:8080/http"
```

--------------------------------

### IP Access Control Configuration Example

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/advanced/roadmap.md

Proposed configuration for restricting access to a proxy based on allowed IP addresses.

```yaml
# Proposed label
tsdproxy.port.1: "443/https:80/http, allow_ips=100.64.0.0/10"
```

--------------------------------

### Rate Limiting Configuration Example

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/advanced/roadmap.md

Proposed configuration snippet for applying rate limiting to a specific port, specifying the maximum requests per minute.

```yaml
# Proposed label
tsdproxy.port.1: "443/https:80/http, rate_limit=100/min"
```

--------------------------------

### List Provider Configuration (YAML file)

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/static/llms-full.txt

Example of defining services in a separate YAML file for the List provider, including port mappings and redirect configurations. This file is then referenced in the main TSDProxy configuration.

```yaml
# /config/services.yaml
my-local-app:
  ports:
    "443/https":
      targets:
        - "http://localhost:3000"

home-assistant:
  ports:
    "443/https":
      targets:
        - "http://192.168.1.100:8123"
    "80/http":
      isRedirect: true
      targets:
        - "https://home-assistant.tailnet.ts.net"
```

```yaml
files:
  services:
    filename: /config/services.yaml
```

--------------------------------

### Multi-Port Service Configuration

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/static/llms-full.txt

Example Docker Compose configuration for a service exposing multiple ports, including HTTP, HTTPS, and TCP, with specific mappings and an example of redirecting HTTP to HTTPS.

```yaml
services:
  myservice:
    image: myservice:latest
    labels:
      tsdproxy.enable: "true"
      tsdproxy.name: "myservice"
      # Main web interface
      tsdproxy.port.1: "443/https:8080/http"
      # API endpoint on different port
      tsdproxy.port.2: "8443/https:9090/http"
      # SSH access via TCP
      tsdproxy.port.3: "2222/tcp:22/tcp"
      # Redirect HTTP to HTTPS
      tsdproxy.port.4: "80/http->https://myservice.tailnet.ts.net"
```

--------------------------------

### Configure HTTP Redirect to HTTPS

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/providers/docker-reference.md

Example of setting up a redirect from an HTTP port (80) to a HTTPS URL. This is useful for enforcing HTTPS for external access.

```yaml
tsdproxy.port.1: "80/http->https://myapp.tailnet-name.ts.net"
```

--------------------------------

### Error Wrapping Example

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/static/llms-full.txt

Use fmt.Errorf with the %w verb to wrap errors, preserving the original error context. This aids in debugging and error handling.

```go
fmt.Errorf("context: %w", err)
```

--------------------------------

### Proxy Lifecycle Webhooks Configuration

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/advanced/roadmap.md

Proposed configuration for setting up webhook URLs that receive POST requests on proxy state transitions like start or error.

```yaml
proxyname:
  webhooks:
    on_start: https://ntfy.sh/mytopic
    on_error: https://discord.webhook/url
```

--------------------------------

### Basic Gotify Configuration

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/notifications/gotify.md

Configure TSDProxy to send generic JSON payloads to Gotify using a URL with the app token. Use this for basic setup when the token can be included in the URL.

```yaml
webhooks:
  - url: "https://gotify.example.com/message?token=your-app-token"
    type: generic
    events:
      - Running
      - Stopped
      - Error
```

--------------------------------

### Docker Compose Configuration for TSDProxy

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/advanced/environment-variables.md

Example of how to configure TSDProxy using Docker Compose. It includes volume mounts for the Docker socket, configuration file, and data directory, as well as port mapping and optional environment variable overrides.

```yaml
services:
  tsdproxy:
    image: almeidapaulopt/tsdproxy:2
    container_name: tsdproxy
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./tsdproxy.yaml:/config/tsdproxy.yaml
      - ./data:/data
    environment:
      # Optional: override Docker daemon address
      DOCKER_HOST: "unix:///var/run/docker.sock"
    ports:
      - "8080:8080"
    restart: unless-stopped

```

--------------------------------

### TCP Proxy for Database Example

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/static/llms-full.txt

Docker Compose configuration demonstrating how to set up TSDProxy to act as a TCP proxy for a database service, exposing the database port securely.

```yaml
services:
  tsdproxy:
    image: almeidapaulopt/tsdproxy:2
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - tsdproxy-data:/data
      - ./config:/config
    ports:
      - "8080:8080"
    restart: unless-stopped

  postgres:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    labels:
      tsdproxy.enable: "true"
      tsdproxy.name: "postgres"
      tsdproxy.port.1: "5432/tcp:5432/tcp"
```

--------------------------------

### Define Lists in tsdproxy.yaml

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/providers/lists.md

Specify the target providers (lists) to be used in your main TSDProxy configuration file. This example defines 'critical' and 'media' providers.

```yaml
lists:
  critical:
    filename: /config/critical.yaml
    defaultProxyProvider: tailscale1
    defaultProxyAccessLog: true
  media:
    filename: /config/media.yaml
    defaultProxyProvider: default
    defaultProxyAccessLog: false
```

--------------------------------

### Configure TSDProxy as a Systemd Service

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/deployment/standalone.md

Set up TSDProxy to run as a systemd service for automatic startup and management. This configuration assumes TSDProxy is installed at /usr/local/bin/tsdproxy and uses a YAML configuration file.

```ini
[Unit]
Description=TSDProxy
After=network.target docker.service
Requires=docker.service

[Service]
Type=simple
ExecStart=/usr/local/bin/tsdproxy --config /etc/tsdproxy/tsdproxy.yaml
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Configure TSDProxy Service Labels

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/deployment/docker-swarm.md

Example of how to use service labels to enable and configure TSDProxy for a specific service, such as Nginx. Labels define TSDProxy's behavior for routing and naming.

```yaml
services:
  nginx:
    image: nginx:latest
    deploy:
      labels:
        tsdproxy.enable: "true"
        tsdproxy.name: "my-nginx"
        tsdproxy.port.1: "443/https:80/http"
```

--------------------------------

### Configure Dashboard Hostname for Non-Docker Setups

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/troubleshooting.md

For non-Docker TSDProxy installations, explicitly set the HTTP hostname to '0.0.0.0' to ensure the dashboard is accessible from outside the container, especially after upgrading to v2.2.0.

```yaml
http:
  hostname: 0.0.0.0
  port: 8080
```

--------------------------------

### Sample TSDProxy Configuration File

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/serverconfig.md

This is a sample tsdproxy.yaml configuration file. Configuration files are case-sensitive. It includes settings for default proxy provider, Docker integration, list providers, Tailscale integration, HTTP server, logging, and API keys.

```yaml
defaultProxyProvider: default
docker:
  local: # Name of the Docker target provider
    host: unix:///var/run/docker.sock # Docker socket or daemon address
    targetHostname: host.docker.internal # hostname or IP of docker server (ex: host.docker.internal or 172.31.0.1)
    defaultProxyProvider: default # Default proxy provider for this Docker server
    autoRestart: true # (optional) Enable automatic re-resolution on backend failure (default: true)
    healthCheckEnabled: true # (optional) Enable health probes (default: true)
    healthCheckInterval: 30 # (optional) Seconds between health probes (default: 30)
    healthCheckFailures: 3 # (optional) Consecutive failures before re-resolution (default: 3)
    healthCheckCooldown: 0 # (optional) Fixed cooldown in seconds, 0 for exponential backoff (default: 0)
lists:
  critical: # Name of the target list provider
    filename: /config/critical.yaml # Path to the proxy list file
    defaultProxyProvider: tailscale1 # (Optional) Default proxy provider for this list
    defaultProxyAccessLog: true # (Optional) Enable access logs for this list
    autoRestart: true # (optional) Enable automatic re-resolution on backend failure (default: true)
    healthCheckEnabled: true # (optional) Enable health probes (default: true)
    healthCheckInterval: 30 # (optional) Seconds between health probes (default: 30)
    healthCheckFailures: 3 # (optional) Consecutive failures before re-resolution (default: 3)
    healthCheckCooldown: 0 # (optional) Fixed cooldown in seconds, 0 for exponential backoff (default: 0)
tailscale:
  providers:
    default: # Name of the Tailscale provider
      clientId: "your_client_id" # OAuth client ID (generated by Tailscale)
      clientSecret: "your_client_secret" # OAuth client secret (generated by Tailscale)
                                         # If clientId and clientSecret are defined, authKey 
                                         # and authKeyFile are ignored
      authKey: "" # Tailscale auth key (alternative to OAuth)
      authKeyFile: "" # Path to a file containing the auth key (ignores authKey if defined)
      tags: "tag:example,tag:server" # Default tags for all containers using this provider
                                     # Container-specific tags override these default tags
      controlUrl: https://controlplane.tailscale.com # Override the default Tailscale control URL
      preventDuplicates: false # Delete stale tailnet devices before creating new nodes (OAuth only)
      maxCertConcurrency: 2 # Max parallel TLS cert generation requests (default: 2)
  dataDir: /data/ # Tailscale data directory
http:
  hostname: 127.0.0.1 # HTTP server hostname (changed from 0.0.0.0 — see breaking changes)
  port: 8080 # HTTP server port
log:
  level: info # Logging level (debug, info, warn, error, fatal, panic, trace)
  json: false # Enable JSON logging (true/false)
proxyAccessLog: true # Enable container access logs (true/false)
apiKey: "" # API key for non-Tailscale authentication (optional)
apiKeyFile: "" # Path to a file containing the API key (optional)
admins: [] # Tailscale UserProfile.IDs authorized for admin actions (optional)
            # Example: admins: ["12345" # alice@github, "67890" # bob@example.com]
adminAllowLocalhost: false # Permit localhost to bypass admin allowlist (for bootstrapping)

```

--------------------------------

### Get TSDProxy Version

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/operations/api.md

Retrieve build information for the TSDProxy application.

```http
GET /api/version
```

```json
{
  "version": "2.0.0",
  "author": "almeidapaulopt",
  "isDirty": false
}
```

--------------------------------

### Go Project Structure Overview

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/CONTRIBUTING.md

Provides a high-level overview of the TSDProxy project's directory structure and the purpose of key files and directories.

```plaintext
cmd/server/main.go        Main server binary
cmd/healthcheck/main.go   Docker HEALTHCHECK binary
internal/
  config/                 Configuration loading and file watching
  core/                   HTTP server, logging, health, sessions
  dashboard/              SSE dashboard routes and streaming
  model/                  Shared types (Config, PortConfig, ProxyStatus)
  proxymanager/           Central orchestrator wiring targets to proxies
  proxyproviders/         Proxy provider interface and Tailscale implementation
  targetproviders/        Target provider interface and Docker/List implementations
  ui/                     templ-generated UI components
web/                      Frontend: Vite + Bun, embedded in the binary via go:embed
docs/                     Hugo documentation site (separate go.mod)
e2e/                      End-to-end tests (build tag: e2e)
```

--------------------------------

### Proxy Provider Resolution

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/internal/proxymanager/AGENTS.md

Details how the proxy provider is resolved during the event start process.

```go
`proxyCfg.ProxyProvider` → target provider default → `config.DefaultProxyProvider` → `ErrProxyProviderNotFound`
```

--------------------------------

### Required SPDX Headers for Go Files

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/CONTRIBUTING.md

Demonstrates the required SPDX license and copyright headers for all Go files in the project. This is enforced by CI.

```go
// SPDX-FileCopyrightText: 2026 Paulo Almeida <almeidapaulopt@gmail.com>
// SPDX-License-Identifier: MIT
```

--------------------------------

### Get Proxy Ports Configuration

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/operations/api.md

Retrieve only the port configuration details for a specific proxy.

```http
GET /api/v1/proxies/{name}/ports
```

```json
{
  "ports": [
    {
      "name": "443/https",
      "proxyProtocol": "https",
      "proxyPort": 443,
      "targetUrl": "http://172.31.0.1:80",
      "tlsValidate": true,
      "isRedirect": false,
      "funnel": false
    }
  ]
}
```

--------------------------------

### Kubernetes Target Provider Annotation

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/advanced/roadmap.md

Example of Kubernetes annotations to enable and configure TSDProxy for a service.

```yaml
# k8s annotation
metadata:
  annotations:
    tsdproxy.enable: "true"
    tsdproxy.name: "my-service"
```

--------------------------------

### Get Prometheus Metrics

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/operations/api.md

Access Prometheus metrics for TSDProxy. This endpoint is protected by admin middleware.

```http
GET /metrics
```

--------------------------------

### HTTPServer Middleware Chain

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/internal/core/AGENTS.md

Demonstrates the order of middleware applied globally to the HTTPServer. This chain is applied via HTTPServer.Use() in InitializeApp().

```go
StripProxyIdentityHeaders  →  SessionMiddleware  →  CSRFMiddleware
```

--------------------------------

### Get Health Summary

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/operations/api.md

Retrieve an aggregated summary of proxy health status across the TSDProxy instance.

```http
GET /api/health
```

```json
{
  "total": 5,
  "running": 4,
  "stopped": 0,
  "error": 0,
  "paused": 1,
  "unhealthy": 0
}
```

--------------------------------

### Clone Repository and Bootstrap Project

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/CONTRIBUTING.md

Clones the TSDProxy repository and runs the bootstrap make target to set up frontend assets and generate templ files.

```bash
git clone https://github.com/almeidapaulopt/tsdproxy.git
cd tsdproxy
make bootstrap
```

--------------------------------

### Build and Run E2E Tests

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/e2e/AGENTS.md

Commands to build and execute the end-to-end tests for tsdproxy. Ensure you have the necessary authentication keys set.

```bash
make test/e2e
go test -tags=e2e -timeout=0 ./e2e/
TSDPROXY_E2E_AUTHKEY=tskey-auth-xxx go test -tags=e2e -run TestBasicProxy ./e2e/
```

--------------------------------

### Get proxy ports

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/operations/api.md

Retrieves only the port configuration for a specific proxy. This is useful for inspecting how a proxy handles incoming connections.

```APIDOC
## GET /api/v1/proxies/{name}/ports

### Description
Returns only the port configuration for a proxy.

### Method
GET

### Endpoint
/api/v1/proxies/{name}/ports

### Parameters
#### Path Parameters
- **name** (string) - Required - The hostname of the proxy whose ports to retrieve.
```

--------------------------------

### Run Sample Nginx Service

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/getting-started.md

Command to run a sample Nginx service container, exposing port 8111 and enabling TSDProxy with a label.

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

--------------------------------

### Get a proxy

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/operations/api.md

Retrieves details for a specific proxy identified by its name. The response format is identical to the entries in the list of all proxies.

```APIDOC
## GET /api/v1/proxies/{name}

### Description
Returns a single proxy by hostname. Same shape as the list entry above.

### Method
GET

### Endpoint
/api/v1/proxies/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The hostname of the proxy to retrieve.
```

--------------------------------

### Get Caller Identity (WhoAmI)

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/operations/api.md

Retrieve the Tailscale identity of the API caller. This endpoint requires an active Tailscale connection.

```http
GET /api/whoami
```

```json
{
  "id": "12345",
  "displayName": "Alice",
  "username": "alice@github",
  "profilePicUrl": "https://avatars.tailscale.com/..."
}
```

--------------------------------

### List Target Provider Configuration Structure

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/static/llms-full.txt

Defines the configuration for the List target provider, specifying the path to the proxy definitions file and optional overrides for the default proxy provider and access log settings.

```go
type ListTargetProviderConfig struct {
    Filename              string // Path to the YAML file with proxy definitions
    DefaultProxyProvider  string // Override proxy provider
    DefaultProxyAccessLog bool   // Default access log setting (default: true)
}
```

--------------------------------

### Get a Proxy by Name

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/operations/api.md

Retrieve details for a single proxy by its name. The response structure is identical to the list all proxies endpoint.

```http
GET /api/v1/proxies/{name}
```

--------------------------------

### Docker Commands

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/AGENTS.md

Commands for building and running Docker images for the project.

```bash
# Docker
make docker_image           # Build local Docker image (Dockerfile)
make dev_docker             # Run dev container
```

--------------------------------

### UDP Proxy Lists Configuration

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/advanced/tcp-proxy.md

Demonstrates how to configure UDP port proxying, including single ports and ranges, using TSDProxy's lists configuration file.

```yaml
myapp:
  ports:
    5000/udp:
      targets:
        - udp://192.168.1.10:5000
neko:
  ports:
    56000-56002/udp:
      targets:
        - udp://192.168.1.10:56000
```

--------------------------------

### Release Commands (CI)

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/AGENTS.md

Notes on release commands managed by GoReleaser for stable and development builds.

```bash
# Release (CI)
# Tags v1.* → .goreleaser.yaml (stable, DockerHub + GHCR + Homebrew + AUR + cosign)
# Push to main → .goreleaser-dev.yaml (dev snapshot, draft, Docker images only)
```

--------------------------------

### Test Webhook

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/notifications/_index.md

Send a test webhook from the API to all configured webhooks.

```bash
curl -X POST http://localhost:8080/api/webhook/test
```

--------------------------------

### Rollback TSDProxy to v1

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/upgrading/from-v1.md

Procedure to roll back TSDProxy to version 1, involving stopping the current version, restoring configuration, and starting the older image.

```bash
docker compose down
# Restore config backup
# Change image tag back to almeidapaulopt/tsdproxy:1
docker compose up -d
```

--------------------------------

### Enable Tailscale Web Client with Docker Labels

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/providers/docker.md

Use the 'tsdproxy.runwebclient' label to enable the Tailscale web client on port 5252.

```yaml
labels:
  tsdproxy.enable: "true"
  tsdproxy.name: "myserver"
  tsdproxy.runwebclient: "true"
```

--------------------------------

### Enable Trace Logging for Network Troubleshooting

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/advanced/docker-networking.md

Enable trace logging to get detailed information about auto-detection attempts and failures. This is crucial for diagnosing network issues.

```yaml
log:
  level: trace
```

--------------------------------

### Provider Registration

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/internal/proxymanager/AGENTS.md

Shows the different providers that can be registered for targets, proxies, DNS, and TLS.

```go
addTargetProviders()  — config.Docker → docker.New, config.Lists → list.New
addProxyProviders()   — config.Tailscale.Providers → tsproxy.New
addDNSProviders()     — switch cfg.Provider: "cloudflare" | "magicdns"
addTLSProviders()     — switch cfg.Provider: "acme" (needs DNS) | "tailscale" (warns: auto-created)
```

--------------------------------

### Lists Provider for Dashboard Customization

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/advanced/dashboard.md

Configure the dashboard appearance for a proxy within the Lists provider configuration. This example sets a custom label and icon for a 'nas' proxy.

```yaml
nas:
  ports:
    443/https:
      targets:
        - http://nas.local:5001
  dashboard:
    visible: true
    label: "File Server"
    icon: "si/synology"
```

--------------------------------

### Docker Labels for Dashboard Customization

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/advanced/dashboard.md

Customize the dashboard appearance for a proxy using Docker labels. This example sets a custom label, icon, and category for a 'nas' proxy.

```yaml
labels:
  tsdproxy.enable: "true"
  tsdproxy.name: "nas"
  tsdproxy.dash.label: "File Server"
  tsdproxy.dash.icon: "si/synology"
  tsdproxy.dash.category: "Storage"
```

--------------------------------

### Lifecycle Manager DNS Operations Pattern

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/internal/dnsproviders/AGENTS.md

Illustrates the sequence of operations for setting up and cleaning up DNS records using the LifecycleManager, including retries for validation.

```go
SetupDNS(ctx, domain, recordType, value)
  → provider.CreateRecord(ctx, domain, recordType, value)
  → retryWithBackoff: provider.ValidateRecord(ctx, domain, recordType, value)
  → status: DNSStatusActive

CleanupDNS(ctx, domain, recordType)
  → provider.DeleteRecord(ctx, domain, recordType)
  → status: DNSStatusNone
```

--------------------------------

### Configure TCP Proxy for SSH

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/providers/docker-reference.md

Example of configuring TSDProxy to forward TCP traffic for SSH (port 22) to a container's SSH service also on port 22.

```yaml
tsdproxy.port.1: "22/tcp:22/tcp"
```

--------------------------------

### Connect to Proxied PostgreSQL Service

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/advanced/tcp-proxy.md

Connect to a PostgreSQL database exposed via TSDProxy using the `psql` command-line client.

```bash
psql -h postgres.your-tailnet.ts.net -p 5432 -U myuser mydb
```

--------------------------------

### Version

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/operations/api.md

Retrieves the build information for the TSDProxy instance, including the version number, author, and whether the build is dirty.

```APIDOC
## GET /api/version

### Description
TSDProxy build info.

### Method
GET

### Endpoint
/api/version
```

--------------------------------

### Configure Multiple Ports with Protocols and Options

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/README.md

Use labels to enable TSDProxy and define various port mappings. Supports HTTPS, HTTP redirects, TCP, UDP, and port ranges.

```yaml
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"
```

--------------------------------

### Proxy List Configuration Format

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/advanced/tcp-proxy.md

Illustrates the general format for configuring TCP proxy targets within a TSDProxy lists configuration file.

```yaml
proxyname:
  ports:
    <port>/tcp:
      targets:
        - tcp://<hostname>:<port>
```

--------------------------------

### Configure TCP Proxy for Database

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/providers/docker-reference.md

Example of configuring TSDProxy to forward TCP traffic for a database service (port 5432) to a container's database service also on port 5432.

```yaml
tsdproxy.port.1: "5432/tcp:5432/tcp"
```

--------------------------------

### Configure HTTPS Proxy to HTTP Backend

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/providers/docker-reference.md

Example of configuring TSDProxy to proxy HTTPS traffic on port 443 to an HTTP backend service running on port 80 within the container.

```yaml
tsdproxy.port.1: "443/https:80/http"
```

--------------------------------

### Configure TSDProxy with Headscale

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/advanced/headscale.md

Set the 'controlUrl' to your Headscale instance's address and provide the generated AuthKey in the TSDProxy configuration file. Ensure the URL and key are correct.

```yaml
tailscale:
  providers:
    default:
      controlUrl: http://headscale:8080
      authKey: "your_preauthkey_here"
      authKeyFile: ""
  dataDir: /data/
```

--------------------------------

### Disabling Auto-detection with Host Networking

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/examples/home-assistant.md

When Home Assistant uses host networking, TSDProxy's auto-detection may fail. This example shows how to disable auto-detection and explicitly specify the port.

```yaml
labels:
  tsdproxy.enable: "true"
  tsdproxy.name: "homeassistant"
  tsdproxy.autodetect: "false"
  tsdproxy.port.1: "443/https:8123/http, no_autodetect"
```

--------------------------------

### Testing Commands

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/AGENTS.md

Commands for running unit tests, tests with coverage reports, and end-to-end tests.

```bash
# Testing
make test                   # Run all unit tests (gotestsum -race -buildvcs)
make test/cover             # Tests with coverage report
make test/e2e               # E2E tests with gotestsum -tags=e2e (needs TSDPROXY_E2E_AUTHKEY)
```

--------------------------------

### Configure Multiple Webhooks

Source: https://github.com/almeidapaulopt/tsdproxy/blob/main/docs/content/docs/notifications/_index.md

Configure multiple webhooks for different services or topics in `/config/tsdproxy.yaml`.

```yaml
webhooks:
  - url: "https://ntfy.sh/alerts"
    type: ntfy
    events: [Running, Error, Stopped]

  - url: "https://discord.com/api/webhooks/123/abc"
    type: discord
    events: [Error]
```