💾 Agent on TrueNAS

If you have a TrueNAS in the workshop, you already have somewhere to put the local agent: it's on all day and on the same network as your printers. The agent runs as just another TrueNAS app, alongside the ones you already have.

This page explains how to install it, link it to your workshop, update it, move it and remove it. What the agent is and which printers it connects is covered in The local agent.

---

Before you start

What you need	How to check
TrueNAS 24.10 or later (Community Edition)	In TrueNAS, Dashboard → System Information → Version. Earlier versions don't have Install via YAML.
TrueNAS apps turned on	In Apps, the top shows Apps Service Running. If it's the first time, TrueNAS asks you to choose the pool to keep them on.
Signing in to TrueNAS with an administrator user	Only an administrator can install apps.
Being the owner of the workshop in BolloPrint	When you link it, only the workshops you own are listed.
The TrueNAS and the printers being on the same network	If they're on separate networks the agent works just the same, but you'll have to add the printers by their IP.
The TrueNAS having internet access	That's all: no ports to open and no fixed IP needed.

---

1. Copy the YAML from BolloPrint

In BolloPrint, go to Settings → Printers → Local agent → New agent and choose TrueNAS.

You'll see the steps and, below them, a box with the YAML: the text that tells TrueNAS what to install. Click Copy.

There's nothing to create on that screen: the YAML is the same for every workshop and carries no keys. The agent comes to life when you link it, in step 3.

In case you're curious about what it does, the YAML looks like this (always copy the one from BolloPrint, which has the right version in the image: line):

services:
  bolloprint-agent:
    image: ghcr.io/bolloprint/bolloprint-agent:XXXX
    restart: unless-stopped
    network_mode: host
    mem_limit: 512m
    pids_limit: 512
    ulimits:
      nofile:
        soft: 65536
        hard: 65536
    environment:
      BP_PLATFORM: truenas
      BP_LINK_LISTEN: ":8257"
    volumes:
      - data:/var/lib/bolloprint

volumes:
  data:

x-portals:
  - name: Web UI
    scheme: http
    host: 0.0.0.0
    port: 8257
    path: /

• network_mode: host puts the agent on your TrueNAS's network: that's how it finds the printers.
• BP_LINK_LISTEN opens its page on port 8257, and x-portals is what puts the Web UI button in TrueNAS.
• data is the folder where the agent keeps its identity and its link. It survives restarts and updates.

---

2. Install it on TrueNAS

1. Sign in to TrueNAS and open Apps.
2. Click Discover Apps.
3. At the top right, next to Custom App, open the ⋮ menu and choose Install via YAML.
4. In Name, type bolloprint-agent.
5. In Custom Config, paste the YAML you copied.
6. Click Save.

TrueNAS downloads the agent and starts it. Within a minute it shows up in Apps → Installed as Running.

---

3. Link it to your workshop

1. In Apps → Installed, click bolloprint-agent. On the right, under Application Info, click Web UI. The agent's page opens in a new tab.
2. The page says "This agent does not belong to any workshop yet" and shows an eight-character code, like 6E7B-9DEF. Click Link with BolloPrint.
3. BolloPrint opens. If you're not signed in, sign in. Choose the workshop you're adding it to.
4. BolloPrint shows you the Device (your TrueNAS's name and "TrueNAS") and the Code. Check that it's the same one shown on the agent's page, give the agent a name and click Add to workshop.
5. You're taken back to BolloPrint, to the list of agents. The agent's page now says Linked to your workshop.

That's it. In Settings → Printers → Local agent you'll see the agent with the TrueNAS logo, Online.

---

4. Give it the printers

The agent starts looking for printers on your network as soon as it's linked. Whatever it finds shows up in Printers on the local network, below the list of agents, and that's where you register them. Any that don't show up on their own can be added with Add by IP.

How to do it for each brand is in Local network printers.

---

Updating it

You don't have to do anything. The agent updates itself: when a new version comes out, it downloads it, checks that it's ours and restarts with it. It keeps it in its data folder, so it stays on that version even if you restart the app or the TrueNAS.

That's why in TrueNAS the app still says Up to date and the image: line in its YAML doesn't change: that's the version it was installed with, not the one that's running. You can see the one that's running in BolloPrint, next to the agent.

Only if BolloPrint tells you that this agent needs a manual update:

1. In Apps → Installed, click bolloprint-agent and then Edit.
2. In Custom Config, change only the version at the end of the image: line to the one BolloPrint shows in New agent → TrueNAS. Don't touch anything else.
3. Click Save.

The agent stays linked to the same workshop, with the same printers and their history. There's nothing to link again.

---

Moving it to another computer or reinstalling it

An agent installed from scratch, on another computer or on the same one after deleting it, is a new agent:

1. Install it and link it as in steps 1 to 3.
2. Add your printers to the new agent: they move over to it with their history.
3. Delete the old agent in BolloPrint (Settings → Printers → Local agent, the agent's ⋮ menu → Delete).

---

Removing it

1. In BolloPrint, delete the agent: Settings → Printers → Local agent, the agent's ⋮ menu → Delete. Within a few seconds the agent finds out and its page offers Link with BolloPrint again.
2. In TrueNAS, Apps → Installed → bolloprint-agent → Delete.

If you only delete it in TrueNAS, it will keep showing as Offline in BolloPrint until you delete it there too.

---

If something isn't working

What you see	What to do
You can't find Install via YAML	Your TrueNAS is older than 24.10, or apps aren't turned on (in Apps, choose the pool it asks for).
The app doesn't get past Deploying or stays Stopped	The TrueNAS can't reach the internet to download the agent. Check the TrueNAS's network and start the app again from Apps → Installed.
Web UI opens a page that doesn't load	Another app is already using port 8257. In Edit, change ":8257" to ":8364" and the port: 8257 further down to port: 8364, both of them, and click Save.
The code in BolloPrint doesn't match the one on the page	Don't confirm. Go back to the agent's page and click Link with BolloPrint again.
The agent shows as Offline in BolloPrint	Check in TrueNAS that the app is Running and that the TrueNAS has internet access. Its log is in Apps → Installed → bolloprint-agent → Workloads, under the logs icon.
It's linked but doesn't find any printers	The TrueNAS and the printers have to be on the same network. If they aren't, add them with Add by IP.