Server configuration
TSDProxy utilizes the configuration file /config/tsdproxy.yaml for its settings.
The config file path can be overridden using the --config CLI flag:
tsdproxy --config /path/to/tsdproxy.yamlImportant
Environment variable configurations used in versions prior to v0.6.0 are
deprecated and will be removed in future releases. However, some legacy env vars are still read during initial config generation: DOCKER_HOST, TSDPROXY_HOSTNAME, TSDPROXY_AUTHKEY, TSDPROXY_AUTHKEYFILE, TSDPROXY_CONTROLURL, and TSDPROXY_DATADIR.
Sample Configuration File
Warning
Configuration files are case-sensitive.
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
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
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: 0.0.0.0 # HTTP server hostname
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)Configuration Sections
tailscale Section
Configures Tailscale integration.
dataDir
Specifies the data directory used by Tailscale. Defaults to /data/.
providers
Defines multiple Tailscale providers. Each provider has the following options:
default: # Provider name
authKey: your-authkey # Tailscale auth key
authKeyFile: "" # Path to auth key file
controlUrl: https://controlplane.tailscale.com # Tailscale control URLExample with multiple providers:
tailscale:
providers:
default:
authKey: your-authkey
authKeyFile: ""
controlUrl: https://controlplane.tailscale.com
server1:
authKey: authkey-server1
authKeyFile: ""
controlUrl: http://server1
differentkey:
authKey: authkey-with-different-tags
authKeyFile: ""
controlUrl: https://controlplane.tailscale.comThis example configures three Tailscale providers: default (default server),
server1 (different Tailscale server), and differentkey (default server with
a different auth key for specific tags).
Tip
For more details, see the Tailscale page.
docker Section
Configures Docker server connections. Multiple Docker servers can be defined:
local: # Docker provider name
host: unix:///var/run/docker.sock # Docker socket or daemon address
targetHostname: 172.31.0.1 # Docker server hostname or IP
defaultProxyProvider: default # Default proxy provider for this Docker serverExample with multiple Docker servers:
docker:
local:
host: unix:///var/run/docker.sock
defaultProxyProvider: default
srv1:
host: tcp://174.17.0.1:2376
targetHostname: 174.17.0.1
defaultProxyProvider: server1This example configures a local Docker server and a remote srv1 server.
host
Specifies the Docker socket or daemon address. Defaults to unix:///var/run/docker.sock.
targetHostname
Specifies the IP address or DNS name of the Docker server. Used for connecting to containers in specific cases.
defaultProxyProvider
Specifies the default Tailscale provider (defined in the tailscale.providers
section) to use for containers on this Docker server. Container-specific labels
override this setting.
tryDockerInternalNetwork
Defaults to false. When set to true, containers default to using
auto-detection of the target URL via connectivity probing. This sets the default
for the per-container tsdproxy.autodetect label. Individual containers can
still override this with the tsdproxy.autodetect label.
docker:
local:
host: unix:///var/run/docker.sock
targetHostname: host.docker.internal
defaultProxyProvider: default
tryDockerInternalNetwork: truehttp Section
Configures the built-in HTTP server that serves the dashboard and health endpoints.
hostname
The bind address for the HTTP server. Defaults to 0.0.0.0 (all interfaces).
port
The port for the HTTP server. Defaults to 8080.
log Section
level
Defines the logging level. Options are debug, info, warn, error, fatal, panic, or trace.
The default is info.
json
Enables JSON-formatted logging when set to true. Defaults to false.
proxyAccessLog
Enables access logging for proxied requests. Defaults to true. Can be
overridden per-container with the tsdproxy.containeraccesslog label or
per-list with defaultProxyAccessLog.
Configuration File Lifecycle
Auto-Generation
On first run, TSDProxy generates a default config automatically.
Live Reload
- Proxy list files reload automatically on changes. No restart needed.
- Main config changes require a restart.
Validation
Config files are strictly validated. Unknown keys or invalid values cause load failures.