🧩 O agente local

O agente local é um programa pequeno que corre num equipamento da tua oficina. Fala com as tuas impressoras pela rede local e conta ao BolloPrint o que vê.

É a única coisa que é preciso instalar para ligar impressoras por rede local e, com um só, chega para toda a frota.

---

Precisas dele?

A tua situação	Precisas do agente?
Tens Bambu Lab e chega-te vê-las pela nuvem	Não, mas com o agente ganhas câmara. E, se ativares na impressora o Modo programador, também pausar, retomar e cancelar: pela nuvem não é possível
Tens Prusa	Sim. É a única forma de as ligar
Tens Elegoo de resina ou Centauri	Sim. Não há outra via
Tens QIDI, Sovol, Voron, RatRig, Two Trees, Artillery, uma Snapmaker U1 ou qualquer máquina com Klipper	Sim
Tens FlashForge Adventurer 5M, AD5X ou Creator 5	Sim
Tens Anycubic Kobra 3, Kobra S1, Kobra 4 ou Kobra X	Sim. Com o Modo LAN ativado na impressora (em beta)
Tens uma Creality K1, K2, Ender-3 V3 ou Hi	Sim. Com o firmware de fábrica, sem preparar nada (em beta)
Não queres que as tuas impressoras saiam para a internet	Sim. O agente fala com elas dentro da tua rede

---

Escolhe onde o instalar

O agente vai num equipamento da oficina que esteja sempre ligado e, se possível, na mesma rede que as impressoras. Não é preciso comprar nada: quase sempre serve algo que já tens.

Há duas formas de o instalar, e a diferença é como se liga à tua conta da primeira vez:

• Com um pacote ou um instalador (Synology, QNAP, Windows, Home Assistant, TrueNAS). Instalas-o como qualquer outra aplicação do teu equipamento, abres a sua página e premes Ligar ao BolloPrint. Confirmas no BolloPrint e pronto: não há códigos para copiar.
• Com um contentor (Docker, Kubernetes). Crias o agente no BolloPrint e damos-te um manifesto com as suas chaves já postas, que colas no teu equipamento.

Onde	O que precisas	Como se instala	Estado
Synology	Um NAS Synology com DSM	Pacote, e Ligar ao BolloPrint	Beta
QNAP	Um NAS QNAP com QTS	Pacote que se instala à mão, e Ligar ao BolloPrint	Beta
Windows	Um PC com Windows que não desligues	Instalador, e Ligar ao BolloPrint	Beta
Home Assistant	Home Assistant com a sua loja de aplicações	Aplicação do Home Assistant, e Ligar ao BolloPrint	Beta
TrueNAS	Um NAS TrueNAS com Apps	Aplicação do TrueNAS, e Ligar ao BolloPrint	Beta
Docker	Qualquer equipamento com Docker ou Portainer: um NAS, um mini-PC, um Raspberry Pi, um servidor	Manifesto com chaves	Estável
Kubernetes	Um cluster de Kubernetes (k3s também serve) com um nó na rede das impressoras	Manifesto com chaves	Estável

Estás indeciso entre dois? Se o teu equipamento tem pacote, usa o pacote: instala-se com menos passos e liga-se com um clique. O Docker é a opção para tudo o resto, e a que há mais tempo funciona em oficinas. As que levam Beta funcionam, mas são novas: se alguma coisa não correr como esperas, conta-nos no suporte.

Cada página explica as duas coisas que vais fazer com o agente: instalá-lo da primeira vez e atualizá-lo se alguma vez to pedirmos.

---

Mantê-lo atualizado

O agente atualiza-se sozinho: quando sai uma versão nova, descarrega-a, confirma que é nossa e reinicia-se com ela. Nunca o faz enquanto alguma das suas impressoras está a imprimir.

Só se o BolloPrint te avisar de que o teu agente precisa de uma atualização manual é que terás de fazer alguma coisa, e depende de como o instalaste:

• Com um pacote ou um instalador: instala a versão nova por cima da que tens, sem desinstalar a anterior.
• Com Docker ou Kubernetes: muda a versão da imagem no teu ficheiro e volta a instalá-lo, com as mesmas chaves.

O passo a passo está na página de cada tipo.

---

Como se liga

O agente liga-se ao BolloPrint, não ao contrário. É isso que faz com que funcione sem mexer no router: não é preciso abrir portas, nem pedir IP fixo, nem tocar na firewall. Funciona atrás de um router doméstico normal, e até com as ligações de fibra que não dão IP público.

A carregar diagrama…

O que o BolloPrint diz ao agente viaja por essa mesma ligação que ele abriu.

Uma vez ligado:

• pergunta que impressoras tem de atender,
• liga-se a cada uma pelo seu protocolo,
• e vai enviando o que vê.

Quando registas uma impressora nova a partir do BolloPrint, o agente dá por isso sozinho, em segundos. Não é preciso reiniciá-lo.

---

O ecrã de estado

O separador Agente local tem duas partes:

• Os agentes, um por linha, com o logótipo do sítio onde está instalado, o seu estado e a sua versão. No menu ⋮ de cada um tens Editar, que abre a sua janela, e Eliminar.
• Impressoras na rede local, por baixo: as de todos os teus agentes juntas, cada uma com o agente que a conduz. Em cima estão Procurar agora e Adicionar por IP, e no final o que cada agente encontrou na tua rede e os endereços que ainda está a procurar.

A janela de um agente tem dois separadores:

• Estado — aquilo que o próprio agente reporta (a tabela abaixo), as instalações pendentes e a ligação a cada impressora. Também é aqui que lhe mudas o nome.
• Instalação — no Docker e no Kubernetes, o manifesto com a versão atual e Regenerar chaves. Num agente instalado com um pacote só diz que foi ligado a partir da sua página: não tem manifesto nem chaves. Para o retirar, usa Eliminar no menu ⋮ da lista, e a sua página volta a oferecer Ligar ao BolloPrint.

O que pode aparecer em Estado:

O que vês	O que significa
Online	Está ligado e a trabalhar.
Por instalar	Criaste-o no BolloPrint, mas ainda nunca se ligou. Não se estragou nada: falta arrancá-lo no teu equipamento.
Sem sinal recente	Já vai um bocado sem dar sinal. Costuma ser o equipamento desligado ou sem internet.
Desligado	Não está.
Modo seguro	Arrancou e ligou-se, mas não está a gerir impressoras. Diz-te o motivo.
Buffer	O que guardou enquanto não o conseguia enviar. Se aparecer «mensagens descartadas», houve um corte tão longo que não coube tudo.
Atualiza o teu agente	Há uma versão mais recente. Os agentes recentes atualizam-se sozinhos; se disser que é preciso atualizar à mão, segue a página do teu tipo de agente.

Por baixo, Ligação a cada impressora: máquina a máquina, se o agente chega a ela e, se não chega, porquê.

O agente procura impressoras novas na tua rede sozinho a cada 15 minutos. Se acabaste de ligar uma e não queres esperar, prime Procurar agora em Impressoras na rede local.

---

Particularidades que convém conhecer

Um agente aguenta uma frota inteira. Não é preciso um por impressora nem um por sala. Dito isto, podes ter vários agentes na mesma conta, e há três motivos para o fazer:

• Redes separadas: uma VLAN para produção e outra para escritório, por exemplo. Um agente em cada uma deteta as suas sem que tenhas de acrescentar nada à mão.
• Locais diferentes: dois pavilhões, duas oficinas, duas casas. Cada sítio com o seu, e vê-se tudo junto no BolloPrint.
• Um agente saturado: se a frota crescer muito e notares que está no limite, reparte as impressoras por dois.

Não têm de ser do mesmo tipo: podes ter um no Synology do pavilhão e outro em Docker no escritório. No separador Agente local vê-los-ás uns por baixo dos outros, e em Impressoras na rede local cada máquina diz por que agente chega. Para mudares uma impressora de um agente para outro, abre-a com Editar no seu menu ⋮ e muda o agente na lista pendente. Ao Adicionar por IP com vários agentes, pergunta-te qual é o que a vai conduzir.

Sobrevive aos cortes. Se a tua internet cair, o agente continua a ler as impressoras e a guardar o que se passa. Quando a ligação volta, manda tudo. As horas do corte não se perdem do histórico.

Eliminar um agente leva as suas impressoras. Faz-se a partir do menu ⋮ da sua linha. Deixa de se ligar no momento, e as impressoras que só chegavam por ele desaparecem da lista e deixam de contar para o teu plano. As que também chegam pela Bambu Cloud ficam. Não se perde nada: se voltares a adicionar uma dessas impressoras — com outro agente, por deteção ou por IP —, ela volta com o seu número e todo o seu histórico. O que está instalado no teu equipamento não se apaga a partir do BolloPrint: um pacote volta sozinho à sua página de Ligar ao BolloPrint, e um contentor paras e eliminas tu. Como, na página de cada tipo.

---

Quando alguma coisa não vai

Sintoma	O que ver
O agente nunca aparece	O equipamento chega à internet? Há alguma firewall a bloquear a saída? No Docker e no Kubernetes, o manifesto foi colado por completo, sem alterações?
Não deteta nenhuma impressora	O agente e as impressoras estão na mesma rede? Se não estão, ou se usas o Docker Desktop, é o esperado: acrescenta-as por IP e funcionarão na mesma.
Uma impressora aparece como «ligada mas sem enviar dados»	Fecha a app do telemóvel ou o fatiador que a tenha aberta. Algumas máquinas só admitem uma ligação de cada vez.
Uma impressora «responde mas recusa a ligação»	Código de acesso errado, ou modo LAN desativado no ecrã da máquina. Atenção: nas Bambu, o código muda sempre que ativas ou desativas o modo LAN.
Todas as impressoras de um agente desligadas de repente	Não é a frota, é o agente. Abre-o com Editar e vê o seu Estado.

Se isto não chegar, a página do teu tipo de agente explica onde ver o seu registo, que é a primeira coisa que te vamos pedir no suporte.

---

Perguntas frequentes

Posso pausar ou cancelar uma impressão a partir do BolloPrint? Sim, nas máquinas ligadas pelo agente que o permitem (hoje, Klipper, Snapmaker, PrusaLink, as Elegoo que vão por SDCP —as de resina e a Centauri Carbon— e as Bambu com o Modo programador ativado). Esse modo exige o Modo LAN Only, que desliga a Bambu da sua nuvem; sem ele, a impressora ignora a ordem, e o BolloPrint desativa os seus botões assim que ela a recusa. Pela nuvem, as Bambu não aceitam ordens. O que não se pode em nenhuma é enviar trabalhos: o ficheiro continua a ser mandado a partir do teu fatiador.

O que acontece se a internet cair na oficina? O agente continua a falar com as tuas impressoras e guarda o que acontece. Quando a ligação volta, envia tudo. Se o corte for longuíssimo, pode não lhe caber o detalhe todo e, nesse caso, ele diz-to.

Guarda alguma coisa no meu disco? Não guarda dados de impressão. Guarda o seu próprio registo de atividade dos últimos dias, que se vai apagando sozinho, e as versões que descarrega para se atualizar. Esse registo só sai do teu equipamento se o suporte do BolloPrint o pedir para investigar um problema.

Quanto consome? Pouco: não precisa de um equipamento potente e cabe à vontade num NAS ou num mini-PC, ao lado do que já lá tens a correr. No Docker e no Kubernetes, o manifesto limita-o a 512 MB de memória.

E se desligar o equipamento? Não acontece nada. Ao ligá-lo, o agente volta sozinho e sem te pedir nada.

Tenho de abrir portas no router? Não. Nem portas, nem IP fixo, nem regras de firewall. A ligação sai da tua rede para fora, como quando abres uma página web.

Posso mudar de tipo mais tarde? Sim. Instala o novo, confirma que aparece Online, passa as impressoras para ele (ou deixa que as encontre) e elimina o antigo. As impressoras mantêm o seu número e o seu histórico.