🏠 Agent on Home Assistant

If you already have a Home Assistant switched on day and night in the workshop, you already have somewhere to put the agent: it's always running, it's on your network and it has its own app store. This page explains how to install it there, link it to your workshop and keep it up to date.

If your computer is something else (a NAS, a PC, a server with Docker), pick yours in The local agent, which also explains what the agent does, whatever the computer.

---

What you need

• Home Assistant OS, which is the installation that comes with an app store. "Supervised" installations have one too, but Home Assistant no longer maintains them. If your Home Assistant runs in Docker ("Container"), it has no apps: install the agent with Docker, as explained in Agent on Docker.
• A 64-bit computer: a mini-PC or a PC with Intel or AMD, a Raspberry Pi 4 or 5, or a Home Assistant Green or Yellow. On a Raspberry Pi 3 or a 32-bit system the app can't be installed.
• Home Assistant on the same network as your printers. If it runs in a virtual machine, its network has to be in bridge mode, not NAT.
• Port 8257 free on that computer. If something else is using it, it only takes a moment to change (further down).
• Being the owner of the workshop in BolloPrint: the agent can only be linked to a workshop of yours.

---

Installing it

1. From a computer or a phone connected to your network, open this link: Add BolloPrint to my Home Assistant. It's a Home Assistant page: the first time, it asks for your Home Assistant's address, for example http://homeassistant.local:8123.
2. Click Open link. Your Home Assistant asks whether you want to add the BolloPrint app repository: click Add.
3. The BolloPrint Agent page opens, with the BolloPrint dog. Click Install. Home Assistant prepares the app itself; it takes a minute or two.
4. Click Start. Leave Start on boot turned on, so the agent comes back by itself every time Home Assistant restarts.

---

Linking it to your workshop

1. On the app's page, click Open Web UI. The agent's page opens in a new tab: it says it doesn't belong to any workshop yet and shows a code, like 8054-627E.
2. Click Link with BolloPrint. It takes you to BolloPrint; sign in with your account if it asks you to.
3. Choose the workshop, check that the code is the same as the one on the agent's page, review the name it suggests (your Home Assistant's; you can change it) and confirm.
4. You're back on the agent's page, which now says "Linked to …". In under a minute you'll see it Online in Settings → Printers → Local agent, with the Home Assistant logo, and it will start looking for your printers.

There's nothing to create in BolloPrint beforehand. The Home Assistant card under New agent just reminds you of these steps.

---

The page's port

The agent's page uses port 8257 on the Home Assistant computer. If something else is already using it, the app stops as soon as it starts and its Log tab says address already in use. To change it:

1. On the app's page, open the Configuration tab.
2. Under Network, enter another number (for example 8364) and click Save.
3. Home Assistant asks whether to restart the app: accept. Open Web UI now takes you to the new port.

Changing the port doesn't unlink the agent: it's still the same one, with its printers.

---

Keeping it up to date

Two things get updated here, and you hardly ever have to do anything:

What	How it's updated
The agent, the part that talks to your printers	By itself. When BolloPrint publishes a new version, it downloads and installs it on its own.
The Home Assistant app, the part that starts the agent	When Home Assistant tells you there's an update for BolloPrint Agent, click Update on its page. If you turn on Auto update on that page, it will do it by itself.

Updating the app doesn't unlink the agent. Its identity is kept in the app's data, which is also included in Home Assistant's backups.

---

Moving it to another computer or reinstalling it

• If you reinstall the app or put it on another Home Assistant, link it again: it will be a new agent. Add your printers with it (it will find them by itself if they're on its network, or by IP) and they'll come across with their number and their whole history. Then delete the old agent, which will have been left with no printers.
• If you restore a backup that includes the app on the same Home Assistant, the agent comes back just as it was, already linked.

---

Uninstalling it

1. In BolloPrint, go to Settings → Printers → Local agent, open the agent's ⋮ menu and click Delete. The printers that were only reachable through it disappear from the list; if you ever add them again, they come back with their history.
2. Within a few seconds, the agent's page offers Link with BolloPrint again. If you no longer want it, open the ⋮ menu on the app's page in Home Assistant and click Uninstall.
3. If you like, remove the repository too: App store → ⋮ → Repositories, and the bin next to BolloPrint.

If you uninstall the app without deleting the agent first, it stays in BolloPrint as Offline. Delete it from its ⋮ menu.

---

When something isn't working

The first place to look is the app's Log tab in Home Assistant: it tells you what the agent is doing and, if it stops, why.

Symptom	What to do
BolloPrint Agent doesn't appear in the store	In the App store, ⋮ menu → Check for updates, and reload the page. If there's no Apps under Settings, your Home Assistant has no apps: install the agent with Docker.
It won't let you install it	Your computer is 32-bit, like a Raspberry Pi 3. The app needs 64 bits.
The installation fails halfway	Home Assistant downloads the agent when installing it: check that it has internet and try again.
The app stops as soon as you start it	Look at the Log. If it says address already in use, the port is taken: change it as explained above.
Open Web UI doesn't load	You're outside the workshop network (remote access, VPN, mobile data). Open it from the local network.
Your workshop doesn't appear when linking	You can only link the agent to workshops you're the owner of. Ask the owner to link it.
It doesn't find any printers	Is Home Assistant on the same network as them? In a virtual machine, its network has to be in bridge mode. If they're on separate networks, add them by IP: they work just the same.
You deleted it in BolloPrint and the page still says "Linked"	Wait a minute and reload: the agent restarts by itself, unlinked.