Setup Remote or Hosted

Setup: TeamSpeak elsewhere (or rented)

Your TeamSpeak server runs on a different machine than TS6 Manager — another VPS of yours, a box at home, or a server rented from a TeamSpeak host.

If both run on the same host, use Setup: TeamSpeak on the same machine instead.

What's different about this setup

Everything the manager does goes over the network to another machine. That changes three things, and they are the three things people get stuck on:

You may not be able to enable WebQuery yourself
The query port has to be reachable across the network — which means deciding who else can reach it
The TeamSpeak server's allowlist needs the manager's own outbound address, which is not obvious to look up

1. Enable WebQuery on the TeamSpeak server

WebQuery is the HTTP query interface, off by default on TeamSpeak 6, and separate from the old raw/telnet ServerQuery on port 10011.

If you control the server, enable it in tsserver.yaml (keep the rest of your file as it is):

server:
  query:
    http:
      enable: 1
      port: 10080

ip sits next to port if the interface should listen on a specific address only. The same exists as command-line flags (--query-http-enable, --query-http-port, --query-http-ip) and, for the Docker image, as environment variables (TSSERVER_QUERY_HTTP_ENABLED, TSSERVER_QUERY_HTTP_PORT, TSSERVER_QUERY_HTTP_IP). Restart afterwards.

If you rent the server, you probably cannot change this yourself. Some hosts expose it in their panel; otherwise ask support to enable the HTTP query interface and tell you the port.

Be aware that some hosts refuse, or only offer the older raw ServerQuery. This manager does not support raw/telnet — WebQuery is required for everything except the music bots. Worth clarifying before you build anything on top.

If your host gives you no WebQuery access at all, you can still add the connection without an API key (see step 5). The music bots join the server like any other TeamSpeak client and need only the host and the voice port, so they work; every page that needs WebQuery is hidden while that connection is selected. Music Bots lists what differs.

2. Get the API key

WebQuery authenticates with an API key rather than a password.

A self-hosted server prints a serveradmin key once, on its very first startup, in a log block titled "Server Query Admin Account created". Otherwise generate one with the apikeyadd query command, or ask your host for one.

This key grants full server administration. Treat it exactly like a root password — and see the firewall note below, because on a remote setup it travels over the network.

3. Make the query port reachable — and only to you

The manager connects out to your-server:10080. That port has to be open on the TeamSpeak side.

Do not simply open it to the internet. Anything that reaches it can attempt to authenticate, and the key behind it is a full administrative credential. Restrict it to the manager's address at the firewall:

# on the TeamSpeak server, allowing only the manager's IP
ufw allow from <manager-public-ip> to any port 10080 proto tcp

If your host manages the firewall, ask them to restrict it the same way.

If the connection is plain HTTP, the API key crosses the network unencrypted. If your server offers HTTPS for the query interface, prefer it — WebQuery over HTTPS below covers both sides.

4. Add the manager to the query IP allowlist

TeamSpeak keeps an allowlist (query_ip_allowlist.txt) containing only the loopback address by default. The address the manager connects from has to be in it, or the connection is dropped after being accepted — a silent failure with nothing useful logged.

TeamSpeak's own documentation recommends exactly this for a web administration interface: add its IP to the allowlist.

Find the manager's outbound address by asking from the machine the manager runs on:

curl -s https://api.ipify.org

Then add it on the TeamSpeak server and restart:

echo <manager-public-ip> >> /var/tsserver/query_ip_allowlist.txt

If the manager sits behind a dynamic IP, this breaks whenever the address changes. A fixed IP, or a small CIDR range you control, saves a lot of confusion later.

5. Add the connection

In the manager: Settings → Connections → Add.

Field	Value
Host	The TeamSpeak server's public hostname or IP
WebQuery port	`10080`, or whatever your host told you
API key	From step 2. Optional — leave it empty if your host gives you no WebQuery access; only the music bots work then

Unlike the same-machine setup, the host field is straightforward here — it is the same address you would use from anywhere else.

Press Test Connection before saving. It surfaces the real reason for a failure — a refused connection, a timeout, or TeamSpeak's own error message. A connection without an API key has nothing to test, so the button is greyed out for it.

Changes to a connection — host, ports, key, enabling or disabling it — take effect straight away; the manager does not need a restart. Deleting a connection also stops its music bots and bot flows.

6. Optional: SSH, for events and files

Only needed for bot flows that react to server events or chat commands — a client joining, leaving, or moving channel — for the live event feed in the Query Console, and for the Files page and icon picker. Scheduled flows and webhooks work over WebQuery alone.

This needs a second port reachable (10022 by default) and, on a rented server, usually a second request to your host. The same firewall reasoning applies: restrict it to the manager's address.

7. First things to set up

Create your admin account at /setup
Consider a Bot Identity (Settings → Connections → Bot Identity) so automated actions appear under their own name in TeamSpeak's logs
Enable two-factor authentication under Settings → Account — especially here, since a remote setup usually means the manager is reachable from the internet too

WebQuery over HTTPS

On a remote setup the API key and every command cross the network. TeamSpeak 6 can serve WebQuery over HTTPS as well — a second interface, default port 10443 — and the manager speaks it. If you control the TeamSpeak server, this is the setup to aim for. (It works the same on the same machine; there it matters less, since the traffic never leaves the host.)

On the TeamSpeak server

TeamSpeak does not create a certificate. You bring one, for a hostname that points at the TeamSpeak server — for example from Let's Encrypt — as a PEM file (the full chain works) plus its private key. If HTTPS is enabled without them, the server logs an error and keeps running, but nothing listens on 10443.

Put the certificate files in place first, where the user TeamSpeak runs as can read them. If a configured certificate path does not exist, the server refuses to start at all (Not an existing file). So: files first, configuration second — and never delete those files while the configuration points at them.
Enable the interface in tsserver.yaml — adapt the paths, and keep the rest of your file as it is:
```
server:
  query:
    https:
      enable: 1
      port: 10443
      certificate: /path/to/fullchain.pem
      private-key: /path/to/privkey.pem
```
The Docker image takes the same as environment variables: TSSERVER_QUERY_HTTPS_ENABLED, TSSERVER_QUERY_HTTPS_PORT, TSSERVER_QUERY_HTTPS_CERT, TSSERVER_QUERY_HTTPS_PRIVATE_KEY (mount the files into the container).
Restart the server. It confirms with listening for https query on ...:10443 in its log.

TeamSpeak reads the certificate only at startup. Replacing the files while it runs changes nothing — it keeps serving the old certificate until the next restart. Whatever renews your certificate (a certbot deploy hook, acme.sh's reload command, ...) therefore has to copy the new files into place and restart the TeamSpeak server. Otherwise everything works until the old certificate expires, and then the manager stops connecting.

Open 10443 the same way as step 3 — to the manager's address only. A firewall that allows only 10080 today blocks the manager until you add the new port; that includes rules for the Docker network the manager's container connects from.

In the manager

Settings → Connections → Edit the connection:

Field	Value
Host	The hostname in the certificate — not the IP. The manager checks that the name matches the certificate, and an IP fails with `does not match certificate's altnames`. The name also has to resolve from inside the backend container
WebQuery Port	`10443` — switching Use HTTPS on does not change the port for you
Use HTTPS	On

Press Test Connection before saving.

Leave TS_ALLOW_SELF_SIGNED unset for a certificate from a public CA such as Let's Encrypt. That variable (Configuration) exists for self-signed certificates only, and it does more than its name says: it switches certificate checking off entirely — any certificate and any hostname are accepted — and for every connection of the manager, not just one.

Turning plain HTTP off

Once the manager connects over HTTPS, you can disable the http interface (server.query.http.enable: 0, or drop TSSERVER_QUERY_HTTP_ENABLED), so the key can no longer be sent unencrypted by mistake. Before you do, move everything else that talks to 10080 — an external health check or monitoring probe, scripts, other tools — over to HTTPS, or it will report the server as down the moment HTTP is gone.

To check from the machine the manager runs on (adapt the name):

curl -sS -o /dev/null -w '%{http_code}\n' https://ts.example.com:10443/

Any HTTP status code means the certificate and the name check passed; an error such as SSL certificate problem means they didn't. After a renewal, openssl s_client -connect ts.example.com:10443 -servername ts.example.com </dev/null | openssl x509 -noout -enddate shows whether TeamSpeak already serves the new certificate.

If it doesn't connect

Symptom	Likely cause
Timeout	Firewall on the TeamSpeak side, or the port isn't open at all
Connection refused	WebQuery isn't enabled, or it's a different port than you were told
Connects, then drops silently	The IP allowlist (step 4) — the most common one in this setup
Worked, then stopped	The manager's outbound IP changed and no longer matches the allowlist
`does not match certificate's altnames`	Host is an IP or a name the certificate doesn't cover — see WebQuery over HTTPS
`unable to get local issuer certificate`, or another certificate error	The certificate isn't from a CA the manager trusts (self-signed, or a private CA) — see WebQuery over HTTPS
Worked over HTTPS, then certificate errors from one day to the next	The certificate was renewed, but TeamSpeak still serves the old one until it restarts