Choose how VoxHF reaches your cockpit.

VoxHF requires Node.js 24 or newer (24 LTS recommended) 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.

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.

Use iOS or iPadOS 16.4 or newer. Open the hosted HTTPS VoxHF app in Safari and sign in. Tap Share, choose Add to Home Screen, keep Open as Web App enabled when shown, then tap Add.

Leave Safari and open VoxHF from its new Home Screen icon. Wait for the agent and callsign to be online, then open Settings > Notifications. Confirm Device Support: Supported and Proxy: Ready, tap Enable on This Device, and choose Allow in the iOS prompt. Enable IVAO Online Confirmation only on devices that should confirm each successful network connection.

In remote mode, PC / Proxy Offline Alert is a separate per-device option. Read and accept its confirmation only if this device should be notified when the simulator PC, network path, or local VoxHF process disappears during a confirmed IVAO session. The relay keeps only a short-lived notification request already encrypted and signed by the proxy; it does not receive the local VAPID private key.

The final state should show Permission: granted, This Device: Enabled, and at least one saved device. Reconnect IVAO to verify the optional online confirmation, or lock the screen and send a private message to the active callsign. To verify the normal disconnect alert, use a simulator scenario moving above five knots, then leave a confirmed IVAO connection disconnected for more than ten seconds. To verify the PC/proxy alert, keep IVAO connected, enable its option, close the proxy, and wait through heartbeat detection plus the default 30-second grace period. Repeat these steps separately on every device that should receive alerts.

If alerts do not arrive, open the iOS Settings app and check Notifications > VoxHF > Allow Notifications, Lock Screen delivery, Focus modes and Scheduled Summary. If VoxHF says Add to Home Screen first, it is open in a browser tab instead of the installed Home Screen app. Notification permission is independent of session chat recovery.

Apple Web Push requirements >

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, session-history recovery, RX and TX from a trusted browser. Enable notifications separately on each supported device and verify a private-message alert 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.