Tailscale Integration

Private, encrypted access to HridaAI from any device. No ports to open, no certificates to manage.

Tailscale creates a WireGuard-based mesh VPN (a "tailnet") between your devices. Every device gets a stable hostname like my-server.tail1234.ts.net, and Tailscale can provision trusted HTTPS certificates automatically. Your HridaAI instance stays completely private, accessible only to devices on your tailnet.

When to use Tailscale

Tailscale is ideal when you want private, authenticated access across devices without exposing HridaAI to the public internet. Perfect for personal setups, small teams, or accessing a home server from your phone or laptop on the go.

---

Prerequisites

Requirement	Details
HridaAI	Running locally on port 8080 (default)
Tailscale account	Free for personal use at tailscale.com
Tailscale installed	On both the server running HridaAI and any client devices

---

Quick Start

1. Install Tailscale

macOS

Download from the Mac App Store or:

brew install tailscale

Linux

curl -fsSL https://tailscale.com/install.sh | sh

Windows

Download from tailscale.com/download.

2. Connect the server

On the machine running HridaAI:

sudo tailscale up

Your machine gets a tailnet hostname like my-server.tail1234.ts.net. Find it with:

tailscale status

3. Access HridaAI

From any device on the same tailnet, open:

http://my-server.tail1234.ts.net:8080

This connection is already encrypted end-to-end by WireGuard. For browser features that require HTTPS (like Voice Calls), continue to the next section.

---

HTTPS with Tailscale

Tailscale can provision trusted Let's Encrypt certificates for your tailnet hostname, no reverse proxy required.

For the full step-by-step HTTPS setup (certificate generation, tailscale serve, configuring HRIDAAI_URL), see the dedicated reference guide:

👉 HTTPS using Tailscale

The short version:

# Proxy HTTPS traffic directly to HridaAI
sudo tailscale serve https / http://localhost:8080

Your instance is now available at https://my-server.tail1234.ts.net with a valid TLS certificate.

---

Authentication via Tailscale (SSO)

Tailscale Serve can act as an authenticating reverse proxy. When a request passes through tailscale serve, Tailscale automatically sets the Tailscale-User-Login header with the email address of the authenticated user. HridaAI can trust this header as a single sign-on mechanism. Users on your tailnet are automatically logged in without needing a separate HridaAI password.

How it works

1. A Tailscale sidecar container runs alongside HridaAI
2. Tailscale Serve proxies HTTPS traffic to HridaAI and injects identity headers
3. HridaAI reads Tailscale-User-Login and Tailscale-User-Name to identify the user
4. Users are auto-registered and logged in on first visit

Docker Compose Setup

Create a tailscale/serve.json file that configures Tailscale Serve to proxy to HridaAI:

{
    "TCP": {
        "443": {
            "HTTPS": true
        }
    },
    "Web": {
        "${TS_CERT_DOMAIN}:443": {
            "Handlers": {
                "/": {
                    "Proxy": "http://hrida-ai:8080"
                }
            }
        }
    }
}

Then set up the Docker Compose file with a Tailscale sidecar:

---
services:
  hrida-ai:
    image: ghcr.io/hrida-ai/hrida-ai-studio:main
    volumes:
      - hrida-ai:/app/backend/data
    environment:
      - HRIDAAI_AUTH_TRUSTED_EMAIL_HEADER=Tailscale-User-Login
      - HRIDAAI_AUTH_TRUSTED_NAME_HEADER=Tailscale-User-Name
    restart: unless-stopped
  tailscale:
    image: tailscale/tailscale:latest
    environment:
      - TS_AUTH_ONCE=true
      - TS_AUTHKEY=${TS_AUTHKEY}
      - TS_EXTRA_ARGS=--advertise-tags=tag:hrida-ai
      - TS_SERVE_CONFIG=/config/serve.json
      - TS_STATE_DIR=/var/lib/tailscale
      - TS_HOSTNAME=hrida-ai
    volumes:
      - tailscale:/var/lib/tailscale
      - ./tailscale:/config
      - /dev/net/tun:/dev/net/tun
    cap_add:
      - net_admin
      - sys_module
    restart: unless-stopped

volumes:
  hrida-ai: {}
  tailscale: {}

You will need to create an OAuth client with device write permission in the Tailscale admin console and pass the key as TS_AUTHKEY.

Your instance will be reachable at https://hrida-ai.TAILNET_NAME.ts.net.

Restrict direct access with ACLs

If you run Tailscale in the same network context as HridaAI, users could bypass the Serve proxy and reach HridaAI directly, skipping the trusted header authentication. Use Tailscale ACLs to restrict access to only port 443.

For more details on trusted header authentication, see the SSO documentation.

---

Tailscale Funnel (Optional Public Access)

If you want to share HridaAI publicly without requiring Tailscale on the client, Tailscale Funnel exposes your tailscale serve endpoint to the internet:

sudo tailscale funnel https / http://localhost:8080

Your HridaAI is now publicly accessible at https://my-server.tail1234.ts.net with a valid TLS certificate. Funnel routes traffic through Tailscale's infrastructure, similar to Cloudflare Tunnel.

warning

Funnel makes your HridaAI accessible to anyone on the internet. Make sure you have authentication configured in HridaAI before enabling it.

---

Quick Reference

What	Command / Value
Connect to tailnet	sudo tailscale up
Check hostname	tailscale status
Serve over HTTPS	sudo tailscale serve https / http://localhost:8080
Public access (Funnel)	sudo tailscale funnel https / http://localhost:8080
Generate cert manually	sudo tailscale cert my-server.tail1234.ts.net
Admin console	login.tailscale.com/admin
Set CORS origin	CORS_ALLOW_ORIGIN=https://my-server.tail1234.ts.net
Trusted email header	HRIDAAI_AUTH_TRUSTED_EMAIL_HEADER=Tailscale-User-Login
Trusted name header	HRIDAAI_AUTH_TRUSTED_NAME_HEADER=Tailscale-User-Name

---

Related Pages

• HTTPS using Tailscale - focused HTTPS/TLS reference
• SSO (Trusted Header) - generic trusted header configuration
• HridaAI Teams - overview of all sharing approaches