# marvinvr/docktail architecture

> Architecture diagram of the GitHub repository marvinvr/docktail, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marvinvr/docktail
- Repository: https://github.com/marvinvr/docktail

## Overview

DockTail is an agent that discovers Docker containers configured with labels and exposes them as native Tailscale Services. Its main loop reconciles desired container services against Tailscale; Tailscale Serve then proxies traffic to container backends. A separate, opt-in Cloud branch reports host and container state, while Funnel supports public exposure. The graph follows the README and sampled entry-point, reconciliation, Docker, Tailscale, and Cloud code; unsampled subsystem links are included only where documented, and other internal Cloud relationships are left out where call sites were not shown.

Main entry points: [`cloud/collector.go`](https://github.com/marvinvr/docktail/blob/main/cloud/collector.go) (Cloud collector), [`main.go`](https://github.com/marvinvr/docktail/blob/main/main.go) (Agent startup), [`tailscale/client.go`](https://github.com/marvinvr/docktail/blob/main/tailscale/client.go) (Tailscale client), [`docker/client.go`](https://github.com/marvinvr/docktail/blob/main/docker/client.go) (Docker discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent and reconciliation"]
  node_agent_main["Agent startup<br/>[main.go]"]
  node_docker_client["Docker discovery<br/>[client.go]"]
  node_reconciler["Service reconciliation<br/>[reconciler.go]"]
  node_health["Health reporting<br/>[health.go]"]
end

subgraph group_exposure["Tailscale exposure"]
  node_ts_client["Tailscale client<br/>[client.go]"]
  node_ts_serve["Serve services<br/>[service.go]"]
  node_funnel["Funnel exposure<br/>[funnel.go]"]
end

subgraph group_cloud["Cloud reporting"]
  node_cloud_collector["Cloud collector<br/>[collector.go]"]
  node_cloud_docker["Cloud inventory<br/>[cloud.go]"]
  node_cloud_checks["Service checks<br/>[checks.go]"]
  node_cloud_tailnet["Tailnet probes<br/>[tailnet.go]"]
  node_host_metrics["Host metrics<br/>[hostmetrics.go]"]
  node_host_fs["Host filesystems<br/>[hostfs_linux.go]"]
  node_cloud_ws["Cloud connection<br/>[wsclient.go]"]
  node_cloud_proto["Cloud protocol<br/>[messages.go]"]
  node_cloud_spool[("Offline spool<br/>[spool.go]")]
end

subgraph group_shared["Shared runtime"]
  node_types["Service model<br/>[types.go]"]
end

node_operator(("Operator"))
node_docker_engine[("Docker Engine")]
node_tailnet_user(("Tailnet client"))
node_tailscaled["tailscaled"]
node_ts_control["Tailscale control plane"]
node_cloud_service["DockTail Cloud"]

node_operator -->|"configures"| node_agent_main
node_agent_main -->|"creates"| node_docker_client
node_agent_main -->|"creates"| node_ts_client
node_agent_main -->|"runs"| node_reconciler
node_agent_main -->|"starts optionally"| node_cloud_collector
node_agent_main -->|"tracks status"| node_health
node_docker_engine -->|"provides containers"| node_docker_client
node_operator -->|"labels containers"| node_docker_engine
node_reconciler -->|"discovers services"| node_docker_client
node_reconciler -->|"reconciles services"| node_ts_client
node_docker_client -->|"builds service models"| node_types
node_ts_client -->|"reconciles Serve"| node_ts_serve
node_ts_client -->|"manages definitions"| node_ts_control
node_ts_client -.->|"reconciles funnels"| node_funnel
node_ts_serve -->|"configures proxy"| node_tailscaled
node_tailscaled -->|"proxies traffic"| node_docker_engine
node_tailnet_user -->|"requests service"| node_tailscaled
node_funnel -->|"enables public access"| node_tailscaled
node_cloud_collector -->|"reads inventory"| node_cloud_docker
node_cloud_collector -.->|"sends reports"| node_cloud_ws
node_cloud_collector -->|"encodes reports"| node_cloud_proto
node_cloud_ws -->|"reports outbound"| node_cloud_service
node_cloud_service -.->|"requests probes"| node_cloud_collector
node_cloud_collector -.->|"checks control state"| node_cloud_tailnet
node_cloud_collector -.->|"runs checks"| node_cloud_checks
node_cloud_collector -.->|"samples host"| node_host_metrics
node_host_metrics -.->|"reads filesystems"| node_host_fs
node_cloud_collector -.->|"buffers offline"| node_cloud_spool
node_cloud_collector -->|"maps service data"| node_types

click node_agent_main "https://github.com/marvinvr/docktail/blob/main/main.go"
click node_docker_client "https://github.com/marvinvr/docktail/blob/main/docker/client.go"
click node_reconciler "https://github.com/marvinvr/docktail/blob/main/reconciler/reconciler.go"
click node_health "https://github.com/marvinvr/docktail/blob/main/health/health.go"
click node_types "https://github.com/marvinvr/docktail/blob/main/types/types.go"
click node_ts_client "https://github.com/marvinvr/docktail/blob/main/tailscale/client.go"
click node_ts_serve "https://github.com/marvinvr/docktail/blob/main/tailscale/service.go"
click node_funnel "https://github.com/marvinvr/docktail/blob/main/tailscale/funnel.go"
click node_cloud_collector "https://github.com/marvinvr/docktail/blob/main/cloud/collector.go"
click node_cloud_docker "https://github.com/marvinvr/docktail/blob/main/docker/cloud.go"
click node_cloud_checks "https://github.com/marvinvr/docktail/blob/main/cloud/checks.go"
click node_cloud_tailnet "https://github.com/marvinvr/docktail/blob/main/cloud/tailnet.go"
click node_host_metrics "https://github.com/marvinvr/docktail/blob/main/cloud/hostmetrics.go"
click node_host_fs "https://github.com/marvinvr/docktail/blob/main/cloud/hostfs_linux.go"
click node_cloud_ws "https://github.com/marvinvr/docktail/blob/main/cloud/wsclient.go"
click node_cloud_proto "https://github.com/marvinvr/docktail/blob/main/cloud/proto/messages.go"
click node_cloud_spool "https://github.com/marvinvr/docktail/blob/main/cloud/spool.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent_main,node_docker_client,node_reconciler,node_health,node_tailnet_user toneBlue
class node_ts_client,node_ts_serve,node_funnel,node_docker_engine toneAmber
class node_cloud_collector,node_cloud_docker,node_cloud_checks,node_cloud_tailnet,node_host_metrics,node_host_fs,node_cloud_ws,node_cloud_proto,node_cloud_spool toneMint
class node_types toneRose
class node_operator,node_tailscaled,node_ts_control,node_cloud_service toneIndigo
```

## Components

### Agent and reconciliation

- [Agent startup](https://github.com/marvinvr/docktail/blob/main/main.go): `main.go`
- [Docker discovery](https://github.com/marvinvr/docktail/blob/main/docker/client.go): `docker/client.go`
- [Service reconciliation](https://github.com/marvinvr/docktail/blob/main/reconciler/reconciler.go): `reconciler/reconciler.go`
- [Health reporting](https://github.com/marvinvr/docktail/blob/main/health/health.go): `health/health.go`

### Tailscale exposure

- [Tailscale client](https://github.com/marvinvr/docktail/blob/main/tailscale/client.go): `tailscale/client.go`
- [Serve services](https://github.com/marvinvr/docktail/blob/main/tailscale/service.go): `tailscale/service.go`
- [Funnel exposure](https://github.com/marvinvr/docktail/blob/main/tailscale/funnel.go): `tailscale/funnel.go`

### Cloud reporting

- [Cloud collector](https://github.com/marvinvr/docktail/blob/main/cloud/collector.go): `cloud/collector.go`
- [Cloud inventory](https://github.com/marvinvr/docktail/blob/main/docker/cloud.go): `docker/cloud.go`
- [Service checks](https://github.com/marvinvr/docktail/blob/main/cloud/checks.go): `cloud/checks.go`
- [Tailnet probes](https://github.com/marvinvr/docktail/blob/main/cloud/tailnet.go): `cloud/tailnet.go`
- [Host metrics](https://github.com/marvinvr/docktail/blob/main/cloud/hostmetrics.go): `cloud/hostmetrics.go`
- [Host filesystems](https://github.com/marvinvr/docktail/blob/main/cloud/hostfs_linux.go): `cloud/hostfs_linux.go`
- [Cloud connection](https://github.com/marvinvr/docktail/blob/main/cloud/wsclient.go): `cloud/wsclient.go`
- [Cloud protocol](https://github.com/marvinvr/docktail/blob/main/cloud/proto/messages.go): `cloud/proto/messages.go`
- [Offline spool](https://github.com/marvinvr/docktail/blob/main/cloud/spool.go): `cloud/spool.go`

### Shared runtime

- [Service model](https://github.com/marvinvr/docktail/blob/main/types/types.go): `types/types.go`

### Other components

- **Operator**
- **Docker Engine**
- **Tailnet client**
- **tailscaled**
- **Tailscale control plane**
- **DockTail Cloud**

## Connections

- Operator → Agent startup: configures (evidence: `README.md`)
- Agent startup → Docker discovery: creates (evidence: `main.go`)
- Agent startup → Tailscale client: creates (evidence: `main.go`)
- Agent startup → Service reconciliation: runs (evidence: `main.go`)
- Agent startup → Cloud collector: starts optionally (evidence: `main.go`)
- Agent startup → Health reporting: tracks status (evidence: `main.go`)
- Docker Engine → Docker discovery: provides containers (evidence: `README.md`)
- Operator → Docker Engine: labels containers (evidence: `README.md`)
- Service reconciliation → Docker discovery: discovers services (evidence: `reconciler/reconciler.go`)
- Service reconciliation → Tailscale client: reconciles services (evidence: `reconciler/reconciler.go`)
- Docker discovery → Service model: builds service models (evidence: `docker/client.go`)
- Tailscale client → Serve services: reconciles Serve (evidence: `tailscale/client.go`)
- Tailscale client → Tailscale control plane: manages definitions (evidence: `tailscale/client.go`)
- Tailscale client → Funnel exposure: reconciles funnels
- Serve services → tailscaled: configures proxy (evidence: `README.md`)
- tailscaled → Docker Engine: proxies traffic (evidence: `README.md`)
- Tailnet client → tailscaled: requests service (evidence: `README.md`)
- Funnel exposure → tailscaled: enables public access (evidence: `README.md`)
- Cloud collector → Cloud inventory: reads inventory (evidence: `cloud/collector.go`)
- Cloud collector → Cloud connection: sends reports
- Cloud collector → Cloud protocol: encodes reports (evidence: `cloud/collector.go`)
- Cloud connection → DockTail Cloud: reports outbound (evidence: `README.md`)
- DockTail Cloud → Cloud collector: requests probes
- Cloud collector → Tailnet probes: checks control state
- Cloud collector → Service checks: runs checks
- Cloud collector → Host metrics: samples host
- Host metrics → Host filesystems: reads filesystems
- Cloud collector → Offline spool: buffers offline
- Cloud collector → Service model: maps service data (evidence: `cloud/collector.go`)
