docktail README

The project's README from github.com/marvinvr/docktail. As one markdown file: README.md.

🍸 DockTail

Unleash your containers as Tailscale Services.

Latest release License: AGPL-3.0 Image on ghcr.io CI status

Add docktail labels to a Compose service, run docker compose up -d, and open https://myapp.your-tailnet.ts.net

Featured on Tailscale Community

DockTail watches Docker containers, reads docktail.* labels, and exposes matching containers as Tailscale Services. App containers do not need published Docker ports by default; DockTail proxies directly to their Docker network IPs.

Watch "I'm Running Docker Apps Differently Now" on Tailscale's YouTube channel
▶ I'm Running Docker Apps Differently Now: DockTail, featured on Tailscale's YouTube channel

Why DockTail?

DockTail uses native Tailscale Services, not per-container Tailscale devices.

DockTail TSDProxy ScaleTail tsbridge Plain Services
Native Tailscale Services ✅ ❌ ❌ ❌ ✅
Configured via Docker labels ✅ ✅ ❌ ✅ ❌
Apps do not consume separate Tailscale device slots ✅ ❌ ❌ ❌ ✅
No app port publishing ✅ ⚠️¹ ⚠️² ⚠️¹ ⚠️³
Automatic Docker reconciliation ✅ ✅ ❌ ✅ ❌
Low manual setup after install ✅ ✅ ⚠️⁴ ✅ ❌

Features

Quick Start

services:
  docktail:
    image: ghcr.io/marvinvr/docktail:latest
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /var/run/tailscale:/var/run/tailscale
    environment:
      # Optional but recommended. Enables automatic service creation.
      - TAILSCALE_OAUTH_CLIENT_ID=${TAILSCALE_OAUTH_CLIENT_ID}
      - TAILSCALE_OAUTH_CLIENT_SECRET=${TAILSCALE_OAUTH_CLIENT_SECRET}

  myapp:
    image: nginx:latest
    # No ports needed. DockTail proxies directly to the container IP.
    labels:
      - "docktail.service.enable=true"
      - "docktail.service.name=myapp"
      - "docktail.service.port=80"
docker compose up -d
curl http://myapp.your-tailnet.ts.net

This assumes the Docker host is connected to Tailscale and allowed to advertise services. See the full docs for host setup, sidecar setup, rootless Docker, OAuth permissions, ACLs, labels, Funnel, and examples. docker-compose.yaml is a ready-to-run version of this setup; for Podman, Synology, Unraid, TrueNAS, macOS, Windows, Swarm and Kubernetes see the platform guides, and for a read-only Docker socket proxy and dropped capabilities see Hardening.

For Docker secrets or other mounted secret files, set FILE__TAILSCALE_OAUTH_CLIENT_ID / FILE__TAILSCALE_OAUTH_CLIENT_SECRET or TAILSCALE_OAUTH_CLIENT_ID_FILE / TAILSCALE_OAUTH_CLIENT_SECRET_FILE to the mounted file paths instead of putting the values directly in the environment.

Common Examples

Expose an app with Tailscale HTTPS:

labels:
  - "docktail.service.enable=true"
  - "docktail.service.name=api"
  - "docktail.service.port=3000"
  - "docktail.service.service-port=443"

Expose a database over TCP:

labels:
  - "docktail.service.enable=true"
  - "docktail.service.name=db"
  - "docktail.service.port=5432"
  - "docktail.service.protocol=tcp"
  - "docktail.service.service-port=5432"

Preserve the tailnet client IP on a TCP reverse proxy:

labels:
  - "docktail.service.enable=true"
  - "docktail.service.name=traefik"
  - "docktail.service.port=443"
  - "docktail.service.protocol=tcp"
  - "docktail.service.service-port=443"
  - "docktail.service.proxy-protocol=2"

Expose a service publicly with Tailscale Funnel:

labels:
  - "docktail.funnel.enable=true"
  - "docktail.funnel.port=3000"
  - "docktail.funnel.funnel-port=8443"

Mount an HTTP(S) Funnel at a path:

labels:
  - "docktail.funnel.enable=true"
  - "docktail.funnel.port=3000"
  - "docktail.funnel.path=/webhook"

DockTail Cloud (optional)

Once you run DockTail on more than one machine, "is it still up?" gets tedious. DockTail Cloud is a hosted dashboard for that — and because it already has the Docker and Tailscale context, it tells you which kind of broken you're looking at:

● down · OOM-killed                   →  the container was killed for running out of memory
● local up · awaiting approval        →  the app is fine, the exposure isn't
● host offline · heartbeat missing    →  the box stopped reporting

It rides along with the agent you already run — no second binary. Set one environment variable and the same container starts reporting:

environment:
  - DOCKTAIL_CLOUD_KEY=${DOCKTAIL_CLOUD_KEY}   # from cloud.docktail.org

Without the key the module is completely inert: no connection is opened and DockTail behaves exactly as before. The link is outbound-only and metadata-only — the protocol has no exec, deploy, or shell message types, which you can verify in cloud/.

DockTail Cloud is a paid service (plans and pricing); Homelab and Team start with a 30-day free trial. Your AI agent can investigate incidents through its MCP server and API. docker-compose.cloud.yaml is a complete example.

Explore DockTail Cloud · open the dashboard · agent setup

Documentation

The canonical documentation source lives in docs/. The site at docktail.org is built from a separate repository, which pins this one as a submodule and renders those Markdown files with tools/docsgen at build time.

Build From Source

go build -o docktail .
docker build -t docktail:latest .

The image is published for linux/amd64, linux/arm64 and linux/arm/v7, and releases newer than 1.8.3 carry static Linux binaries for the same platforms; see Platforms And Release Binaries.

Star History

Star History Chart

License

AGPL v3


By @marvinvr

docktail (marvinvr/docktail)

Searching Database…

What is this?DockTail watches Docker containers, reads docktail labels, and exposes matching containers as Tailscale Services. Apps do not need published Docker ports by default because DockTail proxies to their Docker network IPs.
Is it a Tailscale device per container, or something else?Neither. It uses native Tailscale Services instead of one Tailscale device per container, so your apps do not consume separate device slots.
How do I get it running?Start from the ready-to-run docker-compose.yaml, after connecting the Docker host to Tailscale and allowing it to advertise services. Then add docktail labels to the containers you want exposed.
What do I need before I start?A Docker host connected to Tailscale and allowed to advertise services, plus OAuth client credentials or an API key so DockTail can create Tailscale services automatically.
Are there any pitfalls?Tailscale Funnel exposes a service to the public internet, so enable it on purpose. Cleanup of unused Tailscale service definitions is opt-in.
Does it work on Synology, Unraid, TrueNAS or Kubernetes?Yes, platform guides exist for Podman, Synology, Unraid, TrueNAS, macOS, Windows, Swarm and Kubernetes, and there is a hardening guide for a read-only Docker socket proxy.
Does it send my data anywhere?Not by default. DockTail Cloud reporting is optional and turned on only by setting one environment variable. Without the key, no connection is opened, and the link is outbound-only and metadata-only.
Is it free to use?The core project is licensed under AGPL v3 and is free. DockTail Cloud is a separate paid service, and its Homelab and Team plans start with a 30-day free trial.
What is DockTail Cloud?An optional hosted dashboard for monitoring several machines running DockTail. It reuses the same container, and your AI agent can investigate incidents through its MCP server and API.
Why not just use plain Tailscale Services?Plain Tailscale Services need manual configuration. DockTail reads Docker labels and reconciles automatically when containers restart or their IPs change.
Can I expose a database over TCP?Yes. HTTP, HTTPS, TCP and TLS-terminated TCP are supported, and optional PROXY protocol lets TCP backends see the real tailnet client IP.
Creator
marvinvr
Size
5.6 MB
Stars
1.6K
Age
1y
Commits · 90 Days