TS6 Manager is a browser-based management interface for TeamSpeak servers. This Home Assistant Add-on wrapper packages the manager so it can be installed, started, stopped, backed up and monitored through Home Assistant.

Important: This add-on is the manager UI, not the TeamSpeak 6 server. It connects to an already running TeamSpeak 6 server through the WebQuery HTTP API.

#Wiki Pages

Page	Purpose
Installation	Add repository, install and start the add-on.
First Start	Create the first admin account through the setup wizard.
TS6 Connection	Connect to TeamSpeak 6 with host, WebQuery port and API key.
Persistence & Backup	Understand what lives under /data and what HA backups preserve.
Troubleshooting	Fast checks for broken UI, API errors, database resets and port conflicts.

#Minimum Operating Model

Home Assistant Add-on → TS6 Manager Web UI :8066
TS6 Manager Backend  → TeamSpeak 6 WebQuery HTTP API :10080
TS6 Manager Data     → /data/ts6webui.db + /data/music + /data/secrets.env

The upstream project is structured as a web application with a frontend, backend and SQLite persistence. The frontend never needs direct access to TeamSpeak API keys; API calls go through the backend.

┌──────────────────┐      ┌──────────────────┐      ┌────────────────────────┐
│ Browser / Web UI │ ───▶ │ TS6 Manager API  │ ───▶ │ TeamSpeak 6 Server     │
│ Frontend SPA     │      │ Backend service  │      │ WebQuery HTTP :10080   │
└──────────────────┘      └─────────┬────────┘      └────────────────────────┘
                                    │
                                    ▼
                              ┌──────────┐
                              │ SQLite   │
                              │ /data DB │
                              └──────────┘

#Component Map

Layer	Role	Operational note
Frontend	Browser UI for dashboard, channels, clients, bots, flows and widgets.	Expose only behind trusted access.
Backend	Handles authentication, WebQuery calls, bot engine and persisted settings.	Requires stable secrets and database persistence.
SQLite	Stores users, settings, connections and manager state.	Must remain under /data for HA backup safety.
TeamSpeak 6	Actual voice server and WebQuery API endpoint.	Keep WebQuery private; do not publish port 10080 to the internet.

#Step 1 — Add Repository

1. Open Home Assistant.
2. Go to Settings → Add-ons → Add-on Store.
3. Open ⋮ → Repositories.
4. Add the repository:

https://codeberg.org/Pol4rFuchs/teamspeak6-manager-ha-app

#Step 2 — Install Add-on

1. Search for TS6 Manager in the Add-on Store.
2. Click Install.
3. Wait until the image is downloaded and prepared.

#Step 3 — Start

1. Open the add-on Info tab.
2. Enable Start on boot if the manager should run permanently.
3. Click Start.
4. Open the Log tab and verify that the service starts without errors.

#Open Web UI

http://homeassistant.local:8066

If you changed the host port in the Home Assistant Network tab, use your configured host port instead of 8066.

#1. Open Setup

http://homeassistant.local:8066/setup

Create your first admin account. There are no safe default credentials; define your own strong password.

#2. Log In

1. Open the TS6 Manager Web UI.
2. Log in with the admin account created in setup.
3. Go to Settings → Connections.

#3. First Health Check

Check	Expected result
Web UI opens	Login or setup screen appears.
Database exists	/data/ts6webui.db is created after first start.
Secrets exist	/data/secrets.env exists and remains stable across restarts.
Connection page loads	Settings area allows adding a TeamSpeak server connection.

TS6 Manager talks to your server through the TeamSpeak 6 WebQuery HTTP API. Raw Telnet ServerQuery is not the operating model for this manager.

#Required Values

Field	Value	Note
Host	<TS6-SERVER-IP> or local hostname	Use the IP/hostname reachable from the add-on container.
WebQuery Port	10080	Default WebQuery HTTP API port.
API Key	Generated by TeamSpeak server	Copy from server log or server admin tooling.
Protocol	HTTP WebQuery	Do not use raw Telnet query.

#If TS6 Server Runs on the Same HA Host

Do not blindly use localhost. In containerized Home Assistant add-ons, localhost often means the manager container itself, not another add-on. Prefer the HA host IP, the TS6 add-on hostname if available, or the Docker/network name proven by logs.

# Safer examples
Host: 192.168.x.y
Port: 10080

# Only use localhost if you have verified the manager container can reach TS6 there
Host: localhost
Port: 10080

#Connection Test Matrix

Symptom	Likely cause	Fix
connection refused	Wrong host/port or WebQuery disabled.	Verify TS6 server log and port 10080.
unauthorized / invalid key	Wrong or outdated API key.	Generate/copy a fresh WebQuery API key.
Timeout	Routing or firewall issue.	Check LAN/VLAN, container network and host firewall.

#Server Management

• Live dashboard with online users, channels, uptime, ping and bandwidth information.
• Channel tree and client list.
• Client actions such as kick, ban, move and poke.
• Server groups, channel groups, permissions, ban list and token / privilege key management.
• Server log viewing and administration panels, depending on upstream feature state.

#Music Bots

• Multiple bots per server.
• Radio streams, YouTube playback via yt-dlp and local music library.
• Queue, volume, playback state and chat command control.
• Persistent music storage under /data/music in the add-on wrapper.

#Bot Flow Engine

• Visual node editor for automation workflows.
• Triggers, conditions, variables, delays, loops and actions.
• Useful for workflows such as AFK movers, temporary channels, group protection and online counters.

#Embeddable Widgets

• Public server status widgets for websites or forums.
• Output styles such as live page, SVG, PNG or JSON depending on upstream implementation.
• Use token-based public access carefully; widgets are intended for status display, not admin access.

Port	Service	Expose publicly?	Notes
8066/tcp	TS6 Manager Web UI	Prefer no	Expose only behind trusted auth, VPN, Cloudflare Access or LAN.
10080/tcp	TeamSpeak 6 WebQuery HTTP API	No	Keep private. Only TS6 Manager should need access.
9987/udp	TeamSpeak voice traffic	Usually yes	Server voice port, separate from the manager.

#Reverse Proxy Pattern

Public HTTPS → Reverse Proxy → Home Assistant host :8066 → TS6 Manager
TS6 Manager → private LAN/container route → TS6 WebQuery :10080

Do not route public traffic directly to WebQuery port 10080. If you publish anything, publish the manager UI behind authentication, not the TS6 API key endpoint.

The add-on wrapper should keep important manager state under /data. That is the critical Home Assistant add-on data directory and the clean backup/rollback boundary.

/data/
├── ts6webui.db       # SQLite database: users, settings, connections, manager state
├── secrets.env       # JWT_SECRET and ENCRYPTION_KEY
└── music/            # Downloaded music and local library

#What Must Survive Updates

Path	Content	Why it matters
/data/ts6webui.db	SQLite database	Admin account, settings and connection profiles.
/data/secrets.env	JWT/encryption secrets	Stable secrets prevent token/session and credential encryption problems.
/data/music/	Music library	Preserves bot downloads and local files.

#Backup Workflow

1. Go to Settings → System → Backups.
2. Create a full backup before large add-on updates.
3. For rollback, restore the TS6 Manager add-on data or the full backup.
4. After restore, start the add-on and verify the database and login.

• Treat the WebQuery API key like a password.
• Do not expose WebQuery port 10080 to the internet.
• Keep the manager behind Home Assistant authentication, VPN, trusted LAN or an external access-control layer.
• Never commit secrets.env, SQLite databases, API keys or backup archives to Git.
• Use a strong admin password in the setup wizard.
• Be careful with public widgets: they are status surfaces and should not leak private channel/client details you do not want public.

#Pre-Publication Checklist

Item	Status target
HTTPS enabled	Required for external access.
Manager auth enabled	Required.
WebQuery private	Required.
Backups encrypted/off-host	Recommended.
API key rotated after leaks	Required after any suspected exposure.

#Before Update

1. Create a Home Assistant backup.
2. Download/export the backup if the update is risky.
3. Open the add-on log and note the currently running version.
4. Confirm /data/ts6webui.db exists.

#After Update

1. Start the add-on.
2. Open the Web UI.
3. Verify login.
4. Verify TeamSpeak server connection.
5. Test one safe client/channel read-only action before doing admin actions.

#Rollback

1. Stop TS6 Manager add-on
2. Restore known-good Home Assistant backup
3. Start add-on
4. Verify /data/ts6webui.db and login
5. Re-test WebQuery connection

#Web UI Does Not Open

• Check if the add-on is started.
• Check the add-on log for startup errors.
• Confirm port 8066 is mapped in the Network tab.
• Check if another add-on already uses the same host port.
• Try direct URL: http://homeassistant.local:8066.

#Cannot Connect to TS6 Server

• Confirm TeamSpeak 6 server is running.
• Confirm WebQuery HTTP API is enabled.
• Confirm host/IP is reachable from the add-on environment.
• Confirm WebQuery port is 10080.
• Confirm API key is current and copied without spaces or line breaks.

#Database or Login Broken After Update

1. Stop the add-on.
2. Restore a known-good Home Assistant backup.
3. Start the add-on again.
4. Check whether /data/ts6webui.db exists.

If /data/ts6webui.db is missing, the manager behaves like a fresh installation.

#Log Pattern Matrix

Symptom	Meaning	Action
address already in use	Host port conflict.	Change mapped port or stop conflicting service.
permission denied	Data or music path not writable.	Check add-on data path and startup script permissions.
connection refused	TS6 WebQuery target not reachable.	Fix host, port, firewall or WebQuery setting.
invalid api key	Wrong TeamSpeak WebQuery API key.	Generate/copy a fresh key.

This page intentionally keeps the source links visible and centralized so the wiki can be hosted as a standalone Codeberg Pages asset later.

#Disclaimer

This is an unofficial, community-maintained Home Assistant add-on wrapper for clusterzx/ts6-manager. It is not affiliated with or endorsed by TeamSpeak Systems, Inc. or the upstream project maintainer.

No HA Ingress Support

The TS6 Manager web UI cannot be served through Home Assistant Ingress. The React frontend uses absolute asset paths that break under HA's ingress proxy.

Workaround: Always access TS6 Manager via its direct URL: http://<HA-IP>:8066

WebQuery Connection Required

TS6 Manager requires a running TeamSpeak 6 Server with HTTP WebQuery enabled on port 10080. Without it, the Manager cannot connect and will show a connection error on the dashboard.

No Multi-Server Management

Each TS6 Manager instance connects to exactly one TeamSpeak 6 Server. Managing multiple servers requires multiple Manager instances.

SQLite Database Not Shared

The Manager's SQLite database (/data/ts6manager/prisma.db) is local to the container. It is not synced with the TeamSpeak 6 Server database. If you reinstall the Manager, connection profiles and settings are lost unless you have a backup.

No armhf / armv7 / i386 Support

The add-on only supports amd64 and aarch64. Home Assistant has dropped official support for 32-bit architectures. If you are running one of these, consider migrating to a supported platform.

Music Bot Features Require yt-dlp

The upstream project's music bot features depend on yt-dlp. These work in the add-on, but may break if YouTube changes its API. This is an upstream dependency outside our control.

Disclaimer

This is an unofficial, community-maintained Home Assistant add-on wrapper for clusterzx/ts6-manager. It is not affiliated with or endorsed by TeamSpeak Systems, Inc. or the upstream project maintainer.

Wrapper License

MIT License

The upstream TS6 Manager project by clusterzx is licensed under its own terms. The TeamSpeak 6 Server itself is subject to TeamSpeak licensing terms.

Useful Links