Using Tailscale with Docker

Tailscale has a published Docker image that Tailscale manages and builds from source. It's available in Docker Hub and GitHub Packages. Watch the video below for a quickstart guide on using Docker with Tailscale.

Pull image

To pull the image, run:

docker pull tailscale/tailscale:latest

or

docker pull ghcr.io/tailscale/tailscale:latest

Supported tags

Containers are tagged based on the Tailscale versioning scheme.

• Use stable or latest to get the latest stable version.
  • v1.58.2, v1.58 to get a specific stable version.
• Use unstable to get the latest unstable version.
  • unstable-v1.59.37, unstable-v1.59.44 to get a specific unstable version.

Parameters

You can set additional parameters for use with the image. All configuration is optional.

TS_ACCEPT_DNS

Accept DNS configuration from the admin console. Not accepted by default.

TS_AUTH_ONCE

Attempt to log in only if not already logged in. False by default, to forcibly log in every time the container starts.

TS_AUTHKEY

An auth key used to authenticate the container. This is equivalent to what you'd pass to tailscale login --auth-key=.

It is also possible to use an OAuth client secret here but the associated tag must be provided using TS_EXTRA_ARGS=--advertise-tags=tag:ci.

To mark a containerized node as ephemeral append ?ephemeral=true to the auth key or OAuth client secret.

This parameter cannot be used together with TS_CLIENT_ID, TS_CLIENT_SECRET, TS_ID_TOKEN, or TS_AUDIENCE.

TS_CLIENT_ID

The OAuth client ID. Can be used alone (for example, when an ID token is auto-generated 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:, it is treated as a path to a file containing the client ID.

TS_CLIENT_SECRET

The OAuth client secret for generating auth keys. Must be used together with TS_CLIENT_ID for OAuth authentication.

If the value begins with file:, it is treated as a path to a file containing the secret.

This parameter cannot be used together with TS_ID_TOKEN or TS_AUDIENCE.

TS_DEST_IP

Proxy all incoming Tailscale traffic to the specified destination IP.

TS_HEALTHCHECK_ADDR_PORT

Deprecated. Use TS_ENABLE_HEALTH_CHECK (and optionally TS_LOCAL_ADDR_PORT) instead from 1.78.

TS_LOCAL_ADDR_PORT

Specifies the [<addr>]:<port> on which to serve local metrics and health check HTTP endpoints if enabled through TS_ENABLE_METRICS or TS_ENABLE_HEALTH_CHECK. Defaults to [::]:9002 on all available interfaces.

TS_ENABLE_HEALTH_CHECK

Set to true to enable an unauthenticated /healthz endpoint at the address specified by TS_LOCAL_ADDR_PORT.

The health check returns 200 OK if the node has at least one tailnet IP address, otherwise it returns 503.

TS_ENABLE_METRICS

Set to true to enable an unauthenticated /metrics endpoint at the address specified by TS_LOCAL_ADDR_PORT.

Refer to client metrics for more information about the metrics.

TS_HOSTNAME

Use the specified hostname for the node. This is equivalent to tailscale set --hostname=.

TS_ID_TOKEN

The ID token from the identity provider for workload identity federation. Must be used together with TS_CLIENT_ID.

If the value begins with file:, it is treated as a path to a file containing the token.

This parameter cannot be used together with TS_CLIENT_SECRET or TS_AUDIENCE.

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. Must be used together with TS_CLIENT_ID.

This parameter cannot be used together with TS_CLIENT_SECRET or TS_ID_TOKEN.

TS_KUBE_SECRET

If running in Kubernetes, the Kubernetes secret name where Tailscale state is stored. The default is tailscale.

If TS_AUTHKEY is not set, and TS_KUBE_SECRET contains a secret with an authkey field, that key is used as a Tailscale auth key.

TS_OUTBOUND_HTTP_PROXY_LISTEN

Set an address and port for the HTTP proxy. This will be passed to tailscaled --outbound-http-proxy-listen=. For example, to set the SOCKS5 proxy to port 1055, this is :1055, which is equivalent to tailscaled --outbound-http-proxy-listen=:1055.

TS_ROUTES

Advertise subnet routes. This is equivalent to tailscale set --advertise-routes=. To accept advertised routes, use TS_EXTRA_ARGS to pass in --accept-routes.

TS_SERVE_CONFIG

Accepts a JSON file to programmatically configure Serve and Funnel functionality. Use tailscale serve status --json to export your current configuration in the correct format.

If this file is bind mounted using a Docker volume, it must be done so as a directory and not an individual file for configuration updates to be correctly detected.

TS_SOCKET

Unix socket path used by the Tailscale binary, where the tailscaled LocalAPI socket is created. The default is /var/run/tailscale/tailscaled.sock. This is equivalent to tailscaled tailscale --socket=.

TS_SOCKS5_SERVER

Set an address and port for the SOCKS5 proxy. This will be passed to tailscaled --socks5-server=. For example, to set the SOCKS5 proxy to port 1055, this is :1055, which is equivalent to tailscaled --socks5-server=:1055.

TS_STATE_DIR

Directory where the state of tailscaled is stored. This needs to persist across container restarts. This will be passed to tailscaled --statedir=.

When running on Kubernetes, state is stored 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_USERSPACE

Enable userspace networking, instead of kernel networking. Enabled by default. This is equivalent to tailscaled --tun=userspace-networking.

Extra arguments

TS_EXTRA_ARGS

Any other flags to pass in to the Tailscale CLI in a tailscale up command.

TS_TAILSCALED_EXTRA_ARGS

Any other flags to pass in to tailscaled.

Code examples

Below is a complete Docker Compose code snippet using an OAuth client secret.

---
version: "3.7"
services:
  tailscale-nginx:
    image: tailscale/tailscale:latest
    hostname: tailscale-nginx
    environment:
      - TS_AUTHKEY=tskey-client-notAReal-OAuthClientSecret1Atawk
      - TS_EXTRA_ARGS=--advertise-tags=tag:container
      - TS_STATE_DIR=/var/lib/tailscale
      - TS_USERSPACE=false
    volumes:
      - ${PWD}/tailscale-nginx/state:/var/lib/tailscale
    devices:
      - /dev/net/tun:/dev/net/tun
    cap_add:
      - net_admin
    restart: unless-stopped
  nginx:
    image: nginx
    depends_on:
      - tailscale-nginx
    network_mode: service:tailscale-nginx

More examples can be found in tailscale-dev/docker-guide-code-examples.