Viaalink Viaalink
EN NL
Start Last verified:

Quick Start

Your first published address in minutes with your own Viaalink Relay — install the Relay, approve your key, publish a local port and open the address.

What you will have at the end

A web app running on your own computer — here on localhost:3000 — reachable by anyone at an HTTPS address on your own domain, such as https://k3x.relay.example.com. No port opened on your computer, no router rule for it.

Note: The Relay and via downloads are published with the first release. Until then, ask contact@viaalink.com for early access. Every step below works the same once you have the files.

You need:

  • a machine for the Relay that stays on (a Linux server or VPS, a NAS, or a PC) — see Where It Runs;
  • a domain name you control, here example.com;
  • the computer you want to publish from, with OpenSSH (already on Linux, macOS and current Windows) or the Viaalink CLI.

Step 1: Install the Relay

Follow the guide for your machine: Linux, Docker, ASUSTOR NAS, Synology or QNAP, Windows or macOS. A Relay on Windows or macOS works while you are logged in; for an address that is always up, use a machine that stays on.

Then point two DNS records at the Relay machine, so it can hand out addresses and get HTTPS certificates for them:

NamePoints to
relay.example.comthe Relay’s public IP address
*.relay.example.comthe same address

Details, including AAAA records and Cloudflare: DNS Configuration. Open the ports the Relay needs — at least 2222, 80 and 443 — as described in Requirements and Network Architecture.

Step 2: Approve your key

The Relay only accepts devices whose SSH key you approved. On the computer you publish from, create a key if you do not have one yet:

bash
ssh-keygen -t ed25519

Approve its public half (~/.ssh/id_ed25519.pub) on the Relay, in one of two ways:

  • In the browser: open the setup dashboard (/_relay/dashboard), log in with the setup code, go to the Users tab and paste the key.
  • As a file: copy the .pub file into the Relay’s public keys folder (on Linux /var/lib/viaalink-relay/pubkeys/). The Relay picks it up within a fraction of a second, without a restart.

More ways, such as invites, are on Access Control and Security.

Step 3: Publish a local port

Start your app on port 3000, then connect it to the Relay. Pick one.

With OpenSSH — nothing to install:

bash
ssh -p 2222 -R app:80:localhost:3000 relay.example.com

With the Viaalink CLI:

bash
via publish 3000

The Relay answers with the address it assigned. With OpenSSH you see the Relay’s welcome text, for example:

text
HTTP: http://k3x.relay.example.com
HTTPS: https://k3x.relay.example.com

By default the Relay picks a random three-letter name and gives a new one on every reconnect, even when you ask for app. To let devices keep the name they ask for, the Relay operator turns off --bind-random-subdomains; see Publishing Services.

Keep this command running: the address works for as long as the connection is open.

Step 4: Open the address

Open https://k3x.relay.example.com (your own address) in any browser, on any network. A visitor needs nothing installed.

To keep strangers out, add a password to the link or limit who may visit — see Access Control and Security.

If it does not work

  • Permission denied (publickey) — the Relay does not know your key yet: repeat step 2.
  • The command hangs, then times out — your computer cannot reach port 2222 on the Relay.
  • The page shows 404 Not Found — the address is not published right now, or it changed after a reconnect. Read the address from the latest output.
  • The page shows 502 Bad Gateway — the Relay reached your computer, but nothing answers on localhost:3000.

More on Troubleshooting.

Next