Runtimes e Ambientes

Onde os agentes executam. Um runtime tem uma instalação por ambiente (Desenvolvimento, Homologação e Produção): cadastre o runtime, instale cada instalação numa máquina com a chave de ativação dela e controle o comportamento de execução de cada uma.

O que é um Runtime

O runtime é o aplicativo multiplataforma do browserMate que executa os agentes. Ele controla o navegador, executa os scripts e reporta logs e evidências de volta à plataforma. Na tela Meus Runtimes, um Runtime é o destino de execução que você nomeia e escolhe no agente, por exemplo Nota Fiscal Automation. Ele se organiza em quatro peças:

Na execução, o runtime do agente e o ambiente do agente apontam juntos para uma instalação, e é nela que o agente roda. Um agente em Produção no runtime Nota Fiscal Automation roda na instalação de Produção desse runtime. Se ele vai para Homologação, passa a rodar na instalação de Homologação do mesmo runtime, sem trocar o runtime escolhido.

Com isso você consegue:

• Usar uma máquina só para os três ambientes, que é como todo runtime novo começa
• Desenvolver e homologar no seu notebook e rodar Produção num servidor dedicado, com o mesmo runtime escolhido no agente
• Levar um agente de Homologação para Produção trocando só o ambiente
• Distribuir a carga entre vários runtimes (veja Balancear Carga dos Agentes)
• Ver o status online/offline de cada instalação na tela Meus Runtimes

Cadastrar um runtime

Em Meus Runtimes, clique em Novo Runtime e preencha:

O mesmo formulário existe no painel Runtimes do Agent Builder, para cadastrar sem sair do agente.

Instalações por ambiente

Cada linha do campo Instalações por ambiente tem uma destas opções:

Um runtime novo começa com uma instalação para os três ambientes: Desenvolvimento em Nova instalação, Homologação e Produção em Compartilhar com Desenvolvimento. É a mesma ideia de uma credencial do Cofre com valor único. Quem precisa de máquinas separadas troca a posição para Nova instalação, por exemplo Produção, para rodar Produção num servidor e o resto no notebook.

Abaixo das três linhas, o formulário resume o que o Salvar vai fazer, por exemplo Vai gerar 1 chave de ativação nova (instalação de Desenvolvimento), com o seu agent.config.json. Ao editar, uma posição que deixa de ter instalação própria aparece como A instalação atual de Produção será removida e a chave de ativação dela para de valer.

Trocar para Nova instalação a posição de um ambiente que já tinha instalação é trocar de máquina: as execuções daquele ambiente passam para a instalação nova, que começa com a mesma configuração de execução da anterior (fila, execuções ao mesmo tempo, fluxo offline) e só recebe execuções depois que o agent.config.json novo for instalado. O resumo avisa: As execuções de Produção passam para a instalação nova, com a mesma configuração de execução da atual, e só rodam depois que o agent.config.json novo for instalado na máquina.

O Salvar fica bloqueado, com o motivo no resumo, quando:

• uma posição reaproveita um ambiente que ficou sem instalação própria;
• nenhuma posição tem instalação: O runtime precisa de pelo menos uma instalação.;
• as instalações novas passam do limite do plano (veja Quantos runtimes o plano permite).

Um runtime com uma só instalação atende com ela os ambientes em que ela está escolhida, como os três de um runtime novo. Editar um runtime mantém o mesmo ID, então agentes, agendamentos e integrações que apontam para ele continuam valendo depois de separar as instalações.

O card do runtime

Na tela Meus Runtimes e no painel Runtimes do Agent Builder, cada runtime aparece num card. No alto ficam o nome e os botões Editar e Remover (o ícone da lixeira). Logo abaixo vem o ID para a API, com botão de cópia: é o ID do runtime, usado na API. Em seguida, em Instalações, há um bloco por ambiente, marcado na cor dele (Desenvolvimento azul, Homologação âmbar, Produção verde). O bloco de um ambiente com instalação própria mostra:

• LIVE ou OFFLINE, ao lado do nome do ambiente, o status da instalação;
• a máquina e a versão, informadas pela própria instalação quando ela conecta, no formato máquina - versão. Sem conexão, aparece Ainda não conectado ou Desconectado - última versão seguido da última versão vista;
• a chave de ativação (Chave no painel), com botão de cópia;
• o botão agent.config.json, que baixa o arquivo daquela instalação;
• o botão Configurar, que abre o comportamento de execução daquela instalação.

Um ambiente que reaproveita a instalação de outro ocupa uma linha só, com Compartilha com e o ambiente; um ambiente sem instalação mostra Sem instalação, com borda tracejada. Uma instalação acima do limite do plano mostra Suspensa pelo plano ao lado do status.

Remover uma instalação ou o runtime

Para remover uma instalação, edite o runtime e troque a posição dela para Sem instalação ou Compartilhar com outro ambiente. Para remover tudo, use Remover no card: as instalações do runtime são removidas e as chaves de ativação param de valer.

A plataforma recusa a remoção quando algum agente ou agendamento usa aquele runtime no ambiente que ficaria sem instalação, e lista quem usa. Por exemplo: O runtime Nota Fiscal Automation não foi salvo: o agente "Emitir NF" roda nele, e o agendamento "Fechamento diário" aponta para ele, em Produção. Sem instalação nesse ambiente, essas execuções seriam recusadas. Troque o runtime deles antes. Agendamento desligado não entra nessa conta: ao ser religado, ele é conferido de novo (veja Agendamento).

Remover o runtime também é recusado enquanto uma etapa marca esse runtime na Distribuição entre runtimes (na versão publicada de qualquer agente que o alcança): O runtime Nota Fiscal Automation não foi removido: a etapa "Emitir do agente Lote NF" distribui execuções nele (Distribuição entre runtimes). Desmarque-o na Distribuição do processamento dessa etapa antes. Tirar só a instalação de um ambiente não é recusado por causa da distribuição: nesse ambiente o runtime fica de fora da distribuição, e os outros runtimes marcados recebem.

A remoção também é recusada enquanto a instalação que sai tem execuções na fila ou rodando, porque a fila dela seria perdida: O runtime Nota Fiscal Automation não foi salvo: a instalação de Produção tem 3 execuções na fila ou rodando. Espere terminarem antes de tirar essa instalação, ou a fila dela é perdida.

Ambientes: Desenvolvimento, Homologação e Produção

Todo agente está em um ambiente: Desenvolvimento, Homologação ou Produção. Um agente novo, clonado ou importado começa em Desenvolvimento, e um agente que nunca teve ambiente escolhido está em Produção. Esse único ambiente decide duas coisas na execução:

• qual instalação do runtime roda o agente: a que o runtime tem naquele ambiente;
• qual valor do Cofre de Senhas é usado, quando a credencial tem valores por ambiente. Uma credencial com valor único vale em todos os ambientes, ninguém precisa digitar o mesmo valor três vezes. Uma credencial por ambiente sem valor no ambiente do agente é erro: a plataforma nunca usa o valor de outro ambiente.

Depois da execução, o ambiente também decide onde ela é contada: o Analytics soma só as execuções de Produção (Desenvolvimento e Homologação são teste e não entram nos ganhos), enquanto o Control Room, a Trilha de Auditoria e o consumo de créditos contam todos os ambientes.

No Agent Builder, runtime e ambiente são dois controles separados, lado a lado na segunda fileira do cabeçalho: o campo RUNTIME escolhe onde o agente roda, e os botões Dev, Homolog e Prod escolhem em que ambiente. O ambiente é do agente inteiro: decide qual instalação do runtime escolhido roda o agente (cada instalação tem a própria chave de ativação) e qual valor do Cofre é usado.

O campo RUNTIME

Fica na segunda fileira do cabeçalho. Lista só runtimes, pelo nome e em ordem alfabética, com a Sandbox no fim, no grupo Runtime limitado e para testes. Todos os runtimes se deixam escolher, tenham ou não instalação no ambiente do agente. Uma conta com os runtimes Nota Fiscal Automation e VPS GCP vê a lista assim:

• Nota Fiscal Automation
• VPS GCP
• Sandbox

Escolher um runtime que não tem instalação no ambiente em que o agente está leva o agente junto para um ambiente que o runtime tem (Produção primeiro, depois Homologação, depois Desenvolvimento), numa troca só, com o aviso Agente em Produção: o runtime VPS GCP não tem instalação em Desenvolvimento. Com o agente publicado, ir para Produção pede a confirmação de sempre; cancelar mantém o runtime anterior. Uma troca de runtime feita pelo Copilot segue a mesma regra de levar o agente junto, na versão em desenvolvimento e sem a confirmação de Produção (o aviso diz para qual ambiente o agente foi), e o cabeçalho do editor se atualiza. Passar o mouse sobre o campo mostra o nome inteiro do runtime escolhido.

Os botões Dev, Homolog e Prod

Logo ao lado do campo RUNTIME ficam três botões juntos: Dev (Desenvolvimento), Homolog (Homologação) e Prod (Produção). O botão do ambiente do agente fica preenchido com a cor do ambiente: azul em Desenvolvimento, âmbar em Homologação e verde em Produção. A borda de baixo do cabeçalho mostra uma linha fina na mesma cor, para o ambiente ficar à vista enquanto você trabalha no fluxo.

Os botões dos ambientes em que o runtime escolhido no campo RUNTIME não tem instalação ficam desabilitados, e passar o mouse mostra o motivo: o runtime X não tem instalação neste ambiente. Para usar esse ambiente, dê a ele uma instalação no runtime (em Meus Runtimes) ou escolha outro runtime. Do mesmo modo, o botão de um ambiente cuja instalação está suspensa pelo plano fica desabilitado, com a dica a instalação deste ambiente está suspensa pelo plano. O botão do ambiente atual do agente nunca fica desabilitado por isso: nesse caso quem avisa é a pendência.

Uma pequena marca amarela num botão quer dizer que uma credencial do cofre usada no fluxo não tem valor naquele ambiente; a dica diz falta credencial do Cofre neste ambiente, e a pendência diz qual credencial falta. Esse botão continua escolhível: é escolhendo o ambiente que você vê o que precisa cadastrar.

Clicar em outro botão troca o ambiente do agente. Os três botões ficam desabilitados, com o motivo ao passar o mouse, nas mesmas situações em que o campo RUNTIME trava: outra pessoa está desenvolvendo o processo, você não tem permissão de edição, ou o agente é de outro dono (O ambiente é definido pelo dono deste agente).

Com a Sandbox escolhida no campo RUNTIME, ou com o campo em Selecione... (nenhum runtime), nenhum botão fica marcado, os três ficam desabilitados e a linha do cabeçalho fica cinza: a Sandbox não usa ambiente nem Cofre, e sem runtime não há instalação para o ambiente escolher. O ambiente gravado no agente não muda e volta a aparecer quando um runtime é escolhido.

Existe uma só versão publicada, e publicar é o ato de dizer "terminei". Numa versão em desenvolvimento, a escolha do runtime e do ambiente vale para o debug e vai junto na publicação. Com o agente publicado, trocar o runtime ou o ambiente vale na hora para as próximas execuções e não gera versão nova: a versão só sobe quando o fluxo muda. Ir para Produção com o agente publicado pede uma confirmação, Mudar para Produção, que avisa que as próximas execuções usarão o runtime escolhido e as credenciais de Produção, por exemplo As próximas execuções usarão o runtime Nota Fiscal Automation e as credenciais de Produção. As outras trocas valem na hora, sem perguntar.

Uma sequência comum: criar a versão, depurar em Desenvolvimento e Homologação sem gerar versão nenhuma, publicar em Homologação para deixar o agendamento rodando uns dias, e, quando estiver convencido, abrir o agente e trocar para Produção. Continua sendo a mesma versão.

Ao publicar, a plataforma confere no servidor as pendências de runtime, ambiente e agendamento, venha a publicação de onde vier (inclusive de um agente compartilhado editado por convidado, ou de uma troca de runtime feita pelo Copilot). A publicação é recusada, com o motivo num aviso no editor, quando:

• o agente não tem runtime: Escolha o runtime do agente antes de publicar.;
• o runtime gravado não existe mais na conta do dono do agente, ou saiu do alcance dele: O runtime gravado neste agente não existe mais na conta do dono (ou saiu do alcance dele). Escolha outro runtime antes de publicar.;
• o runtime não tem instalação no ambiente da versão em desenvolvimento: O runtime X não tem instalação em Y. Escolha outro runtime, ou cadastre uma instalação nesse ambiente.;
• a instalação desse ambiente está suspensa pelo plano (a mensagem é a de Quantos runtimes o plano permite);
• um agendamento ligado do agente fica sem instalação no runtime e no ambiente da versão em desenvolvimento (a mesma mensagem da pendência de agendamento).

Um agente chamado por outro (Chamar Agente) roda no próprio ambiente, não no do agente que chamou. Cada agente carrega o seu. O Meus Insights mostra o ambiente de cada execução.

Quantos runtimes o plano permite

O número de runtimes é um teto da empresa inteira, não de cada pessoa: os runtimes de todos os membros somam contra o mesmo limite. Na conta, cada instalação conta como um runtime. Um runtime com Desenvolvimento, Homologação e Produção em instalações separadas conta 3; uma instalação reaproveitada por outro ambiente (Compartilhar com) conta uma vez só. O topo da tela Meus Runtimes mostra quanto já está em uso, no formato 2 de 5 runtimes em uso na empresa, para você saber onde está antes de criar mais uma instalação.

O formulário recusa o Salvar quando as instalações novas passam do teto e explica a conta, por exemplo: O plano permite 5 runtimes na empresa e 4 já estão em uso: cabem mais 1, e este runtime pede 2. Reaproveite uma instalação entre ambientes ("Compartilhar com ...") ou remova um runtime que não usa mais. Uma instalação removida na mesma edição libera a vaga dela. A plataforma confere o teto de novo ao gravar e recusa o que passar dele.

Quando a empresa muda para um plano menor, as instalações que passam do novo teto são suspensas, nunca excluídas. A ordem protege Produção: saem primeiro as instalações de Desenvolvimento, depois as de Homologação, e as de Produção ficam. Uma instalação que atende Produção conta como Produção, e dentro do mesmo ambiente fica a mais antiga. A instalação suspensa mostra Suspensa pelo plano no card, continua cadastrada com a configuração e a chave de ativação intactas, não aceita ativação e não ocupa vaga. Ela volta quando a empresa passa a um plano que a comporte (troca de plano ou confirmação de pagamento); remover outra instalação não a reativa. O mesmo vale para as instalações de um membro que ficou sem acesso ativo por causa do plano: elas saem da contagem enquanto ele estiver nessa situação.

Toda execução que entraria numa instalação suspensa é recusada na entrada, venha de onde vier (execução manual, API, webhook, agendamento, debug, agente chamado por outro): A instalação NOME está suspensa pelo plano: o plano da empresa não comporta todas as instalações de runtime. Faça upgrade do plano, ou escolha outro runtime. Na API o erro é INVALID_ENVIRONMENT (400). Na Distribuição entre runtimes, a instalação suspensa fica de fora e os outros runtimes recebem; o log do agente registra instalação suspensa pelo plano, e o painel da etapa mostra o runtime com suspensa pelo plano · não recebe. No editor, o botão desse ambiente fica desabilitado e, se é o ambiente do agente, a pendência diz qual instalação está suspensa.

Baixar e configurar o runtime

O runtime não tem instalador. É um pacote .zip pronto para rodar. O fluxo é: baixar, configurar, abrir.

1. Com o runtime já cadastrado (seção Cadastrar um runtime acima), no Menu, acesse Runtime dos Agentes e baixe o pacote .zip do seu sistema operacional.
2. Extraia o .zip numa pasta. No card do runtime, em Instalações, no bloco do ambiente que esta máquina vai atender, clique em agent.config.json para baixar o arquivo já preenchido e salve-o nessa mesma pasta, substituindo o que veio no pacote (seção Ativação do runtime a seguir).
3. Abra o executável. Não há instalador nem login, é rodar direto.
4. O runtime conecta-se à plataforma, e a instalação aparece como LIVE em Meus Runtimes, com a máquina e a versão.

Um runtime com mais de uma instalação repete esses passos em cada máquina, cada uma com o agent.config.json da sua instalação.

Cenário conhecido: aviso do SmartScreen no Windows

Ao abrir o browsermate.exe pela primeira vez no Windows, é esperado que o Microsoft Defender SmartScreen exiba um aviso antes de deixar o executável rodar. Isso acontece porque o binário ainda não tem um certificado de assinatura de código reconhecido pela Microsoft. Não é um indício de problema no arquivo baixado.

1. Ao abrir o browsermate.exe, aparece a tela "O Windows protegeu o computador".
2. Clique em Mais informações. O aviso se expande e mostra o nome do arquivo (browsermate.exe) e o botão Executar assim mesmo.
3. Clique em Executar assim mesmo para seguir com a abertura. O runtime inicia normalmente a partir daí.

Ativação do runtime (agent.config.json)

O que liga a máquina à sua conta e a uma instalação do runtime é o arquivo agent.config.json, localizado na pasta onde você extraiu o .zip do runtime:

{
  "key_activation": "<chave de ativação do runtime>",
  "user_token":     "<seu token de usuário>",
  "ui_socket_url":  "https://app.browsermate.io",
  "execution-mode": "console",
  "startup-notice": true,
  "keep-session-active": false,
  "ip-preference":  "ipv4"
}

Na inicialização, o runtime envia a chave de ativação e o token ao servidor, que os valida e devolve uma credencial temporária exclusiva daquela sessão. O runtime nunca opera com acesso além do necessário para executar os agentes. Depois de editar o arquivo, reinicie o runtime para aplicar.

Executar em segundo plano (bandeja do Windows)

{
  "key_activation": "<chave de ativação do runtime>",
  "user_token":     "<seu token de usuário>",
  "ui_socket_url":  "https://app.browsermate.io",
  "execution-mode": "background",
  "startup-notice": true
}

Como nada abre na tela nesse modo, o runtime confirma que subiu: aparece uma caixa de mensagem do Windows dizendo browserMate Runtime está rodando em background. Processo ativo na bandeja. Ela não interrompe nada, a ativação do agente segue acontecendo enquanto ela estiver na tela. Sai com um clique em OK, e também se fecha sozinha depois de um minuto, para nunca ficar parada na tela de uma máquina sem ninguém por perto. É uma caixa diferente do aviso de que o runtime já está rodando, que aparece quando o executável é aberto uma segunda vez.

Para iniciar calado, ponha "startup-notice": false no arquivo. Isso é recomendado quando o runtime sobe sozinho junto com o Windows, ou quando ele fica num servidor sem ninguém na frente da tela: nos dois casos a confirmação não tem quem leia. Quando é uma pessoa que abre o runtime, deixe true, porque é essa caixa que diz a ela que o serviço está no ar. O padrão é confirmar: campo ausente, arquivo gerado antes desta opção existir, valor escrito errado ou arquivo com erro de digitação mantêm o aviso, nunca calam o runtime por acidente.

O ícone da bandeja tem duas opções: Ver logs, que abre no programa de texto padrão do Windows o arquivo de log local dessa execução em segundo plano (esse arquivo só existe no modo background, já que no modo console o próprio console já mostra tudo ao vivo), e Sair, que encerra o processo.

Essa opção só existe no Windows. No Mac e no Linux, o campo é ignorado: o runtime sempre abre em console, registrando no log a mensagem Background nativo não suportado neste sistema operacional.

Manter a sessão ativa em servidor remoto (Windows)

Quando o runtime roda num servidor ou numa máquina virtual acessada por Área de Trabalho Remota (RDP), fechar a janela da conexão sem sair do Windows deixa a sessão desconectada. Ela continua viva e o runtime continua executando, mas o Windows deixa de ter uma tela ativa. Programas que dependem do desktop deixam de funcionar até alguém entrar de novo. O caso típico são os módulos de segurança de bancos, como o Warsaw do Banco do Brasil, que o navegador não reconhece enquanto a sessão está desconectada.

Com "keep-session-active": true, o runtime prepara o Windows para manter a sessão ativa, sem nenhum script a instalar ou manter:

• cria uma tarefa agendada do Windows, executada pela conta do sistema a cada minuto, chamada browserMate-KeepSessionActive-<usuário>. Quando a sessão do usuário que roda o runtime fica desconectada, a tarefa a move para o console da máquina, o que a mantém ativa sem ninguém conectado;
• zera os tempos limite do RDP (sessão desconectada, ociosa e conectada), para o Windows não encerrar a sessão depois de algumas horas. Os valores anteriores são guardados;
• põe Desligar o monitor e Suspender em "Nunca" no plano de energia ativo, na tomada e na bateria. Com o monitor desligado, o Windows para de desenhar a tela da sessão, e o programa do banco pode deixar de ser reconhecido mesmo com a sessão no console. Os valores anteriores são guardados.

A cada vez que sobe, o runtime confere a tarefa, os tempos limite e o plano de energia e corrige o que tiver mudado. Com a opção em false, ele remove a tarefa e devolve os tempos limite, o monitor e a suspensão aos valores anteriores.

O runtime também avisa no log, sem alterar nada, quando o Windows bloqueia a tela por inatividade (política InactivityTimeoutSecs) ou quando a proteção de tela está ligada para o usuário. Com a tela bloqueada ou coberta, a automação pode falhar.

A tarefa só move a sessão quando ela continua desconectada numa segunda verificação, 30 segundos depois, e não há ninguém conectando pelo RDP naquele momento. Ao reconectar, a sessão passa um instante pelo estado desconectado. Sem essas verificações, a tarefa poderia agir nesse instante e derrubar quem está entrando. Quando você volta pelo RDP, a sessão é reconectada normalmente.

{
  "key_activation": "<chave de ativação do runtime>",
  "user_token":     "<seu token de usuário>",
  "ui_socket_url":  "https://app.browsermate.io",
  "keep-session-active": true
}

• Só Windows. Em Mac e Linux o campo é ignorado.
• Abra o runtime como administrador uma vez depois de ligar a opção (e uma vez depois de desligar). Criar e remover a tarefa e alterar os tempos limite e o plano de energia exigem essa permissão. Depois disso, o runtime pode rodar sem ser administrador. Sem a permissão, o runtime avisa no log Manter sessão ativa NÃO está instalado: abra o runtime como administrador uma vez para concluir e segue funcionando, sem a proteção.
• Só a sessão de quem roda o runtime é movida. Sessões de outros usuários nunca são tocadas.
• Use em servidor dedicado ao runtime. Deixe desligado em um computador de uso pessoal ou compartilhado com troca rápida de usuário.
• Funciona em qualquer idioma do Windows: o estado da sessão é lido pelo sistema, como número, e não pelo texto de comandos como query session, que muda com o idioma.
• O que a tarefa fez fica registrado em logs\sessao-ativa.log, na pasta do runtime.
• Depois de editar o arquivo, reinicie o runtime.

Preferência de IP (IPv4 ou IPv6)

O banco de dados em tempo real e as APIs da Google que a plataforma usa respondem tanto por IPv4 quanto por IPv6. O campo ip-preference diz qual dos dois o runtime tenta primeiro ao abrir uma conexão com eles:

Com qualquer valor, uma rede que só tem IPv4 ou só tem IPv6 continua funcionando, porque a outra família fica de reserva. O padrão é IPv4 porque, em algumas redes, o caminho por IPv6 perde pacotes de vez em quando sem chegar a cair: a conexão aberta por ele fica lenta sem dar erro, e o agente para entre uma etapa e outra até ela se recuperar (veja Quando o banco de dados demora a responder). Use "ipv6" ou "system" quando a política de rede da empresa pede IPv6.

• Campo ausente vale "ipv4". Um valor que não seja um dos três também vale "ipv4", e o console avisa qual valor foi lido e qual foi usado.
• Ao subir, o console mostra a preferência em uso na linha IP preference:.
• Depois de editar o arquivo, reinicie o runtime.

Uma máquina ativa por chave de ativação

Cada chave de ativação é de uma instalação e aceita um único runtime ativo por vez. Duas máquinas com a mesma chave disputariam os mesmos jobs da fila e dividiriam a mesma presença: cada job roda em quem o tirar da fila primeiro, mas, quando uma delas cai, a instalação inteira aparece desligada, mesmo com a outra no ar. Por isso, ao subir, o runtime faz a mesma pergunta que a tela Meus Runtimes faz para mostrar LIVE ou OFFLINE: esta chave está ativa agora? Se estiver, o runtime novo não sobe. Se não estiver, ele sobe.

Um runtime ativo renova um sinal de vida a cada 30 segundos, e a chave é considerada ativa enquanto esse sinal estiver recente (menos de 75 segundos). Na prática:

• Já existe um runtime ativo: o runtime novo mostra Registering... por alguns segundos, o tempo de confirmar que o outro continua renovando o sinal. Em seguida mostra Já existe um Runtime ativo com essa chave de ativação., com o nome do computador onde o outro está rodando, e encerra. O runtime que já estava rodando não é afetado.
• O runtime anterior foi encerrado normalmente: a chave fica livre na hora, e o runtime novo sobe sem espera.
• O runtime anterior parou de forma abrupta (queda de energia, servidor que caiu, travamento): o sinal deixa de ser renovado e a chave volta a ficar livre sozinha, em até 75 segundos. Um runtime que reinicia automaticamente depois da queda mostra Registering... até lá e então sobe, sem você fazer nada. Ele nunca é barrado por causa de um runtime que já não existe.

O Registering... também aparece se o servidor demorar mais de uns 5 segundos para responder à ativação, para que o runtime nunca fique parado sem dar sinal, principalmente no modo background, em que não há janela.

No modo background, o aviso de chave em uso aparece numa caixa de mensagem do Windows, e o ícone nem chega a subir na bandeja. Essa caixa não depende do startup-notice: mesmo com "startup-notice": false, ela sempre aparece, porque é um erro e não uma confirmação. Durante a espera, aparece também uma caixa Registering..., que se fecha sozinha assim que a pergunta termina.

Erros comuns de ativação e conexão

Se algo no agent.config.json ou na rede não estiver certo, o runtime encerra com uma mensagem no console (prefixo Boot error:) ou fica rodando sem nunca aparecer como online. Todas as mensagens Activation failed abaixo vêm da chamada que o runtime faz ao Router (veja Pré-requisitos técnicos) para validar a ativação:

Pré-requisitos técnicos

O runtime não abre nenhuma porta de entrada. Ele não sobe nenhum servidor local esperando conexão de fora, então não é preciso redirecionar porta nenhuma no roteador. Mas ele faz várias conexões de saída, e em redes corporativas com firewall/proxy restritivo (que bloqueiam saída por padrão), o time de TI provavelmente vai precisar liberar explicitamente:

• Router da plataforma: https://router.browsermate.io:9443 precisa estar alcançável. É o controlador dos runtimes: sem esse domínio liberado, o runtime não funciona. Veja o detalhe de protocolo e porta de cada conexão em Arquitetura → Topologia de Comunicação.
• A plataforma browserMate: https://app.browsermate.io (ou o endereço configurado em ui_socket_url), por onde o runtime recebe comandos ao vivo (acompanhar execução, debug, gravador).
• O banco de dados em tempo real (Firebase) da plataforma: um domínio da Google (*.firebaseio.com) usado para o runtime saber, ao vivo, quando um novo job foi disparado. É uma conexão separada das duas anteriores.
• Conexão de saída para os sistemas-alvo: a máquina do runtime também precisa acessar as URLs que os agentes vão automatizar (VPN, rede interna, etc.).
• Repositórios públicos de pacotes: só se os seus agentes usarem Regra Customizada com bibliotecas externas. Para instalá-las na primeira execução, o runtime precisa alcançar o repositório do npm (Node.js) e o do pip (Python). Num Projeto ZIP em Node.js dá para evitar essa liberação empacotando as dependências junto: veja Rodando sem acesso aos repositórios de pacotes.
• Não precisa instalar Python ou Node.js: o runtime já carrega sua própria versão portátil de execução (Node.js 24 LTS e Python 3.14) para rodar scripts de Regra Customizada, isolada do que estiver (ou não) instalado na máquina.
• Google Chrome instalado: necessário quando o Navegador do agente está configurado como "Usando navegador local" ou "Usando conexão com navegador local". No modo "Usando app nativo" o runtime já traz um Chromium embutido. Nenhuma instalação extra é necessária nesse modo.
• Porta local de depuração do Chrome: só no modo "Usando conexão com navegador local". O runtime abre o Chrome com depuração remota numa porta que o próprio Chrome escolhe entre as livres, e se conecta a ele via localhost. Não há porta fixa a reservar nem a liberar no firewall.
• Conectores fazem suas próprias conexões de saída: a maioria dos Conectores (bancos de dados, APIs de IA, serviços de e-mail, integrações HTTP) abre conexão direta com o serviço configurado, em geral por HTTP/HTTPS ou no protocolo do próprio banco (ex.: porta padrão do MySQL, Postgres, MSSQL, Oracle, MongoDB). Se o conector aponta para um serviço atrás de firewall, libere a saída para o endereço e porta específicos desse serviço a partir da máquina do runtime.

Requisitos mínimos de máquina

O runtime herda os requisitos oficiais de sistema operacional do Node.js 24, a versão que o empacota (no runtime 2.4.0, a 24.22.1):

Não há requisito mínimo de RAM/CPU documentado oficialmente. Na prática, o consumo segue o do Google Chrome/Chromium (o maior componente do pacote), então qualquer máquina capaz de rodar um navegador Chrome moderno com folga roda o runtime sem problema. Reserve pelo menos 3 GB de disco livre por instalação (o .zip baixado já tem entre 380 MB e 660 MB dependendo do sistema operacional, e ocupa mais espaço depois de extraído).

Comportamento de execução

Cada instalação tem o próprio comportamento de execução. No card do runtime, o botão Configurar no bloco da instalação abre Configurar instalação, com o nome da instalação no título. A seção Comportamento de Execução controla como aquela instalação lida com múltiplos jobs. Nome, descrição e visibilidade para a empresa são do runtime e ficam em Editar.

Essas opções são lidas quando o runtime sobe. Depois de mudar Enfileirar Jobs, o número de execuções ao mesmo tempo ou as outras duas, reinicie o runtime na máquina daquela instalação para a mudança valer.

Limites e tetos

Quando o runtime sai do ar no meio

O runtime pode cair por qualquer motivo comum: a máquina foi desligada, a internet caiu, o processo foi encerrado. O que acontece com o trabalho depende de onde ele estava.

Quando o banco de dados demora a responder

Antes de cada etapa, o runtime confere no banco de dados em tempo real se alguém pediu para parar ou pausar a execução. Normalmente a resposta vem em milissegundos. Quando ela demora:

• Depois de 5 segundos sem resposta, o log mostra Sem resposta do banco de dados há 5 s; aguardando a conexão voltar antes da etapa "<etapa>". A etapa não começa enquanto isso, porque sem a resposta o runtime não teria como atender um pedido de parar.
• Quando a resposta chega, o log mostra O banco de dados respondeu depois de N s e a execução segue. Um pedido de parar feito durante a espera é atendido nesse momento.
• Sem resposta por 5 minutos, a execução é encerrada antes daquela etapa, com o motivo Execução encerrada: sem resposta do banco de dados por mais de 5 minutos antes da etapa "<etapa>". no registro da execução.
• Quando as esperas de uma mesma execução somam 2 minutos, o log avisa uma vez que ela está mais lenta que o normal por esperar o banco de dados, e a execução continua. Se o agente tem Envio de Logs com Sempre que houver uma falha, o mesmo aviso vai por e-mail para Quem o agente deve informar?. Veja Configurações do Agente.
• No fim, o log mostra quanto a execução esperou ao todo: Esperas pelo banco de dados nesta execução: N s em M parada(s) entre etapas.

Esse prazo só conta entre etapas. Dentro de uma etapa valem os prazos de sempre: espera de página, de elemento e de script. Uma pausa tem o seu prazo de 5 minutos, e ele vale mesmo com o banco de dados sem responder.

Esperas repetidas costumam vir da rede da máquina do runtime. Veja Preferência de IP.

Vínculo com o agente

Cada agente tem um runtime e um ambiente cadastrados, e são eles que valem por padrão: a execução roda na instalação que o runtime tem no ambiente do agente. O runtime fica no campo RUNTIME, na segunda fileira do cabeçalho do Agent Builder, e o ambiente nos botões Dev, Homolog e Prod, ao lado dele. Com o agente publicado, trocar um ou outro vale na hora, sem versão nova, porque é uma decisão de infraestrutura e não de modelagem. Os dois ficam travados enquanto outra pessoa está desenvolvendo o processo, já que a publicação dela sobrescreveria a escolha.

Em um agente que foi compartilhado com você, o runtime não é seu para trocar: ele pertence ao dono do agente, e o campo mostra apenas Runtime do dono do agente, além da Sandbox quando há uma versão em desenvolvimento aberta. Os botões Dev, Homolog e Prod mostram o ambiente que o dono escolheu e ficam desabilitados. Os runtimes da sua conta não aparecem ali de propósito. O dono não os alcança, e apontar um deles faria toda execução do agente ser recusada, inclusive as dele. Se o agente precisa rodar na sua máquina, marque o runtime como visível para toda a empresa e peça ao dono para selecioná-lo. Quem troca o runtime e o ambiente de um agente é sempre o dono dele.

Esse cadastro vale na execução manual, no modo de teste do editor e no disparo por webhook. Três situações permitem apontar outro runtime, ou outro ambiente, sem mexer no cadastro do agente. Em todas, o runtime precisa ter instalação no ambiente da execução:

ID do runtime (para a API)

Numa chamada de API, o campo environmentID do disparo e do agendamento indica qual runtime deve executar. O ID de cada runtime aparece no alto do card dele em Meus Runtimes, com botão de cópia, e também vem da rota GET /v1/environments, que devolve os runtimes que a conta de quem chama alcança, com o ID e, para cada ambiente, se há instalação e qual o status dela (veja Rotas da API). O disparo e o agendamento valem pelo alcance do dono do processo: num agente compartilhado, o runtime enviado precisa estar ao alcance do dono. Qual instalação roda depende do ambiente: o do agente, ou o de stage. O ID de uma instalação também é aceito e vale pelo runtime a que ela pertence.

A chave de ativação do card é outra coisa: liga a máquina à instalação, no agent.config.json. É segredo, nunca use em integrações.

Boas práticas

• Separe a instalação de Produção quando o agente for para valer. Uma instalação para os três ambientes serve para começar. Quando o agente for para Produção, troque a posição de Produção para Nova instalação e instale num servidor, deixando Desenvolvimento e Homologação no notebook. Assim uma execução de Produção nunca cai na sua máquina pessoal, que desliga, dorme e troca de rede.
• Use Sem instalação no que o runtime não deve atender. Um runtime que só serve para testes fica sem instalação em Produção, e nenhum agente roda nele em Produção: escolhê-lo num agente em Produção leva o agente junto para um ambiente que o runtime tem (Homologação, depois Desenvolvimento), com aviso.
• Use Enfileirar Jobs em servidores compartilhados. Evita erros de concorrência quando vários processos disparam ao mesmo tempo.
• Nomeie pelo que o runtime faz. "Nota Fiscal Automation" comunica mais do que "Servidor 2". O ambiente já aparece nos botões Dev, Homolog e Prod do agente, não precisa estar no nome.
• Compartilhe com parcimônia. Só marque "visível para toda a empresa" em servidores dimensionados para receber a carga de outros times.