Connect to a Relay

Add a Relay

The Viaalink CLI (via) publishes through a Viaalink Relay. Before the first publish, register this device with the Relay. The Relay’s operator gives you an invite link (see Invites); paste it in quotes, because it contains a #. The link is a web address on your Relay:

via relay add '<invite link>' --name office

via checks the Relay, creates a device key on this machine, registers the key with the Relay and saves the Relay under the name you gave:

🌐 Relay "relay.example.com" (…) found at https://relay.example.com
🔐 Device key generated at … (SHA256:…)
✅ Registered with the relay as device <host>-xxxxxx
✅ Saved as relay "office" and set as default.

The device key stays on this machine; only its public half goes to the Relay. The via CLI pins the Relay’s host key automatically when you enrol. The first Relay you add becomes your default. Now publish a port:

via expose 3000 myapp

It prints the address the Relay assigned. With basic auth on (the default) it also prints the username and password (Basic auth is on: username <user>, password <password>) and an Open: link with the login built in (https://<user>:<password>@<host>/). The Open: link appears only when basic auth is on; because it contains your login credentials, do not share it. With --auth=none there is no Open: line.

Whether you get the name you asked for depends on the Relay’s settings, see Publishing Services. Always use the URL it prints: never assume an exact hostname, as since Relay 0.62.6 an owner can give a person’s addresses a suffix.

List your Relays

via relay list

Shows a Relays table with the columns Name, Domain, Caps and Device key. An arrow marks your default Relay. Caps are the capabilities the Relay reports, as badges such as TCP or PTH. Device key is the shortened hash (SHA256:…) of this device’s key. With no Relay added yet, it prints:

No relays found. Enrol this device on a relay with: via relay add '<enrolment link>'

Show one Relay

via relay info office

Shows the Relay’s Domain, its SSH Host (host:port), the Device key hash and the Relay’s capabilities. A Names: line says how the Relay names your addresses: short (names as asked), suffixed with the suffix (such as suffixed (-nico)), or unknown. For now it may show unknown, because the Relay client that comes with the CLI cannot report it yet; a later CLI release will. Until then, use the URL via expose prints. Give the operator the key hash when they want to check which device on the Relay’s Devices page is yours (each device shows its Key).

Choose the default Relay

via relay set office

via expose uses the default Relay. To use another Relay you added for one command, pass --server <relay-name>, for example via expose 3000 --server home.

Replace the device key

via relay rotate-key office

via creates a new key, signs it with the current one and switches only after the Relay confirms. It then deletes the old key on this machine, and the Relay closes the open sessions of the old key straight away: restart what you were publishing (the CLI tells you). Do this when you think the key was copied, or as routine. via relay info office shows the new key hash.

If the Relay’s answer gets lost or it reports an error, both keys are kept. Run the command again, or finish it with --adopt-pending (use the new key) or --discard-pending (keep the old one).

Remove a Relay

via relay remove office

via first signs this device out at the Relay, then removes the Relay on this machine. If the Relay cannot be reached or refuses, nothing is removed and the command exits with status 1. --force removes it on this machine anyway, with a warning; the device key then stays approved on the Relay until the operator removes it under People › Users. On a Relay that does not let devices manage themselves, via removes it on this machine and tells you that the operator has to remove the device.

When your plan is full

When the Relay refuses a connection because of a plan limit, via says which limit, for example Connection limit reached or Bandwidth limit reached, with how much is used and allowed, and shows where to upgrade: the Relay’s own HTTPS address, or viaalink.com/relay#plans when it has none.