Skip to content
Subaya

Self-hosted runner

A self-hosted runner is a small agent, subaya-runner, that runs Subaya builds on a machine you control instead of in the Subaya cloud. Use it when the toolchain is already installed on that machine — for example a licensed Quartus install — or when the build has to happen on your own hardware.

The runner connects out to Subaya over a secure WebSocket. It needs no inbound port, no VPN, and no public IP. Subaya pushes builds to it over that connection.

A runner executes builds for its own organisation, using commands the platform derived from that organisation’s project. A build runs with the runner’s privileges on a machine you own — the same trust model as a GitHub self-hosted runner. It is not a sandbox.

Requirements

Section titled “Requirements”
  • Linux on x86_64. Other platforms come later.
  • Outbound HTTPS (port 443) to subaya-dev.com.
  • The tools your builds need, installed and on the PATH of the user that runs the runner. The runner reports what it finds; it installs nothing.
  • Optional: Docker or Podman, for builds whose recipe names a container image.

Install

Section titled “Install”

In the console, open Settings → Runners and choose Add runner. Give the runner a name and Subaya shows three commands with a one-time enrolment token already filled in. The token works once and expires after 1 hour.

Download and unpack the runner:

Terminal window
curl -fsSL -o subaya-runner.tar.gz https://subaya-dev.com/cli/runner/latest/subaya-runner_linux_amd64.tar.gz && tar xzf subaya-runner.tar.gz

Configure it. This exchanges the enrolment token for the runner’s own credential and generates a key pair that never leaves the machine:

Terminal window
./subaya-runner configure --url https://subaya-dev.com --token srt_... --name 'lab-quartus-01'

Run it in the foreground:

Terminal window
./subaya-runner run

To keep it running across reboots, install it as a systemd service instead:

Terminal window
./subaya-runner install-service

Run as your own user, this installs a systemd user service; run as root, it installs a system-wide one. A user service stops when you log out unless lingering is enabled for your account:

Terminal window
sudo loginctl enable-linger "$USER"

Within a few seconds the runner shows as online in Settings → Runners, with the tools and versions it detected.

Send a build to it

Section titled “Send a build to it”

Target a runner by name with --runner:

Terminal window
suya build <app> --source . --runner lab-quartus-01 --wait

Subaya checks that the runner reported every tool the build needs before it accepts the build. If the runner is offline, the build waits in the queue and starts when the runner reconnects.

What gets recorded

Section titled “What gets recorded”

When a build starts, the runner reports the exact toolchain it measured: each tool’s version string, path, and the SHA-256 of its binary. That measured toolchain — not what the project asked for — is what the run records.

If the project pins a tool version explicitly (for example with suya tools set quartus-pro 26.1.1) and the runner’s installed version does not match the pin, the build is refused and fails with toolchain_pin_mismatch. Nothing is executed. Without an explicit pin, the runner’s installed version is used.

Revoke a runner

Section titled “Revoke a runner”

In Settings → Runners, choose Revoke on the runner. Revoking takes effect immediately: the runner’s credential stops working, its connection is closed, no further builds are sent to it, and a build it is running fails. Revoking cannot be undone — to use the machine again, add it as a new runner and run ./subaya-runner configure --replace with the new token.

To remove the service from the machine as well:

Terminal window
./subaya-runner uninstall-service

Troubleshooting

Section titled “Troubleshooting”

The runner shows offline. Check that the process or service is running and that the machine can reach subaya-dev.com on port 443:

Terminal window
./subaya-runner status

The runner reconnects on its own after network loss. A build that was running when the connection dropped fails with runner_disconnected; run it again.

The runner exits with “upgrade required”. The runner is older than the minimum version Subaya accepts. Download the latest release with the download command above, replace the binary, and start it again. Its configuration is kept.

The build is rejected with 422 runner_missing_tool. The runner did not report a tool the build needs. Install the tool, make sure it is on the runner’s PATH, and restart the runner so it reports its toolchain again. The error names the missing tool.

The enrolment token is rejected. Tokens are single-use and expire after one hour. Create a new one with Add runner.

Next steps

Section titled “Next steps”