Tailscale Integration
Relevant source files
The following files were used as context for generating this wiki page:
Nyansa provides a secure, private access mode using Tailscale to connect to the self-hosted stack without exposing public ports. This integration creates a private WireGuard-based network (tailnet) node that handles encrypted traffic directly to the internal Docker services.
The Tailscale profile ensures that the nyansa-caddy-tailscale reverse proxy and internal services remain unreachable from the public internet. Access is restricted to authenticated devices within the user's Tailscale network.
Sources: README.md:23-25, docker-compose.yml:333-335
Architecture and Connectivity
The Tailscale integration utilizes two primary containers: nyansa-tailscale and nyansa-caddy-tailscale. The nyansa-tailscale service acts as the network gateway, while the Caddy service shares its network namespace to serve internal components over the tailnet.
The diagram shows how external traffic enters via the Tailscale node and is routed to internal services through a dedicated Caddy instance.
Sources: README.md:46-64, docker-compose.yml:347-380
Tailscale Service (nyansa-tailscale)
The nyansa-tailscale service runs the official Tailscale image and functions as a node on the private network. It requires a TS_AUTHKEY for initial registration and persists its identity in the nyansa_tailscale_state volume.
- Network isolation: The container uses the
NET_ADMINcapability and/dev/net/tundevice to manage the VPN tunnel. - Health checks: It exposes a local health endpoint at
127.0.0.1:9002/healthz.
Sources: docker-compose.yml:347-372
Caddy Tailscale Proxy (nyansa-caddy-tailscale)
This service operates in the network namespace of the nyansa-tailscale container. It serves the Open WebUI and n8n editor specifically for the tailnet.
- Certificate management: Caddy communicates with the
tailscaledsocket to obtain valid HTTPS certificates for the*.ts.netdomain. - Service mapping: It routes traffic to internal services using the
nyansainternal Docker network names.
Sources: README.md:23-25, docker-compose.yml:374-394
Configuration Parameters
Tailscale integration is activated by selecting the tailscale profile during deployment. The following environment variables control the behavior of the integration:
| Variable | Description | Default Value |
|---|---|---|
TS_AUTHKEY | Tailscale auth key for node registration | (Empty) |
TS_HOSTNAME | Hostname of the node within the tailnet | nyansa |
TS_TAILNET | The name of the Tailscale network | (Empty) |
TAILSCALE_VERSION | Version of the Tailscale Docker image | v1.102.5 |
Sources: docker-compose.yml:336-343, docker-compose.yml:352-355
Security and Exposure
When the Tailscale profile is active, Nyansa publishes no ports on the host's public IP addresses. This eliminates the risk of brute-force attacks on the n8n login or Open WebUI from the public internet.
- Port Exposure: The
scripts/check-exposure.shscript validates that no ports are mapped to0.0.0.0when the Tailscale profile is used. - Authentication: Access is protected by Tailscale's built-in device authentication and encryption.
- Network Namespace:
nyansa-caddy-tailscaleusesnetwork_mode: service:nyansa-tailscaleto inherit the VPN interface without exposing itself to the standard Docker bridge.
Sources: README.md:88-90, docker-compose.yml:378, scripts/check-exposure.sh:1-10
Service Initialization Flow
The following sequence describes how the Tailscale integration establishes connectivity:
This sequence illustrates the dependency of the Caddy proxy on the Tailscale node for networking and certificate issuance.
Sources: docker-compose.yml:350-394
Nyansa's Tailscale integration provides a robust "zero-exposure" deployment option. By combining the Tailscale sidecar pattern with Caddy, the system ensures that sensitive RAG and workflow tools are only accessible via a private, encrypted tunnel.