Pairing the app

Pairing the app

The Vonode app connects to your node directly over encrypted SSH. There is no account to sign up for: you pair by scanning a one-time QR code that the node shows.

Before you pair

• Install Vonode 1.4.0 or later from the App Store (coming soon; free download; iPhone and iPad, iOS and iPadOS 17 or later).
• The phone must reach the node on one TCP port, 2222 by default:
  • At home: allow the port on the host firewall: sudo ufw allow 2222/tcp.
  • Away from home: forward the port on your router to the node, and use your public IP or a DDNS name as the address.
  • Behind carrier-grade NAT (no public IPv4): run a VPN such as WireGuard or Tailscale between the phone and the host, and use the host's VPN address.

Show the QR code

Use the address the phone will use to reach the node.

systemd package:

sudo /opt/vonode/vonode pair -c /opt/vonode/config/config.yaml -host node.example.com

Docker (in the package's docker/ folder):

sudo docker compose exec vonode /app/vonode pair -c /app/config/config.yaml -host node.example.com -port 2222

Add -port <port> if the router forwards a different external port. The terminal shows the code as a block graphic. It is valid for five minutes and works once; run the command again for a new one.

Scan it

1. Open the Vonode app.
2. On the Connect your node screen, tap the scanner and point the camera at the QR code in the terminal.
3. The app connects to the node over SSH, pins the node's host key and shows the node on its home screen with its numbers.

If the app shows a connection error, check the port forward, firewall or VPN first (see Troubleshooting), then create a fresh code.

Free plan or subscription

Free plan. Without a subscription the node runs the free plan. Open the Numbers tab and choose the one number whose SMS you want to see. The choice is permanent for this node; a backup restore keeps it. The Messages tab then shows the SMS that number receives; you can read and delete them.

Subscription. Every other feature (calls, Wi-Fi calling, sending SMS, notifications, eSIM profiles, proxies, automations, more numbers) needs a subscription, bought in the app. Open More, then See Plans. Apple bills you; the app hands the signed transaction to your node, which unlocks within a few seconds and restarts into full mode. Then add your modules with Add Modem and switch Wi-Fi calling on per SIM. One subscription unlocks one node.

If a subscription ends without renewal, the node keeps working for 72 hours so the app can deliver the renewal. After that, or immediately after a refund, it returns to the free plan.

More phones and lost phones

• To pair another phone, use Move to a new phone in the app; it shows a one-time QR code.
• A lost phone can be removed from the app's list of paired phones.
• Resetting the administrator password signs out all phones; each pairs again.

Keep the host key

Paired phones pin the node's SSH host key. The systemd package keeps it across upgrades. With Docker it lives in the vonode_gateway-private volume: never run docker compose down -v.