Skip to main content

Tailscale Integration

Private, encrypted access to Hrida.ai 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 Hrida.ai 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 Hrida.ai to the public internet. Perfect for personal setups, small teams, or accessing a home server from your phone or laptop on the go.

Prerequisites​

RequirementDetails
Hrida.aiRunning locally on port 8080 (default)
Tailscale accountFree for personal use at tailscale.com
Tailscale installedOn both the server running Hrida.ai and any client devices

Quick Start​

1. Install Tailscale​

Download from the Mac App Store or:

brew install tailscale

2. Connect the server​

On the machine running Hrida.ai:

sudo tailscale up

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

tailscale status

3. Access Hrida.ai​

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 Hrida.ai
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. Hrida.ai can trust this header as a single sign-on mechanism. Users on your tailnet are automatically logged in without needing a separate Hrida.ai password.

How it works​

  1. A Tailscale sidecar container runs alongside Hrida.ai
  2. Tailscale Serve proxies HTTPS traffic to Hrida.ai and injects identity headers
  3. Hrida.ai 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 Hrida.ai:

{
    "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 Hrida.ai, users could bypass the Serve proxy and reach Hrida.ai 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 Hrida.ai 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 Hrida.ai 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 Hrida.ai accessible to anyone on the internet. Make sure you have authentication configured in Hrida.ai before enabling it.

Quick Reference​

WhatCommand / Value
Connect to tailnetsudo tailscale up
Check hostnametailscale status
Serve over HTTPSsudo tailscale serve https / http://localhost:8080
Public access (Funnel)sudo tailscale funnel https / http://localhost:8080
Generate cert manuallysudo tailscale cert my-server.tail1234.ts.net
Admin consolelogin.tailscale.com/admin
Set CORS originCORS_ALLOW_ORIGIN=https://my-server.tail1234.ts.net
Trusted email headerHRIDAAI_AUTH_TRUSTED_EMAIL_HEADER=Tailscale-User-Login
Trusted name headerHRIDAAI_AUTH_TRUSTED_NAME_HEADER=Tailscale-User-Name
Hrida.ai is proprietary software of Zlabs Innovation. See the license for terms. © 2026 Zlabs Innovation.