playeraudio.
CLUSTER MANAGER · 0.1.0 PREVIEW

Your communities.
One host console.

Create, start and stop servers from your browser. Update selected instances or all of them, make backups, and restore the snapshot you need.

Set up your host ↓
WINDOWS & LINUX

Get the manager

The dashboard and documentation are included. Download the community server separately.

Download checksums

Windows x64

Manage your communities on a Windows host.

Version 0.1.0 · 3.1 MB

Preview · unsigned executable

Download Windows manager
Verify SHA-25645da23ef44cf34bef38d0e2f0d42f8f893b97184febc94437809cf102ede2ad7

Linux x64

Manage your communities on a Linux host.

Version 0.1.0 · 2.8 MB

Preview

Download Linux manager
Verify SHA-25650d82582fe8e8acf6e5e2dd72cab397c65a6ca82c2a33d0eebbb02f3f5986eeb

Before you start

Run several PlayerAudio communities on one Windows or Linux host. Create instances, start and stop them, change settings, update selected instances or all instances, and restore a chosen backup from your browser. The same operations are available through the JSON API.

Version 0.1.0 is a preview for 64-bit Intel and AMD machines. The Windows executable is unsigned.

Download the manager for your host above, then get a matching community server package. The server executable is supplied separately. Check each archive against its published SHA-256 before extracting it. For initialization, use the SHA-256 of the extracted server executable, not the archive. Compare it with the server package's SHA256SUMS or the published server manifest.

Use a dedicated non-administrator account. Keep management on your private network or VPN. Use separate VMs or containers when customers require isolated hosting.

The dashboard is included in the download. The Linux community server requires Debian 12+ or Ubuntu 24.04+ on x64.

Try it on your computer

Initialize a new data directory with an existing writable parent. Keep that directory private.

Windows setup

Extract both downloaded packages. In PowerShell, replace the server path and hash below with your verified executable. Run these commands as the account that will run the manager.

New-Item -ItemType Directory -Force C:\PlayerAudio
Get-FileHash C:\PlayerAudio\playeraudio-server.exe -Algorithm SHA256
.\playeraudio-cluster-manager.exe init `
  --data-dir C:\PlayerAudio\cluster-data `
  --server-binary C:\PlayerAudio\playeraudio-server.exe `
  --server-sha256 VERIFIED_SERVER_EXECUTABLE_SHA256 `
  --domain localhost --public-bind 127.0.0.1 --development
.\playeraudio-cluster-manager.exe serve --data-dir C:\PlayerAudio\cluster-data
Linux setup

Extract both packages into separate directories. In this example, copy the native server executable to /home/playeraudio/playeraudio-server and run as the playeraudio account. The data directory must not already exist.

sha256sum /home/playeraudio/playeraudio-server
./playeraudio-cluster-manager init \
  --data-dir /home/playeraudio/cluster-data \
  --server-binary /home/playeraudio/playeraudio-server \
  --server-sha256 VERIFIED_SERVER_EXECUTABLE_SHA256 \
  --domain localhost --public-bind 127.0.0.1 --development
./playeraudio-cluster-manager serve --data-dir /home/playeraudio/cluster-data
Sign in and create a community

Open http://localhost:8443 and sign in with the value in bootstrap-token.txt inside your private data directory. Keep this token out of screenshots, URLs and shared files.

Create an instance and start it. For a local console trial, turn off Enable the voice relay; a relay requires a valid public IPv4 address or successful discovery. Retrieve the instance's Owner code to claim the community through PlayerAudio. Community owners manage channels, roles and members inside PlayerAudio.

Development mode accepts loopback listeners only. Use the TLS setup below for public hosting.

Host public communities

Point a DNS name such as servers.example.com directly at your host. Instances share this name and use separate ports, such as https://servers.example.com:10000 and :10001. Use a second, private administration hostname such as manage.example.com, and obtain a TLS certificate covering both names.

The manager loads your certificate and private key; obtain and renew them through your certificate tooling. See the server hosting guide for certificate and firewall background. Standard website proxies generally do not forward the required voice and community ports, so use direct DNS.

Initialize with TLS

Use a fresh data root and absolute paths. In this Linux example, /srv/playeraudio is an existing private directory writable by the service account. The same flags work in Windows PowerShell with Windows paths and backticks for line continuations.

./playeraudio-cluster-manager init \
  --data-dir /srv/playeraudio/cluster-data \
  --server-binary /opt/playeraudio/playeraudio-server \
  --server-sha256 VERIFIED_SERVER_EXECUTABLE_SHA256 \
  --domain servers.example.com \
  --admin-domain manage.example.com \
  --tls-cert /etc/playeraudio/tls/fullchain.pem \
  --tls-key /etc/playeraudio/tls/privkey.pem \
  --public-ip YOUR_PUBLIC_IPV4
./playeraudio-cluster-manager serve --data-dir /srv/playeraudio/cluster-data

Protect the certificate key so only the service account and certificate renewal process can read it. Management defaults to 127.0.0.1:8443. Reach it through a VPN or SSH tunnel and use the exact HTTPS hostname and port printed at startup. A tunnel also needs private DNS or a local hosts entry so manage.example.com resolves through it. For direct VPN access, set --admin-bind to the host's VPN address. Keep management off the public internet.

Ports and certificates

The manager assigns free ports from these pools and checks them again before starting an instance. Configure your host firewall, provider firewall and router forwards for the assigned ports yourself.

  • Management: TCP 8443, administration network only.
  • Community HTTPS and WebSockets: TCP 10000–10999, assigned instance ports.
  • Voice relay: TCP and UDP 30000–30999, assigned instance ports.
  • Voice media: UDP 40000–49999, assigned blocks of 100 ports.

Behind NAT, forward the assigned ports and set --public-ip to the public IPv4 address. This release does not provide TURN-over-TLS. Test an actual call from outside your network before opening the service to users.

After renewing the certificate files, choose Reload renewed certificate in the dashboard.

Archiving keeps the instance's data and assigned ports.

Update selected instances or all

Download and verify a trusted server executable for the host's OS. Admit it through the local CLI, including while the manager is running. Replace the version label with the release you downloaded.

playeraudio-cluster-manager stage-release \
  --data-dir /srv/playeraudio/cluster-data \
  --server-binary /opt/releases/playeraudio-server \
  --server-sha256 VERIFIED_SERVER_EXECUTABLE_SHA256 \
  --version 0.2.0-rc.19

Select the release and instances in the dashboard, then choose Update selected or Update all. Different instances can keep different releases. The manager makes a safety backup before updating. A failure restores that instance's previous release and stops the remaining batch. Check the job results before retrying.

Updates interrupt calls on the affected instance. Jobs continue when you close the browser; check the result before treating an update as complete. Keep older releases available for backup restoration.

The manager's own executable is updated separately while stopped. New communities initially use the server binary supplied during initialization; select and update them if you want a later staged release.

Back up and restore

Select instances to back them up together, or open an instance's Backups panel and create a snapshot. To recover, choose the specific snapshot and restore it. The manager makes another safety backup first. Restoration recovers the saved data, settings and server release while keeping the instance's current address.

Backups stop the affected instance and interrupt calls. Allow enough disk space for your data and additional copies. You can keep up to 100 snapshots per instance. Delete older snapshots when you need space.

Keep encrypted backup copies on another machine or disk. For whole-host recovery, stop the manager and back up the entire data directory. Protect the TLS key separately. Restore snapshots to their original instance.

Automate with the JSON API

Use https://manage.example.com:8443/api/v1 with an Authorization: Bearer header containing the administrator token from your secret store. Keep tokens out of URLs, command history and web pages. Requests must use the configured hostname and port.

  • GET /status, /instances and /releases show the host, instance state and staged releases.
  • POST /instances creates an instance with request_id and settings. PUT /instances/{id} changes a stopped instance using its current revision and settings.
  • POST /instances/{id}/start, /stop and /restart control a community process.
  • POST /instances/{id}/archive and /restore archive and unarchive an instance. Backup restoration uses /jobs instead.
  • GET /instances/{id}/backups lists snapshots. DELETE /instances/{id}/backups/{backup_id} removes one.
  • POST /jobs queues an update, backup or backup restore. GET /jobs returns job progress and results.
  • POST /tls/reload reloads the certificate. GET /audit returns recent operations.
Update request

POST this body to /api/v1/jobs, using fresh UUIDs for each new request and real instance and release IDs. Reuse the same request ID only to retry an uncertain submission of the same operation.

{
  "request_id": "71b0e407-a15a-40e7-98bd-12aa696839a3",
  "operation": {
    "action": "update",
    "instance_ids": ["dc3d5c1c-5dc6-4e36-ae2b-9c61bd0cd115"],
    "release": "SHA256_FROM_GET_RELEASES"
  }
}

To update all, get /instances and submit the explicit list of IDs whose instance.archived is false. Empty, duplicate, unknown and archived targets are rejected. For a backup job use action "backup" with instance_ids. For restoration use action "restore_backup" with instance_id and backup_id.

Check job results

A 202 response means the job was queued. Poll GET /jobs every few seconds until it completes, fails or becomes interrupted. The latest 50 jobs are retained. Inspect individual results after a failed batch to see which instances completed and which were untouched.

The full API reference is available from your own manager at the authenticated GET /api/v1/openapi.json endpoint.

Run at boot and recover

The packages include service installation instructions for Windows and Linux. Initialize as the dedicated account that will run the service. On Linux, adjust the supplied unit's data path to match your setup and keep data and certificates outside /home. On Windows, grant the account Log on as a service and install the service with the name PlayerAudioClusterManager. Follow SERVICES.md in your download.

Stop the manager before using doctor or rotate-token. Use doctor to check your configuration, or rotate-token to replace a lost administrator token.

playeraudio-cluster-manager doctor --data-dir /srv/playeraudio/cluster-data
playeraudio-cluster-manager rotate-token --data-dir /srv/playeraudio/cluster-data

After an interruption, restart the manager and check job results before retrying. Enable Autostart for instances that should start with the manager. Avoid manually editing files inside instance data directories.