Ambientes Runtime

Onde os agentes executam. Baixe e configure o runtime nas suas máquinas, cadastre ambientes de Produção, Homologação e Dev e controle o comportamento de execução de cada um.

O que é um Ambiente 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. Um Ambiente é o registro de uma máquina (ou contêiner) onde o runtime está instalado.

Com ambientes separados você consegue:

• Executar agentes de Produção em um servidor dedicado, enquanto desenvolve em sua máquina local
• Testar novas versões em Homologação antes de publicar
• Distribuir a carga entre várias máquinas
• Ver o status online/offline de cada máquina na tela Meus Ambientes

Cadastrar um ambiente

Em Meus Ambientes, clique em Novo Ambiente e preencha:

Quantos ambientes o plano permite

O número de ambientes é um teto da empresa inteira, não de cada pessoa: os ambientes de todos os membros somam contra o mesmo limite. O topo da tela Meus Ambientes mostra quanto já está em uso, no formato 2 de 5 ambientes em uso na empresa, para você saber onde está antes de tentar cadastrar mais um. Ao atingir o teto, o cadastro é recusado com um aviso na própria tela.

Quando a empresa muda para um plano menor, os ambientes que passam do novo teto são suspensos, nunca excluídos: eles continuam cadastrados, com a configuração e a chave de ativação intactas, e voltam a funcionar sozinhos se a empresa subir de plano de novo. Enquanto está suspenso, o ambiente não aceita ativação e não ocupa vaga, então o teto continua disponível para os ambientes que o plano cobre. O mesmo vale para os ambientes de um membro que ficou sem acesso ativo por causa do plano: eles saem da contagem enquanto ele estiver nessa situação.

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 ambiente já cadastrado (seção Cadastrar um ambiente 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 ambiente, 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á instalação nem login, é rodar direto.
4. O runtime conecta-se à plataforma e passa a aparecer como online em Meus Ambientes.

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)

A vinculação do runtime à sua conta e ao ambiente é feita pelo arquivo agent.config.json, localizado na pasta onde você extraiu o .zip do runtime:

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

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 ambiente>",
  "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.

Um runtime por chave de ativação

Cada chave de ativação aceita um único runtime ativo por vez. Dois runtimes 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 um deles cai, o ambiente inteiro aparece desligado, mesmo com o outro no ar. Por isso, ao subir, o runtime faz a mesma pergunta que a tela Meus Ambientes 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):

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 ambiente instalado (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

A seção Comportamento de Execução do cadastro controla como o ambiente lida com múltiplos jobs:

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 daquele ambiente 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.

Vínculo com o agente

Cada agente tem um ambiente cadastrado, e é ele que vale por padrão. A escolha fica no seletor AMBIENTE, na segunda fileira do cabeçalho do Agent Builder. Trocar ali vale na hora, sem precisar de uma versão em desenvolvimento aberta nem de publicação, porque é uma decisão de infraestrutura e não de modelagem. O seletor fica travado 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 ambiente não é seu para trocar: ele pertence ao dono do agente, e o seletor mostra apenas Runtime do dono do agente, além da Sandbox quando há uma versão em desenvolvimento aberta. Os ambientes 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 ambiente como visível para toda a empresa e peça ao dono para selecioná-lo. Quem troca 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. Duas situações permitem apontar outro ambiente sem mexer no cadastro do agente, valendo só para aquele disparo:

ID do ambiente (para a API)

O cartão de cada ambiente em Meus Ambientes mostra dois códigos, com finalidades diferentes:

Quem integra por sistema não precisa abrir esta tela: a rota GET /v1/environments devolve os ambientes disponíveis com o ID e o status de cada um (veja Rotas da API).

Boas práticas

• Separe Produção de Dev. Nunca aponte agentes de produção para sua máquina pessoal. Notebooks desligam, dormem e trocam de rede.
• Use Enfileirar Jobs em servidores compartilhados. Evita erros de concorrência quando vários processos disparam ao mesmo tempo.
• Nomeie pelos papéis. "Produção Financeiro" comunica mais do que "Servidor 2".
• Compartilhe com parcimônia. Só marque "visível para toda a empresa" em servidores dimensionados para receber a carga de outros times.