Skip to content

Runner setup

A runner is a machine you own that accepts RayRF jobs: install RayRF on it, license it against your account, open one TCP port, and keep the daemon running. This page is the box-side walkthrough. Driving runners from the desktop app is covered in Remote running.

Runner licensing is seatless. A Pro or Founding license key from the dashboard licenses page validates the runner against your account and signs a machine-bound token for every job, without consuming an activation seat. Run as many runners as you want, and your desktop installs keep their seats.

Linux

Install once, with the license key from the dashboard licenses page:

./RayRF-Studio-1.1.9-x86_64.AppImage serve --install --license-key RAYRF-XXXX-XXXX-XXXX-XXXX

Then start serving:

./RayRF-Studio-1.1.9-x86_64.AppImage serve

The runner validates the key, registers this machine's address to your account, and your other machines list it under Discover from account. On a GPU box pass --backend cuda with --install so jobs default to the GPU. Later starts are the same plain serve, because the configuration is stored.

Open the runner port so clients can reach it. Jobs move over a direct link to port 8787, which a host firewall or cloud security group often blocks by default. On a box running ufw that is sudo ufw allow 8787/tcp. On a cloud VM also open the port in the provider's security group.

To keep the runner alive across reboots, pass --autostart with --install. It writes a systemd unit into the state dir and prints the install command:

sudo cp /var/lib/rayrf/rayrf-runner.service /etc/systemd/system/ && sudo systemctl enable --now rayrf-runner

Windows

The same two steps, from the install folder (%LOCALAPPDATA%\Programs\RayRF Studio). rayrf resolves to the console launcher rayrf.com, which waits and streams output, and RayRF.exe is the windowed app.

.\rayrf serve --install --license-key RAYRF-XXXX-XXXX-XXXX-XXXX
.\rayrf serve

Open the runner port so clients can reach it, the same as on Linux. Windows Firewall blocks inbound connections by default, so a runner that registers with your account is still unreachable until port 8787 is allowed. From an Administrator PowerShell:

netsh advfirewall firewall add rule name="RayRF runner 8787" dir=in action=allow protocol=TCP localport=8787

On a cloud VM also open the port in the provider's security group. If the machine's network is set to Public, allow the rule on the Public profile (the command above covers all profiles).

To run at startup, register a Scheduled Task (or a service wrapper) that runs RayRF.exe serve --state-dir "C:\ProgramData\RayRF\runner". Passing --autostart with --install prints this hint with the resolved state dir.

By default the runner registers its own detected address. When that address is not what peers reach, pass the reachable endpoint yourself with --advertise HOST:PORT at install or serve time: on a NAT or portmapped host (a rented container, a port-forwarded home box) that is the external address and mapped port, which can differ from the listen port. Registration is metadata only. Jobs move over a direct TLS 1.3 link to the advertised address, so the port (default 8787) must be reachable through the firewall or cloud security group.

--advertise off skips account registration entirely. The runner then serves direct connections only, and clients add it by host, port, and fingerprint.

What each piece does

  • --install writes runner.json (name, owner, host, port, slots, backend, advertise, and the license key when one is resolved) and the identity into the state dir. Command-line flags always win over the stored values.
  • The state dir holds the identity, the configuration, and the durable job queue. It resolves from --state-dir, then the RAYRF_STATE_DIR environment variable, then the machine default (C:\ProgramData\RayRF\runner on Windows, /var/lib/rayrf on Linux when writable, else ~/.rayrf/runner). Keep every invocation on one state dir: a new dir mints a new identity, and clients that pinned the old fingerprint refuse the new one.
  • --backend cuda or --backend cpu sets the default engine for jobs that do not pin one.
  • The owner defaults to the license key's account: that account gets submit and control, and every other connection is view-only. --owner overrides the account, and --open-owner grants control to any peer on a trusted LAN. --allow-unlicensed skips the license gate entirely for closed-network use.
  • --slots sets how many jobs run concurrently (default 1).

Verify and connect

--install prints the runner's identity fingerprint. Give it to anyone who will connect, or compare it in the trust prompt on first connect. Either way the pin is stored, and a later key change on the runner is refused.

rayrf serve --health                     status JSON on the box
rayrf remote info --host HOST --fingerprint FP     from a client

A client that connects by CLI stores the fingerprint it first trusted in ~/.rayrf/pins.json (%USERPROFILE%\.rayrf\pins.json on Windows). If a runner's key later changes (wiping its state dir mints a new identity), the next connection is refused. After verifying the new fingerprint out of band, reconnect with --fingerprint NEWFP, or remove that runner's host:port entry from the pins file and reconnect to trust it fresh. In the desktop app, remove the stale machine and re-add or rediscover it, then confirm the new fingerprint at the trust prompt.

The runner also has a windowed form, rayrf serve --window, which is what the desktop app's "Use this computer as a runner" button starts: the same daemon with a status window showing account, address, fingerprint, discovery state, and live job counts.

Submit work from the desktop app (Remote running) or from the CLI with the rayrf remote verbs (CLI reference).