Runner auto-hospedado

Um runner auto-hospedado é um pequeno agente, subaya-runner, que executa builds do Subaya em uma máquina que você controla, em vez de na nuvem do Subaya. Use-o quando a toolchain já estiver instalada nessa máquina — por exemplo, uma instalação licenciada do Quartus — ou quando o build precisar acontecer no seu próprio hardware.

O runner se conecta de saída ao Subaya por um WebSocket seguro. Ele não precisa de porta de entrada, VPN nem IP público. O Subaya envia os builds a ele por essa conexão.

Um runner executa builds para a sua própria organização, usando comandos que a plataforma derivou do projeto dessa organização. Um build é executado com os privilégios do runner em uma máquina que pertence a você — o mesmo modelo de confiança de um runner auto-hospedado do GitHub. Não é um sandbox.

Requisitos

• Linux em x86_64. Outras plataformas virão depois.
• HTTPS de saída (porta 443) para subaya-dev.com.
• As ferramentas de que seus builds precisam, instaladas e no PATH do usuário que executa o runner. O runner informa o que encontra; ele não instala nada.
• Opcional: Docker ou Podman, para builds cuja receita indica uma imagem de contêiner.

Instalação

No console, abra Settings → Runners e escolha Add runner. Dê um nome ao runner e o Subaya mostra três comandos com um token de registro de uso único já preenchido. O token funciona uma vez e expira em 1 hora.

Baixe e descompacte o 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

Configure-o. Isso troca o token de registro pela credencial própria do runner e gera um par de chaves que nunca sai da máquina:

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

Execute-o em primeiro plano:

./subaya-runner run

Para mantê-lo em execução após reinicializações, instale-o como serviço do systemd:

./subaya-runner install-service

Executado com o seu próprio usuário, isso instala um serviço de usuário do systemd; executado como root, instala um serviço de todo o sistema. Um serviço de usuário para quando você sai da sessão, a menos que o lingering esteja ativado para a sua conta:

sudo loginctl enable-linger "$USER"

Em poucos segundos, o runner aparece como online em Settings → Runners, com as ferramentas e versões que detectou.

Enviar um build para ele

Direcione um runner pelo nome com --runner:

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

Antes de aceitar o build, o Subaya verifica se o runner informou todas as ferramentas de que o build precisa. Se o runner estiver offline, o build aguarda na fila e começa quando o runner se reconectar.

O que é registrado

Quando um build começa, o runner informa a toolchain exata que mediu: para cada ferramenta, a string de versão, o caminho e o SHA-256 do binário. Essa toolchain medida — e não a que o projeto pediu — é o que a execução registra.

Se o projeto fixar explicitamente uma versão de ferramenta (por exemplo com suya tools set quartus-pro 26.1.1) e a versão instalada no runner não corresponder, o build é recusado e falha com toolchain_pin_mismatch. Nada é executado. Sem uma versão fixada explicitamente, a versão instalada no runner é usada.

Revogar um runner

Em Settings → Runners, escolha Revoke no runner. A revogação vale imediatamente: a credencial do runner deixa de funcionar, a conexão é encerrada, nenhum outro build é enviado a ele e um build em andamento falha. A revogação não pode ser desfeita — para usar a máquina novamente, adicione-a como um novo runner e execute ./subaya-runner configure --replace com o novo token.

Para remover também o serviço da máquina:

./subaya-runner uninstall-service

Solução de problemas

O runner aparece offline. Verifique se o processo ou serviço está em execução e se a máquina consegue alcançar subaya-dev.com na porta 443:

./subaya-runner status

O runner se reconecta sozinho após uma perda de rede. Um build que estava em execução quando a conexão caiu falha com runner_disconnected; execute-o novamente.

O runner sai com “upgrade required”. O runner é mais antigo que a versão mínima aceita pelo Subaya. Baixe a versão mais recente com o comando de download acima, substitua o binário e inicie-o novamente. A configuração é mantida.

O build é rejeitado com 422 runner_missing_tool. O runner não informou uma ferramenta de que o build precisa. Instale a ferramenta, confirme que ela está no PATH do runner e reinicie o runner para que ele informe sua toolchain novamente. O erro indica a ferramenta que falta.

O token de registro é rejeitado. Os tokens são de uso único e expiram em uma hora. Crie um novo com Add runner.

Próximos passos

• Workspaces e projetos — onde os builds ficam.
• Faturamento e uso — como a computação em nuvem é medida.