Docker configuration parameters

Configuration parameters are passed as environment variables in your container definition. These parameters control how a Tailscale container authenticates to your tailnet, manages networking, and exposes services.

You can use parameters to configure authentication methods, enable features like DNS, metrics, and health checks, advertise routes, or forward traffic to other services. Set these variables in your Docker configuration (such as Docker run, Compose, or Kubernetes manifests) to customize how the container joins and operates within your tailnet.

TS_ACCEPT_DNS

Accept DNS configuration from the Tailscale admin console. Defaults to not accepted. Enable this if you want your container to use MagicDNS and custom DNS settings from your tailnet. Without this, the container uses Docker's default DNS configuration.

TS_AUDIENCE

The audience to use when requesting an ID token from a well-known identity provider for workload identity federation. Use this parameter in environments that support automatic ID token generation, such as GitHub Actions, Google Cloud, or AWS. You must use this with TS_CLIENT_ID. You cannot use this parameter with TS_CLIENT_SECRET or TS_ID_TOKEN.

TS_AUTH_ONCE

Controls login behavior. Set to false by default, which forces login every time the container starts. Set TS_AUTH_ONCE=true to log in only if the container isn't already authenticated. Use this when you're persisting state and don't want unnecessary re-authentication.

TS_AUTHKEY

Authenticates a container to your tailnet. Create an authentication key in the Tailscale admin console, then paste it here. This is equivalent to what you would pass to tailscale login --auth-key=. You can also use an OAuth client secret here, but you must provide the associated tag using TS_EXTRA_ARGS=--advertise-tags=tag:ci.

To mark a containerized node as ephemeral (automatically removed when disconnected), append ?ephemeral=true to the auth key or OAuth client secret. Use this for temporary containers or CI/CD environments.

You cannot use this parameter with TS_CLIENT_ID, TS_CLIENT_SECRET, TS_ID_TOKEN, or TS_AUDIENCE.

TS_CLIENT_ID

The OAuth client ID for authentication. You can use it alone (for example, when an ID token auto-generates in well-known environments like GitHub Actions), with TS_CLIENT_SECRET for OAuth authentication, with TS_ID_TOKEN for workload identity federation, or with TS_AUDIENCE for automatic ID token generation in supported environments.

If the value begins with file:, Tailscale treats it as a path to a file containing the client ID.

TS_CLIENT_SECRET

The OAuth client secret for generating auth keys. You must use this with TS_CLIENT_ID for OAuth authentication. If the value begins with file:, Tailscale treats it as a path to a file containing the secret. This is more secure than embedding secrets directly in your setup. You cannot use this parameter with TS_ID_TOKEN or TS_AUDIENCE.

TS_DEST_IP

Proxies all incoming Tailscale traffic to the specified destination IP. Use this when you want all traffic that reaches your Tailscale container to forward to a specific service. For example, TS_DEST_IP=100.0.0.5 sends all traffic to that IP address.

TS_ENABLE_HEALTH_CHECK

Set to true to enable an unauthenticated /healthz endpoint at the address you specify with TS_LOCAL_ADDR_PORT. The health check returns 200 OK if the node has at least one tailnet IP address. Otherwise it returns 503. Use this for container orchestration health checks.

TS_ENABLE_METRICS

Set to true to enable an unauthenticated /metrics endpoint at the address you specify with TS_LOCAL_ADDR_PORT. Refer to client metrics for more information about the available metrics. This is useful for monitoring your Tailscale container's performance and connection status.

TS_HEALTHCHECK_ADDR_PORT

TS_HOSTNAME

Sets a custom hostname for your container on the tailnet. Without this, Docker generates a random hostname. This is equivalent to tailscale set --hostname=. For example, TS_HOSTNAME=my-dev-database makes your container accessible at my-dev-database in your tailnet.

TS_ID_TOKEN

The ID token from the identity provider for workload identity federation. You must use this with TS_CLIENT_ID. If the value begins with file:, Tailscale treats it as a path to a file containing the token.

You cannot use this parameter with TS_CLIENT_SECRET or TS_AUDIENCE.

TS_KUBE_SECRET

If you're running in Kubernetes, this is the Kubernetes name where Tailscale stores state. Defaults to tailscale. If you don't set TS_AUTHKEY, and TS_KUBE_SECRET contains a secret with an auth key field, Tailscale uses that key as the auth key.

TS_LOCAL_ADDR_PORT

Specifies the [<addr>]:<port> where Tailscale serves local metrics and health check HTTP endpoints if you enable them through TS_ENABLE_METRICS or TS_ENABLE_HEALTH_CHECK. Defaults to [::]:9002 on all available interfaces.

TS_OUTBOUND_HTTP_PROXY_LISTEN

Sets an address and port for the HTTP proxy. Tailscale passes this to tailscaled --outbound-http-proxy-listen=. For example, TS_OUTBOUND_HTTP_PROXY_LISTEN=:8080 creates an HTTP proxy on port 8080, which is equivalent to tailscaled --outbound-http-proxy-listen=:8080.

TS_ROUTES

Advertises subnet routes so other devices in your tailnet can reach networks accessible from this container. This is equivalent to tailscale set --advertise-routes=. For example, TS_ROUTES=192.168.1.0/24 lets other tailnet devices access your local network through this container.

To accept routes advertised by other nodes, use TS_EXTRA_ARGS to pass in --accept-routes.

TS_SERVE_CONFIG

Accepts a JSON file to programmatically configure Tailscale Serve and Tailscale Funnel functionality. Use tailscale serve status --json to export your current configuration in the correct format. If you bind mount this file using a Docker volume, you must mount it as a directory (not an individual file) for Tailscale to correctly detect configuration updates.

TS_SOCKET

The Unix socket path where the tailscaled LocalAPI socket lives. Defaults to /var/run/tailscale/tailscaled.sock. This is equivalent to tailscaled tailscale --socket=. You typically don't need to change this unless you have specific socket path requirements.

TS_SOCKS5_SERVER

Sets an address and port for the SOCKS5 proxy. Tailscale passes this to tailscaled --socks5-server=. For example, TS_SOCKS5_SERVER=:1055 creates a SOCKS5 proxy on port 1055, which is equivalent to tailscaled --socks5-server=:1055.

TS_STATE_DIR

Specifies where tailscaled stores its state. The TS_STATE_DIR volume ensures the container keeps its identity across restarts. Without it, each restart creates a new node in the admin console. This directory must persist across container restarts or your container will appear as a new node each time. Tailscale passes this to tailscaled --statedir=. For example, TS_STATE_DIR=/var/lib/tailscale stores state in that directory, which you should mount as a volume.

When running on Kubernetes, Tailscale stores state by default in the Kubernetes secret with name:tailscale. To store state on local disk instead, set TS_KUBE_SECRET="" and TS_STATE_DIR=/path/to/storage/dir.

TS_TAILNET_TARGET_FQDN

Proxies all incoming non-Tailscale traffic to the specified tailnet FQDN. Functions like TS_TAILNET_TARGET_IP but resolves a MagicDNS name instead of using a static IP. Not compatible with TS_USERSPACE mode. Cannot be used together with TS_TAILNET_TARGET_IP.

TS_TAILNET_TARGET_IP

Proxies all incoming non-Tailscale traffic to the specified destination IP within the tailnet. This sets up the container as an egress proxy, forwarding traffic from outside the tailnet to a Tailscale IP. Not compatible with TS_USERSPACE mode. Cannot be used together with TS_TAILNET_TARGET_FQDN.

TS_USERSPACE

Controls whether to use userspace networking instead of kernel networking. Enabled by default. This is equivalent to tailscaled --tun=userspace-networking.

Userspace networking works everywhere but has lower performance. Set TS_USERSPACE=false to use kernel networking for better speed, but you'll also need to add devices and cap_add sections to setup. Kernel networking provides better performance but requires /dev/net/tun and additional capabilities.

Extra arguments

The parameters above cover common Tailscale configurations, but Tailscale supports many additional CLI flags. Use the extra arguments parameters below to pass any flags that don't have dedicated parameters. For example, if you want to advertise your container as an exit node or enable SSH, you can pass those flags through TS_EXTRA_ARGS since they don't have specific TS_ parameters.

TS_EXTRA_ARGS

Pass other Tailscale CLI flags you want to use with the tailscale up command. For example, TS_EXTRA_ARGS=--advertise-exit-node --ssh.

TS_TAILSCALED_EXTRA_ARGS

Pass other Tailscale CLI flags you want to use with the tailscaled command. For example, TS_TAILSCALED_EXTRA_ARGS=--verbose=2.