Resposta rápida
Para limitar onde uma automação do Cloudflare Browser Run pode navegar, defina guardrails.allowedDomains ao iniciar a sessão. Informe apenas hostnames, sem https://, porta ou caminho. Se a tarefa precisa acessar o domínio principal e seus subdomínios, liste os dois padrões, por exemplo example.com e *.example.com.
O controle vale para requisições HTTP e HTTPS da sessão criada com Puppeteer, Playwright ou CDP. Destinos fora da lista recebem 403. A proteção não está disponível para Quick Actions e, se allowedDomains e allowedDomainSets forem omitidos, as requisições continuam sem essa restrição.
O que mudou no Browser Run
A Cloudflare anunciou os guardrails em 14 de setembro de 2026. O objetivo é manter uma sessão de navegador nos hostnames necessários à tarefa, permitir dependências conhecidas e impedir que uma página autocontida carregue conteúdo externo.
A política é definida quando a sessão começa e permanece fixa durante toda a vida daquela sessão. Para mudar a lista, encerre a sessão e inicie outra com a nova configuração. Use @cloudflare/puppeteer 1.4.0 ou posterior, ou @cloudflare/playwright 1.3.6 ou posterior. Kitesurf não oferece suporte a esse controle no momento verificado.
Como configurar allowedDomains
No objeto de lançamento do Puppeteer ou Playwright, adicione guardrails com allowedDomains. A mesma estrutura pode ser enviada ao endpoint REST que cria uma sessão. Uma lista curta e estável deve usar allowedDomains, que aceita até 50 entradas.
Cada item é um hostname. example.com libera somente o domínio principal. *.example.com libera subdomínios, inclusive níveis mais profundos, mas não libera o domínio principal. Por isso, uma automação que usa ambos precisa declarar ambos. Não inclua protocolo, porta ou caminho.
- Mapeie o site principal, redirecionamentos e hostnames de APIs, scripts, imagens e fontes necessários.
- Adicione somente esses hostnames a guardrails.allowedDomains quando iniciar a sessão.
- Liste o domínio principal e o padrão de subdomínios separadamente quando precisar dos dois.
- Inicie uma nova sessão e execute o fluxo completo, incluindo login, redirecionamentos e carregamento de recursos.
- Tente abrir deliberadamente um domínio fora da lista e confirme o bloqueio 403 e os cabeçalhos de guardrail.
Curingas e listas compartilhadas exigem cuidado
Prefira *.example.com ao padrão *example.com. A documentação alerta que o segundo também aceita hostnames parecidos que outra pessoa pode registrar, como evilexample.com. Quando o domínio principal for necessário, declare example.com em uma entrada separada.
Para listas maiores ou mantidas centralmente, allowedDomainSets aceita até quatro entradas. É possível usar o conjunto common-cdns mantido pela Cloudflare ou uma URL HTTPS que entregue uma lista text/plain. O conjunto comum pode mudar com o tempo. Uma lista hospedada é armazenada em cache por até uma hora, e alterações só afetam novas sessões depois da atualização do cache.
Não adicione common-cdns por conveniência se o fluxo usa poucos provedores conhecidos. Uma permissão mais ampla facilita o carregamento, mas aumenta a quantidade de destinos que uma página ou automação consegue alcançar.
Como diagnosticar uma página quebrada pelo guardrail
Quando um hostname não permitido é solicitado, o Browser Run responde 403 com cf-mitigated: guardrails e cf-brapi-guardrails-reason: not-in-allowlist. Esses cabeçalhos diferenciam o bloqueio do guardrail de um 403 gerado pelo próprio site, por autenticação ou por um WAF.
Se a página abre sem estilo, imagem ou fonte, inspecione as requisições bloqueadas e adicione somente a dependência indispensável. Se a navegação para depois de um clique, verifique a cadeia de redirecionamentos. Não libere um domínio inteiro antes de confirmar por que ele aparece no fluxo.
- Registre URL, hostname, status e cabeçalhos da requisição bloqueada.
- Confirme se o hostname pertence ao serviço esperado e é necessário para a tarefa.
- Atualize a política e crie uma nova sessão, pois a lista da sessão atual não muda.
- Repita o teste e confirme que um domínio externo de controle continua bloqueado.
- Consulte o status da Cloudflare se sessões diferentes falharem sem alteração de configuração.
Como bloquear todas as requisições externas
Para renderizar HTML autocontido sem acesso à web, use allowedDomains como uma lista vazia e não combine a política com domain sets. O conteúdo inline ainda pode ser renderizado, mas APIs, imagens, fontes e outros recursos externos não serão carregados.
Esse modo é útil para gerar captura de tela ou PDF a partir de HTML controlado. Faça o teste com o documento real: CSS, imagens incorporadas e fontes locais precisam estar disponíveis sem uma solicitação externa.
Live View somente leitura é outro controle
O mesmo anúncio adicionou um modo somente leitura ao Live View. Ao gerar o link pela API REST, use guardrails com mode: readonly. A pessoa que recebe o link pode assistir à sessão, mas não pode navegar, digitar, clicar nem executar JavaScript por aquela conexão.
Essa restrição vale apenas para o link gerado. Outros links e os scripts de automação continuam capazes de controlar a sessão. O link contém um JWT e deve ser tratado como credencial, pois até uma visualização somente leitura pode revelar dados exibidos na página. As restrições de hostname da sessão continuam ativas em todos os acessos do Live View.
O que os guardrails não resolvem
A lista limita destinos de rede, não ações realizadas dentro de um domínio permitido. Um agente ainda pode clicar no botão errado, enviar dados para uma rota legítima, alterar uma conta ou expor informações na tela se o fluxo e as credenciais permitirem. Trate o guardrail como uma camada de contenção, não como autorização completa.
Mantenha credenciais curtas e específicas, separe sessões por tarefa, restrinja permissões da conta usada, registre ações importantes e exija aprovação antes de publicar, excluir, pagar ou mudar acesso. Revise também downloads, uploads, extensões e dados já carregados no navegador.
Limites e próxima ação útil
Este guia foi verificado em 15 de setembro de 2026. Guardrails e Live View aparecem como recursos beta, e limites, versões compatíveis e formatos podem mudar. Quick Actions não aceitam guardrails, políticas inválidas fazem a criação da sessão retornar 400 e listas omitidas deixam o tráfego HTTP e HTTPS irrestrito.
Antes de colocar um agente em produção, crie uma sessão de homologação com a menor lista possível. Execute o fluxo normal, teste um redirecionamento inesperado e confirme que um domínio externo recebe 403 com os cabeçalhos documentados. Depois valide publicamente os domínios permitidos e acompanhe o status oficial da plataforma.
Faça o próximo teste
Fontes consultadas
Os links abaixo servem para conferir conceitos, orientações oficiais e o critério editorial usado neste conteúdo.
- Control which hostnames Browser Run sessions can accessCloudflare Changelog
- GuardrailsCloudflare Browser Run Docs
- Live ViewCloudflare Browser Run Docs
- Browser Run overviewCloudflare Docs
- Cloudflare StatusCloudflare