Choose how VoxHF reaches your cockpit.

VoxHF requires Node.js 20 or newer and ffmpeg with Speex support.

winget install OpenJS.NodeJS.LTS
winget install Gyan.FFmpeg

Open a new terminal after installation.

Download voxhf-local-<version>.zip and SHA256SUMS.txt from the matching GitHub release. Extract the complete archive to a normal user folder.

Open releases >

Double-click start.bat. On first launch the setup wizard creates private config.json and detects a suitable Ethernet or Wi-Fi IPv4 address.

Double-click start.bat before opening PilotUI. Enter the IPv4 address printed in the VoxHF console as the PilotUI Simulator Address, then connect Altitude normally.

http://localhost:3000

The local browser workspace needs no account and is not exposed to the public internet.

Ask the server operator for the hosted app URL, relay URL and a one-time registration code when registration is invite-only. Independent servers may run modified software; review the operator's information before registering.

Browse listed servers >

Open the server app's /register page. Enter your own username, password and invitation code. Save the personal agent token shown once after registration.

From the extracted Local folder, use the guided setup:

npm.cmd run setup -- agent

Enter the server's relay URL, your personal agent token and a recognizable simulator-PC name.

Alternatively, open the existing config.json and update only these fields:

{
  "remoteAgentEnabled": true,
  "remoteRelayUrl": "wss://relay.example.com",
  "remoteRelayToken": "paste-your-personal-agent-token",
  "remoteDeviceId": "my-simulator-pc",
  "remoteDeviceName": "My Simulator PC"
}

Use the relay URL supplied by the operator. Keep remoteDeviceId stable for this PC; remoteDeviceName is the friendly name shown in the app. Preserve every other setting already present in config.json.

Restart start.bat. The console should report the remote agent as connected. Sign in to the hosted app from each trusted PC or phone using the same account.

http://localhost:3000 remains available even when the external relay is unavailable. No PilotUI, PilotCore, FSD or TS2 proxy port is opened to the internet.

Use a current Ubuntu or Debian VPS with a public IP address. Create three DNS records pointing to that address and wait until all three resolve:

your-domain.example
app.your-domain.example
relay.your-domain.example

The first serves the public site, the second the operational app, and the third the relay and admin panel.

apt update
apt install -y docker.io docker-compose-v2 git curl ufw
systemctl enable --now docker
docker --version
docker compose version

If your distribution does not provide docker-compose-v2, install Docker Engine and the Compose plugin from Docker's official repository. Do not continue until docker compose version succeeds.

Allow your real SSH port before enabling the firewall, then expose HTTP and HTTPS:

ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable
ufw status

VoxHF does not require any other public port. Keep the local PilotUI, PilotCore, FSD, TS2 and webapp ports private.

A Git checkout is recommended because the managed update and rollback commands use its history.

git clone https://github.com/leledeste/voxhf.git /opt/voxhf
cd /opt/voxhf
chmod +x infra/docker/voxhf-server.sh

infra/docker/voxhf-server.sh setup

Enter the base domain without https://, an email address for TLS notices, and choose either Private token for one owner or Accounts for invite-only multi-user access. Store every generated token in a password manager. The wizard creates the Git-ignored infra/docker/.env; never commit or share it.

infra/docker/voxhf-server.sh doctor
infra/docker/voxhf-server.sh start
curl https://relay.your-domain.example/health

Startup builds both containers, obtains TLS certificates and waits for relay health. DNS must already point to the VPS and inbound TCP 80/443 must be reachable.

Accounts: customise the neutral Terms and Privacy templates before inviting other people. Then open https://relay.your-domain.example/admin, use the bootstrap token to create the owner, create a one-time invite under Access, and register at https://app.your-domain.example/register. Save the personal agent token shown after registration.

Private token: use the relay token printed by the wizard for the local agent and browser Remote settings. The browser must also be paired with the short-lived code printed by the agent.

MFA for the owner account is optional and can be enabled later from the admin Security section.

Install Local Slim on the Windows PC, then configure its outbound connection:

npm.cmd run setup -- agent

Enter wss://relay.your-domain.example, the personal agent token and a recognizable PC name. Restart start.bat; the console must report the remote agent as connected. The local workspace remains available at http://localhost:3000.

Open the base domain, sign in at the app domain, confirm the agent is online, and test COM, XPDR, chat, RX and TX from a trusted browser before relying on the deployment during a flight.

infra/docker/voxhf-server.sh doctor
infra/docker/voxhf-server.sh logs

infra/docker/voxhf-server.sh backup
infra/docker/voxhf-server.sh update

Keep off-server copies of infra/docker/.env and the SQLite backups in infra/docker/backups/. Test restore <backup-file> before depending on those backups. After a managed update, rollback restores the previous commit and its pre-update database.