tslink

module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 13, 2026 License: MIT

README

tslink is a Docker network plugin that makes each container a node in your Tailscale tailnet, with its own identity, name and address.

Features

  • One node for each container. Each container has its own identity and ACL tags, separate from the host.
  • Tailscale Serve and Services. Labels serve a container over HTTPS, or make it a backend of a Tailscale Service.
  • Docker Swarm. Each stack gets its own tags, from one cluster credential or from an OAuth client for each stack.
  • Updates without downtime. tslink drains a Service backend before its container stops.
  • Self-healing. tslink restarts tailscaled, logs nodes in again and removes the nodes of lost containers.
┌────────────────────────────────────────────────────────────┐
│ Host                                                       │
│  ┌──────────────────────────────────────────┐              │
│  │ Container (tailnet address 100.x.y.z)    │              │
│  │ App ─► tailscale0 ─► tailscaled ─► veth ─┼─► NAT ───────┼─► Tailnet
│  │ App ─► eth0 ─────────────────────────────┼─► Docker ────┼─► Internet
│  └──────────────────────────────────────────┘              │
└────────────────────────────────────────────────────────────┘

The container reaches the tailnet only as its own node, never through the Tailscale of the host.

Requirements

  • Linux with Docker Engine, or Docker in a Linux VM, for example OrbStack or Docker Desktop.
  • A Tailscale tailnet.
  • An auth key or an OAuth client secret.

Quick start

Replace amd64 with arm64 on an ARM host, and tskey-auth-… with your auth key:

sudo install -d -m 0755 /var/lib/docker-plugins/tailscale
docker plugin install --alias tslink --grant-all-permissions ghcr.io/matchory/tslink:latest-amd64
docker network create --driver tslink:latest --opt tslink.authkey=tskey-auth-… my-tailnet
docker run -d --network my-tailnet --label tslink.hostname=web nginx:alpine

The container is now the node web in your tailnet. For a complete example with HTTPS, see Getting started.

Documentation

Section Content
Getting started A tutorial for the first container
Guides Install, provision, deploy on Swarm, expose services, update, monitor and troubleshoot
Reference Network options, container labels, plugin settings, credentials, files and tslink diag
Explanation Architecture, security model, HTTPS certificates and limitations

Contributing

See CONTRIBUTING.md. Report vulnerabilities as described in SECURITY.md. The changes are in CHANGELOG.md.

License

MIT, see LICENSE. tslink is a fork of aaomidi/tslink by Amir Omidi.

The plugin image contains Tailscale (BSD 3-Clause) and Go modules under their own licenses. Their notices are in the image under /usr/share/licenses.

Directories

Path Synopsis
cmd
tslink command
Command tslink is a Docker network plugin that puts each container on a tailnet as its own Tailscale node.
Command tslink is a Docker network plugin that puts each container on a tailnet as its own Tailscale node.
internal
leakcheck
Package leakcheck fails a package's tests if they leak goroutines.
Package leakcheck fails a package's tests if they leak goroutines.
secmodel
Package secmodel checks the security model in SECURITY.md against the tests: every guarantee it publishes must be guarded by a test, a model or a probe, or be marked as checked by hand.
Package secmodel checks the security model in SECURITY.md against the tests: every guarantee it publishes must be guarded by a test, a model or a probe, or be marked as checked by hand.
pkg
core
Package core holds the endpoint and network logic: the per-container Tailscale lifecycle, its state directories and their garbage collection.
Package core holds the endpoint and network logic: the per-container Tailscale lifecycle, its state directories and their garbage collection.
diag
Package diag reports the state of the plugin's endpoints for debugging.
Package diag reports the state of the plugin's endpoints for debugging.
docker
Package docker implements the Docker network driver API and watches Docker events for container starts and stops.
Package docker implements the Docker network driver API and watches Docker events for container starts and stops.
logger
Package logger provides the plugin's structured logging and rotating log files.
Package logger provides the plugin's structured logging and rotating log files.
netutil
Package netutil sets up the Linux networking for endpoints: veth pairs, routing and NAT.
Package netutil sets up the Linux networking for endpoints: veth pairs, routing and NAT.
preflight
Package preflight checks, on the host it runs on, the environment properties that SECURITY.md's guarantees rely on.
Package preflight checks, on the host it runs on, the environment properties that SECURITY.md's guarantees rely on.
tailscale
Package tailscale runs and supervises tailscaled for each endpoint.
Package tailscale runs and supervises tailscaled for each endpoint.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL