Tailscale Sidecar

Run Zerobyte behind a Tailscale sidecar container so the web UI is accessible over your private tailnet without exposing ports to the public internet.

What is Tailscale?

Tailscale is a mesh VPN built on WireGuard. It connects devices and containers into a private network ("tailnet") without opening inbound ports on your router.

In this setup, Tailscale acts as a secure access layer in front of Zerobyte:

You reach Zerobyte using the node's tailnet IP or MagicDNS name
Access can be restricted using Tailscale ACLs and tags
No port forwarding or public exposure required

Prerequisites

Docker and Docker Compose
A Tailscale account and an auth key

Setup

This example uses a sidecar networking pattern where Zerobyte shares the Tailscale container's network namespace.

Create docker-compose.yml

services:
  tailscale:
    image: tailscale/tailscale:stable
    container_name: zerobyte-tailscale
    hostname: ${TS_HOSTNAME:-zerobyte}
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    environment:
      - TS_AUTHKEY=${TS_AUTHKEY}
      - TS_STATE_DIR=/var/lib/tailscale
      - TS_USERSPACE=${TS_USERSPACE:-false}
      - TS_EXTRA_ARGS=${TS_EXTRA_ARGS:-}
    volumes:
      - /var/lib/tailscale:/var/lib/tailscale
    # Remove this section to make Zerobyte only accessible via Tailscale
    ports:
      - "4096:4096"

  zerobyte:
    image: ghcr.io/nicotsx/zerobyte:latest
    container_name: zerobyte
    restart: unless-stopped
    # Uncomment if you need remote mounts (NFS/SMB/WebDAV):
    # cap_add:
    #   - SYS_ADMIN
    # devices:
    #   - /dev/fuse:/dev/fuse
    network_mode: service:tailscale
    depends_on:
      - tailscale
    environment:
      - TZ=${TZ:-UTC}
      - BASE_URL=http://${TS_HOSTNAME:-zerobyte}:4096
      - APP_SECRET=${APP_SECRET}
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/lib/zerobyte:/var/lib/zerobyte

Create .env file

TS_AUTHKEY=tskey-auth-xxxxx
TS_HOSTNAME=zerobyte
APP_SECRET=your-secret-here  # Generate with: openssl rand -hex 32
TZ=UTC
# Optional:
# TS_EXTRA_ARGS=--advertise-tags=tag:backup
# TS_USERSPACE=false

Start the stack

docker compose up -d

Verify in Tailscale

Confirm the node appears in your Tailscale admin console. Approve it if your policy requires approval.

Accessing Zerobyte

Once running, access Zerobyte over your tailnet:

By IP: http://<tailscale-ip>:4096
By MagicDNS: http://zerobyte:4096 (if MagicDNS is enabled)

To make Zerobyte accessible only via Tailscale, remove the ports: section from the tailscale service.

Kernel Mode vs Userspace Mode

Mode	Requirements	Best For
Kernel (default)	`/dev/net/tun`, `NET_ADMIN`	Linux servers, best performance
Userspace	No special devices	Docker Desktop, restricted hosts

To use userspace mode:

Set TS_USERSPACE=true in your .env
Remove the devices: /dev/net/tun section from the tailscale service

If you want Zerobyte to be reachable only via Tailscale (not from the local network), remove the ports: section from the tailscale service. Zerobyte will still be able to access the internet and your LAN for backup operations, but the UI will only be accessible over Tailscale.

Troubleshooting

TUN device error: Ensure /dev/net/tun exists on the host. Switch to userspace mode if it doesn't.
Node not appearing: Check the auth key is valid and not expired.
ACL issues: Set TS_EXTRA_ARGS=--advertise-tags=tag:backup and configure ACLs in Tailscale admin.

Verify the tailnet address:

docker exec zerobyte-tailscale tailscale status
docker exec zerobyte-tailscale tailscale ip -4