Runner autoalojado

Un runner autoalojado es un pequeño agente, subaya-runner, que ejecuta builds de Subaya en una máquina que tú controlas en lugar de en la nube de Subaya. Úsalo cuando la cadena de herramientas ya esté instalada en esa máquina — por ejemplo, una instalación de Quartus con licencia — o cuando el build deba ejecutarse en tu propio hardware.

El runner se conecta hacia fuera con Subaya mediante un WebSocket seguro. No necesita ningún puerto de entrada, VPN ni IP pública. Subaya le envía los builds por esa conexión.

Un runner ejecuta builds para su propia organización, usando comandos que la plataforma derivó del proyecto de esa organización. Un build se ejecuta con los privilegios del runner en una máquina de tu propiedad — el mismo modelo de confianza que un runner autoalojado de GitHub. No es un sandbox.

Requisitos

• Linux en x86_64. Otras plataformas llegarán más adelante.
• HTTPS saliente (puerto 443) hacia subaya-dev.com.
• Las herramientas que necesitan tus builds, instaladas y en el PATH del usuario que ejecuta el runner. El runner informa de lo que encuentra; no instala nada.
• Opcional: Docker o Podman, para builds cuya receta indica una imagen de contenedor.

Instalación

En la consola, abre Settings → Runners y elige Add runner. Asigna un nombre al runner y Subaya mostrará tres comandos con un token de registro de un solo uso ya incluido. El token funciona una vez y caduca a la 1 hora.

Descarga y descomprime el runner:

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

Configúralo. Esto intercambia el token de registro por la credencial propia del runner y genera un par de claves que nunca sale de la máquina:

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

Ejecútalo en primer plano:

./subaya-runner run

Para que siga funcionando tras reiniciar, instálalo en su lugar como servicio de systemd:

./subaya-runner install-service

Si lo ejecutas con tu propio usuario, instala un servicio de usuario de systemd; si lo ejecutas como root, uno de todo el sistema. Un servicio de usuario se detiene al cerrar sesión, salvo que actives el lingering para tu cuenta:

sudo loginctl enable-linger "$USER"

En pocos segundos el runner aparece como online en Settings → Runners, con las herramientas y versiones que detectó.

Enviarle un build

Selecciona un runner por su nombre con --runner:

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

Antes de aceptar el build, Subaya comprueba que el runner haya informado de todas las herramientas que necesita. Si el runner está desconectado, el build espera en la cola y comienza cuando el runner se vuelve a conectar.

Qué se registra

Al iniciar un build, el runner informa de la cadena de herramientas exacta que midió: para cada herramienta, la cadena de versión, la ruta y el SHA-256 de su binario. Esa cadena de herramientas medida — no la que pidió el proyecto — es la que registra la ejecución.

Si el proyecto fija explícitamente una versión de herramienta (por ejemplo con suya tools set quartus-pro 26.1.1) y la versión instalada en el runner no coincide, el build se rechaza y falla con toolchain_pin_mismatch. No se ejecuta nada. Sin una versión fijada explícitamente, se usa la versión instalada en el runner.

Revocar un runner

En Settings → Runners, elige Revoke en el runner. La revocación es inmediata: la credencial del runner deja de funcionar, su conexión se cierra, no se le envían más builds y un build en curso falla. La revocación no se puede deshacer — para volver a usar la máquina, añádela como un runner nuevo y ejecuta ./subaya-runner configure --replace con el nuevo token.

Para quitar también el servicio de la máquina:

./subaya-runner uninstall-service

Solución de problemas

El runner aparece desconectado. Comprueba que el proceso o el servicio esté en marcha y que la máquina pueda alcanzar subaya-dev.com en el puerto 443:

./subaya-runner status

El runner se reconecta solo tras una pérdida de red. Un build que se estaba ejecutando cuando se cortó la conexión falla con runner_disconnected; vuelve a lanzarlo.

El runner termina con «upgrade required». El runner es más antiguo que la versión mínima que acepta Subaya. Descarga la última versión con el comando de descarga anterior, reemplaza el binario y vuelve a iniciarlo. Su configuración se conserva.

El build se rechaza con 422 runner_missing_tool. El runner no informó de una herramienta que el build necesita. Instala la herramienta, asegúrate de que esté en el PATH del runner y reinícialo para que vuelva a informar de su cadena de herramientas. El error indica la herramienta que falta.

El token de registro se rechaza. Los tokens son de un solo uso y caducan a la hora. Crea uno nuevo con Add runner.

Próximos pasos

• Espacios de trabajo y proyectos — dónde viven los builds.
• Facturación y uso — cómo se mide el cómputo en la nube.