Self-hosting

Tentacle TV runs one server in front of your Jellyfin. It holds accounts, invites, plugins and pairing; Jellyfin keeps holding your media.

Current server release

Self-Host with Docker

Recommended

The fastest way to get Tentacle TV running. Copy, paste, done.

Includes MariaDB + Tentacle TV in a single stack:

services:
  db:
    image: mariadb:11
    container_name: tentacle-db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: tentacle_db
      MYSQL_USER: tentacle_user
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - tentacle-db-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5

  web:
    image: ghcr.io/knaox/tentacle-tv:latest
    container_name: tentacle-tv
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      DATABASE_URL: mysql://tentacle_user:${MYSQL_PASSWORD}@db:3306/tentacle_db
      JWT_SECRET: ${JWT_SECRET}
      PORT: "3000"
      HOST: "0.0.0.0"
    volumes:
      - tentacle-data:/app/apps/backend/data
    ports:
      - "3000:3000"

volumes:
  tentacle-db-data:
  tentacle-data:
docker compose up -d

Already have a MariaDB/MySQL instance? Use this minimal config:

services:
  web:
    image: ghcr.io/knaox/tentacle-tv:latest
    container_name: tentacle-tv
    restart: unless-stopped
    environment:
      JWT_SECRET: ${JWT_SECRET}
      PORT: "3000"
      HOST: "0.0.0.0"
    volumes:
      - tentacle-data:/app/apps/backend/data
    ports:
      - "3000:3000"

volumes:
  tentacle-data:
docker compose -f docker-compose.external.yml up -d
First launch: Open http://your-server:3000 — the setup wizard guides you through database, Jellyfin connection, and admin account creation.

Configuration

VariableDescriptionDefault
DATABASE_URLMariaDB connection string
JWT_SECRETSecret key for token signing
PORTServer listening port3000
HOSTServer bind address0.0.0.0
RATE_LIMITMax requests/min per IP1000

Jellyfin URL and API key are configured through the web setup wizard and stored in the database.

Architecture

Tentacle Backend /api/*

Auth, invites, tickets, config, pairing, plugins

Jellyfin Proxy /api/jellyfin/*

Streaming, media browsing, user data via backend proxy

LayerTechnology
WebReact 19, Vite 6, Tailwind CSS, Framer Motion
DesktopElectron (Windows, macOS) · Tauri v2 (Linux), native mpv player
MobileReact Native 0.76, Expo 52, NativeWind
TVReact Native — ExoPlayer/Media3 (Android TV), AVPlayer (tvOS)
BackendFastify 5, Prisma 6, MariaDB 11
DataTanStack Query v5
Videohls.js (web), mpv (desktop), react-native-video
LanguageTypeScript 5.7, strict mode