docktail

🍸 DockTail

Unleash your containers as Tailscale Services.

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.

Why DockTail?

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

• ¹ Depends on proxy and Docker network setup.
• ² Depends on the sidecar template and app network setup.
• ³ You configure how the service host reaches the backend yourself.
• ⁴ ScaleTail is template-based, so each app usually starts from its own Compose recipe.

Features

• Automatic Docker container discovery through labels.
• Automatic Tailscale service creation with OAuth or API key credentials.
• HTTP, HTTPS, TCP, and TLS-terminated TCP support.
• Optional PROXY protocol on TCP services so backends see the tailnet client IP.
• Tailscale HTTPS with automatic certificates.
• Tailscale Funnel for public internet access.
• Multiple Tailscale services from one container.
• Automatic reconciliation when containers restart or IPs change.
• Optional cleanup of unused Tailscale service definitions (opt-in, safe with multiple instances).
• Stateless Docker container runtime.
• Optional DockTail Cloud reporting — multi-host monitoring, opt-in via one env var.

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.

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                   →  Docker reported an OOM kill
● 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/.

Explore DockTail Cloud · open the dashboard · agent setup

Documentation

• Human docs: https://docktail.org/docs/

• Markdown docs: https://docktail.org/docs.md

• LLM guide: https://docktail.org/llms.txt

• Full LLM docs: https://docktail.org/llms-full.txt

• DockTail Cloud overview: https://docktail.org/cloud/

• Optional Cloud agent setup: docs/06-cloud.md

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 .

Links

• Tailscale Services Documentation
• Tailscale Funnel Documentation
• Tailscale Service Configuration Reference
• Docker SDK for Go

Star History

License

AGPL v3

By @marvinvr