Indice del manuale

🧩 L'agente locale

L'agente locale è un piccolo programma che gira su un computer del tuo laboratorio. Parla con le tue stampanti attraverso la rete di casa e racconta a BolloPrint quello che vede.

È l'unica cosa da installare per collegare stampanti in rete locale, e ne basta uno solo per tutta la flotta.

Ti serve?

La tua situazione	Ti serve l'agente?
Hai Bambu Lab e ti basta vederle dal cloud	No, ma con l'agente guadagni la telecamera. Mettere in pausa e annullare no: Bambu non accetta comandi da programmi esterni, da qualunque via arrivino
Hai Prusa	Sì. È l'unico modo per collegarle
Hai Elegoo a resina o Centauri	Sì. Non c'è un'altra via
Hai QIDI, Sovol, Voron, RatRig, Two Trees, Artillery, una Creality K1 con Moonraker raggiungibile o qualsiasi macchina con Klipper	Sì
Hai FlashForge Adventurer 5M, AD5X o Creator 5	Sì
Non vuoi che le tue stampanti escano su internet	Sì. L'agente parla con loro dentro la tua rete

Installarlo e tenerlo aggiornato

Due pagine separate, perché sono due momenti diversi:

🚀 Installare l'agente — dove metterlo, come crearlo in BolloPrint e come avviarlo sul tuo computer con Docker Compose, Portainer o Kubernetes.
🔄 Aggiornare l'agente — cosa fare quando BolloPrint ti avvisa che c'è una versione nuova. Basta cambiare un numero e reinstallare.

Come si collega

L'agente chiama BolloPrint, non il contrario. È questo che fa sì che funzioni senza toccare il router: non bisogna aprire porte, né chiedere un IP fisso, né toccare il firewall. Funziona dietro un normale router domestico, e persino con le connessioni in fibra che non danno un IP pubblico.

Una volta collegato:

chiede quali stampanti deve seguire,
si collega a ciascuna con il suo protocollo,
e invia man mano quello che vede.

Quando registri una nuova stampante da BolloPrint, l'agente se ne accorge da solo, in pochi secondi. Non bisogna riavviarlo.

Autorizzare le installazioni

L'installazione del manifesto che hai copiato entra direttamente. Qualsiasi altra installazione che usi quello stesso codice aspetta il tuo via libera: vedrai un avviso rosso sopra le schede e, dentro l'agente, in Stato, l'installazione in Installazioni in attesa di autorizzazione, con il nome del computer da cui si collega.

Con un manifesto attuale questo non succede quasi mai: l'identità è scritta nel manifesto stesso, quindi puoi spostare l'agente su un'altra macchina o reinstallarlo e resta lo stesso. È normale che succeda con un agente precedente, installato con un manifesto senza identità, quando:

lo sposti su un'altra macchina,
cancelli il suo volume di dati e lo ricrei,
lo reinstalli da zero.

Premi Autorizza se riconosci il computer. Autorizzandone uno, il precedente perde l'accesso.

Se compare un'installazione in attesa che non hai messo tu, non autorizzarla: significa che qualcun altro ha il tuo codice. Apri l'agente, usa Rigenera le chiavi in Installazione e reinstallalo con il nuovo manifesto.

La schermata di stato

La scheda Agente locale ha due parti:

Gli agenti, uno per riga, con il suo stato e la sua versione. Nel menu ⋮ di ciascuno trovi Modifica, che apre la sua finestra, e Elimina.
Stampanti in rete locale, sotto: quelle di tutti i tuoi agenti insieme, ciascuna con l'agente che la gestisce. In alto trovi Cerca ora e Aggiungi per IP, e in fondo quello che ogni agente ha trovato nella tua rete e gli indirizzi che sta ancora cercando.

La finestra di un agente ha due schede:

Stato — quello che l'agente stesso riferisce (la tabella qui sotto), le installazioni in attesa e il collegamento con ogni stampante. Qui puoi anche cambiargli il nome.
Installazione — il manifesto con la versione attuale e Rigenera le chiavi.

Cosa può comparire in Stato:

Quello che vedi	Cosa significa
Online	È collegato e sta lavorando.
Nessun segnale recente	È da un po' che non dà segnali. Di solito è il computer spento o senza internet.
Offline	Non c'è.
Modalità sicura	Si è avviato e si è collegato, ma non sta gestendo stampanti. Ti dice il motivo.
Buffer	Quello che ha salvato mentre non poteva inviarlo. Se compare «messaggi scartati», c'è stata un'interruzione così lunga che non ci è entrato tutto.
Aggiorna il tuo agente	C'è una versione più recente. Si fa sul tuo computer, non da BolloPrint: cambia la versione dell'immagine nel tuo file e reinstalla. Passo per passo in Aggiornare l'agente.

Sotto, Collegamento con ogni stampante: macchina per macchina, se l'agente la raggiunge e, se no, perché.

L'agente cerca stampanti nuove nella tua rete da solo ogni 15 minuti. Se ne hai appena accesa una e non vuoi aspettare, premi Cerca ora in Stampanti in rete locale.

Particolarità che conviene conoscere

L'agente ricorda chi è. La sua identità è scritta nel manifesto (BP_AGENT_INSTANCE_ID), quindi lo stesso manifesto avviato su un'altra macchina resta lo stesso agente. Non cambiarla e non copiarla in un'altra installazione: è la sua password. Gli agenti installati con un manifesto precedente salvano l'identità nel loro volume di dati; se lo cancelli, dovrai autorizzarlo di nuovo (non si perde nulla).

Un agente regge un'intera flotta. Non serve uno per stampante né uno per stanza. Detto questo, puoi avere più agenti nello stesso account, e ci sono tre motivi per farlo:

Reti separate: una VLAN per la produzione e un'altra per l'ufficio, per esempio. Un agente in ciascuna scopre le sue senza che tu debba aggiungere nulla a mano.
Sedi diverse: due capannoni, due laboratori, due case. Ogni posto con il suo, e si vede tutto insieme in BolloPrint.
Un agente sovraccarico: se la flotta cresce molto e noti che fa fatica, distribuisci le stampanti fra due.

Ogni agente si crea allo stesso modo, con il suo nome e il suo codice. Nella scheda Agente locale li vedrai uno sotto l'altro, e in Stampanti in rete locale ogni macchina dice da quale agente arriva. Per spostare una stampante da un agente a un altro, aprila con Modifica nel suo menu ⋮ e cambia l'agente nel menu a tendina. Con Aggiungi per IP e più agenti, ti chiede quale la gestirà.

⚠️ Un codice per computer

Quello che non devi fare è usare lo stesso codice su due macchine: la seconda resterà in attesa di autorizzazione, e se la autorizzi, la prima perde l'accesso. Per due computer, due agenti.

Sopravvive alle interruzioni. Se cade la tua connessione a internet, l'agente continua a leggere le stampanti e a salvare quello che succede. Quando la connessione torna, invia tutto. Le ore dell'interruzione non si perdono dallo storico.

Rigenerare le chiavi scollega l'agente all'istante. Il codice e l'identità precedenti smettono di valere appena premi il pulsante, quindi l'agente si scollega finché non lo reinstalli con il nuovo manifesto. Usalo quando pensi che qualcuno abbia le tue chiavi o se hai perso il manifesto. Per aggiornare l'agente non serve: basta cambiare la versione dell'immagine (Aggiornare l'agente).

Eliminare un agente si porta via le sue stampanti. Si fa dal menu ⋮ della sua riga. Smette di collegarsi all'istante, e le stampanti che arrivavano solo tramite lui spariscono dall'elenco e smettono di contare per il tuo piano. Quelle che arrivano anche tramite Bambu Cloud restano. Non si perde nulla: se aggiungi di nuovo una di quelle stampanti —con un altro agente, tramite scoperta o per IP—, torna con il suo numero e tutto il suo storico. Il contenitore che gira sul tuo computer non si elimina da BolloPrint: fermalo ed eliminalo tu (docker compose down nella sua cartella, oppure elimina lo stack in Portainer).

Quando qualcosa non va

Quando l'agente non compare o si comporta in modo strano, la prima cosa è guardare il suo registro sul computer dove gira:

docker logs bolloprint_agent --tail 50

Sintomo	Cosa guardare
L'agente non compare mai	Il codice è stato incollato bene, intero e senza spazi davanti o dietro? Il computer arriva a internet? C'è un firewall che blocca l'uscita?
Chiede l'autorizzazione a ogni riavvio	Il manifesto non contiene `BP_AGENT_INSTANCE_ID` (è di prima o è stato modificato a mano). Rigenera le chiavi e installa il nuovo manifesto così com'è.
Non rileva nessuna stampante	L'agente e le stampanti sono nella stessa rete? Se non lo sono, o se usi Docker Desktop, è quello che ci si aspetta: aggiungile per IP e funzioneranno lo stesso.
Una stampante risulta «collegata ma non invia dati»	Chiudi l'app del cellulare o lo slicer che la tiene aperta. Alcune macchine ammettono una sola connessione alla volta.
Una stampante «risponde ma rifiuta la connessione»	Codice di accesso sbagliato, o modalità LAN disattivata sullo schermo della macchina. Attenzione: sulle Bambu, il codice cambia ogni volta che attivi o disattivi la modalità LAN.
Tutte le stampanti di un agente disconnesse di colpo	Non è la flotta, è l'agente. Aprilo con Modifica e guarda il suo Stato.

Domande frequenti

Posso mettere in pausa o annullare una stampa da BolloPrint? Sì, sulle macchine collegate tramite l'agente che lo permettono (oggi Klipper, PrusaLink e le Elegoo che passano per SDCP: quelle a resina e la Centauri Carbon). Sulle Bambu no, né tramite l'agente né tramite il cloud: il loro firmware ignora i comandi che non arrivano dai loro stessi programmi. Quello che non si può fare su nessuna è inviare lavori: il file si continua a mandare dal tuo slicer.

Cosa succede se cade internet in laboratorio? L'agente continua a parlare con le tue stampanti e salva quello che succede. Quando la connessione torna, invia tutto. Se l'interruzione è lunghissima può darsi che non gli entri tutto il dettaglio, e in quel caso te lo dice.

Salva qualcosa sul mio disco? Non salva dati di stampa. Nel suo volume salva il proprio registro di attività degli ultimi giorni, che si cancella da solo (e, negli agenti installati con un manifesto precedente, il suo file di identità). Quel registro esce dal tuo computer solo se il supporto di BolloPrint lo chiede per indagare su un problema.

Quanto consuma? Pochissimo: tra 10 e 20 MB di memoria con diverse stampanti collegate.

E se spengo il computer? Non succede nulla. Riaccendendolo, l'agente torna da solo e senza chiederti niente.

Devo aprire porte sul router? No. Né porte, né IP fisso, né regole di firewall. La connessione esce dalla tua rete verso l'esterno, come quando apri una pagina web.