tailhome

• Automatic Service discovery. tailhome lists reachable Services without API credentials and loads icons from dashboard-icons. New Services appear on the next refresh.
• One small binary, no host Tailscale needed. tailhome joins your tailnet through tsnet. The image is about 12 MB.
• Health checks inside the tailnet. A green dot means tailhome can reach the Service.

tailhome lists Tailscale Services, not machines. No Services yet? Define one in the admin console, or publish containers with DockTail.

tailhome is a launcher, not a dashboard: no widgets, no feeds. For those, use Homepage or Glance.

Prerequisites: at least one Tailscale Service, Tailscale 1.86 or later on your browsing devices, and MagicDNS plus HTTPS Certificates enabled in the DNS settings.

Create compose.yaml, then start tailhome:

services:
  tailhome:
    image: ghcr.io/mickey/tailhome:latest
    env_file: [{ path: .env, required: false }] # optional, see "Groups and descriptions"
    environment:
      TZ: Etc/UTC # your time zone, for the "updated" time
      TAILHOME_OVERRIDES: /config/overrides.yaml
    volumes:
      - tailhome-data:/data
      - ./config:/config:ro # put overrides.yaml here
    restart: unless-stopped

volumes:
  tailhome-data:

docker compose up -d
docker compose logs -f

Open the login link in the logs to add tailhome to your tailnet. When the logs show serving https://home.<tailnet>.ts.net, open http://home/ from a tailnet device. Keep the trailing slash so your browser doesn't search for "home".

tailhome joins under your account as a device named home:

• Disable key expiry on the Machines page. Untagged nodes expire after 180 days by default; the page shows the date until you disable it.
• Check the address in the logs. If a device or Service already uses home, Tailscale assigns another name, such as home-1.

To skip browser login, set TS_AUTHKEY to an auth key. A tagged key also avoids key expiry, but its tag needs a tagOwners entry.

go install github.com/mickey/tailhome@latest
tailhome

install -m 755 tailhome /usr/local/bin/
install -d /etc/tailhome
install -m 600 .env /etc/tailhome/env
install -m 644 contrib/tailhome.service /etc/systemd/system/
systemctl enable --now tailhome

• Tiles and "Other". A Service becomes a tile if it advertises port 443 or 80, has a url or web: true override, or answers HTTP on its first TCP port. Without a usable port (such as do-not-validate), tailhome tries HTTPS on 443, then HTTP on 80. Services needing HTTP detection stay under "Other" until they answer. Other Services, such as databases, stay there; click one to copy its hostname. Use web: false to keep a Service under "Other".
• Health.
  • Green: an HTTP response below 500, including redirects; a successful TCP connection for "Other" and non-HTTP links (ssh://, vnc://).
  • Red: the check failed. Hover over the dot for the reason. A tile that goes down stays in its group.
  • Grey: nothing to check, such as a Service with no TCP port.
• Refresh. tailhome reloads and checks Services every 5 minutes. Select refresh to check now, at most once every 10 seconds. If discovery or overrides fail, the page keeps the last list and shows the error.
• Notices. Without credentials, the page warns when the node's key will expire or when the node got another name, such as home-1. It rechecks both on every refresh.
• JSON. /api/services.json returns the same data as the page, notices included.

Default tile fields:

To change them, create config/overrides.yaml next to compose.yaml. All fields are optional; overrides.example.yaml lists them:

jellyfin:
  group: Media
  order: -1                 # lower sorts first; unset counts as 0, ties sort by label
grafana:
  label: Grafana
  icon: grafana             # a dashboard-icons name, or a full image URL
  url: https://grafana.example.ts.net/d/main
nas:
  url: vnc://nas.example.ts.net:5900   # also ssh, rdp, smb, ftp, sftp, telnet
postgres:
  hidden: true

Make the file readable by everyone (chmod 644). Without Docker, tailhome reads overrides.yaml from its working directory; set TAILHOME_OVERRIDES to use another path.

tailhome rereads overrides on every refresh, so edits need no restart. Keys are Service names, with or without svc:. Unknown fields fail the refresh: correct them and refresh again. tailhome ignores unmatched names and logs a warning; check their spelling.

DockTail and TSDProxy v3 (services: true) publish Docker containers as Services, so their tiles appear on their own. TSDProxy v2, tsbridge, and ScaleTail create devices instead; tailhome doesn't list them.

• Service names. Anyone who can open tailhome sees all listed Service names on the page and in /api/services.json, even Services they can't open. Restrict access to tailhome if needed.
• Icons. Browsers request icons from cdn.jsdelivr.net, revealing Service names to jsDelivr. Use icon overrides with your own URLs to avoid this.
• Logs. tailhome uploads diagnostic logs to Tailscale, like other Tailscale nodes. Set TS_NO_LOGS_NO_SUPPORT=true to stop uploads.

Report vulnerabilities as described in SECURITY.md. To contribute, see CONTRIBUTING.md. tailhome is released under the MIT license.