🐳 Agent on Docker

Docker is the way to install the agent on any computer, whether or not it has its own package. If your computer is a Synology, a QNAP, a TrueNAS, a Windows PC or Home Assistant, check its page in The local agent first: with the package there are fewer steps.

---

What you need

• A workshop computer that's always switched on: a NAS, a mini-PC, the workshop PC, a Raspberry Pi or a server you already have.
• Docker with Docker Compose, or Portainer, which is Docker with a screen.
• For it to be on the same network as the printers, so it finds them on its own.

It's lightweight: it doesn't need a powerful computer, and the manifest caps it at 512 MB of memory.

On Docker Desktop (Windows and Mac) there's no automatic discovery. There, Docker runs inside a virtual machine that can't see the computer's network, so printers are added by IP. They work exactly the same; there's just one extra step when registering them. On Windows, the Windows installer doesn't have that limitation.

---

Creating it in BolloPrint

1. Go to Settings → Printers and open the Local agent tab.
2. Click New agent. Under Where will you install it?, choose Docker, in With a container.
3. Give it a name you'll recognise. Better where it is than what it is: "Ground floor", "Unit 2".
4. Click Create agent.
5. The manifest appears, with the agent's code and its identity already written in. Leave the Docker Compose tab selected and click Copy. There's nothing to replace.
6. With the manifest saved somewhere safe, click Save to close the window.

This is what the manifest looks like. Yours carries your keys instead of CHANGE_ME and the agent version that's current at that moment instead of YYYY:

services:
  bolloprint-agent:
    image: ghcr.io/bolloprint/bolloprint-agent:YYYY
    container_name: bolloprint_agent
    restart: unless-stopped
    network_mode: host
    mem_limit: 512m
    pids_limit: 512
    ulimits:
      nofile:
        soft: 65536
        hard: 65536
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    environment:
      BP_AGENT_CODE: CHANGE_ME
      BP_AGENT_INSTANCE_ID: CHANGE_ME
      BP_PLATFORM: docker
    volumes:
      - identity:/var/lib/bolloprint

volumes:
  identity:
    name: bolloprint_agent_identity

Don't copy this one: always copy yours from the screen in BolloPrint, which is the one that carries your keys.

Two lines worth understanding:

• BP_AGENT_CODE and BP_AGENT_INSTANCE_ID are the agent's keys: who it is and which workshop it works for. Treat them like a password.
• network_mode: host is what lets the agent see your network to find the printers. It doesn't open any port.

---

Starting it on your computer

The manifest goes in as is, without changing anything. Pick whichever method you use.

Docker Compose

1. Create a folder for the agent, for example bolloprint-agent.
2. Inside it, save the manifest as docker-compose.yml.
3. From that folder, start it:

docker compose up -d

Portainer

1. Go to Stacks → Add stack and give it a name, for example bolloprint-agent.
2. In Web editor, paste the manifest as is.
3. Click Deploy the stack.

Your NAS's container manager

If your NAS comes with its own container manager (Synology's Container Manager, for example), create a new project, paste the manifest as its docker-compose.yml and start it. It's the same as Docker Compose, with a screen.

---

Checking it works

In under a minute, the agent goes from Not installed to Online in the Local agent tab, with the name of the computer it runs on and its version. It won't ask you for authorisation: that installation comes already authorised.

If it doesn't show up, look at its log on the computer it runs on:

docker logs bolloprint_agent --tail 50

What's happening	What to check
It never shows up	Was the whole manifest pasted, unchanged? Can the computer reach the internet? Is a firewall blocking outbound traffic?
It shows up, but asks for authorisation	The manifest doesn't include BP_AGENT_INSTANCE_ID (it was edited by hand or is an older one). Regenerate the keys and deploy the new manifest as is.
It's online but doesn't find any printers	If it's on a different network from the printers or you're using Docker Desktop, that's expected: add them with Add by IP.

With the agent online, the next step is connecting your printers: you'll find it in Local network printers.

---

Updating it

From version 2026.1.1 on, the agent updates by itself: when a new version comes out, it downloads it, checks that it's ours and restarts with it. It never does so while any of its printers is printing. You don't have to touch your file.

You only need to do it by hand if BolloPrint asks you to (for example, an agent installed a while ago, with a version from before automatic updates). You'll see it like this:

• Above the tabs in Settings → Printers, a notice with your agent's name: "“Ground floor” runs version XXXX. Version YYYY is now available", with the How to update button.
• In the Local agent tab, that agent's version number in orange. In red, that version is no longer supported and you should update as soon as possible.

What changes

Only the image: line changes, and within it only the version, what comes after the colon. Everything else stays exactly the same: the keys, the volume and the rest of the configuration.

You'll find the version to use in your agent's Deployment tab (⋮ → Edit menu): it's the one in the image: line.

Before

    image: ghcr.io/bolloprint/bolloprint-agent:XXXX

After

    image: ghcr.io/bolloprint/bolloprint-agent:YYYY

With Docker Compose

1. Open the agent's docker-compose.yml and change the version in the image: line.
2. From that file's folder, pull the new version and start it again:

docker compose pull
docker compose up -d

Docker replaces the container with a new one, with the same configuration and the same volume.

With Portainer

1. Go to Stacks and open the agent's stack.
2. Click Editor and change the version in the image: line.
3. Turn on Re-pull image and redeploy (or Pull latest image, depending on your Portainer version) and click Update the stack.

Checking it went well

Within a minute the agent shows up again as Online, with the new version and no warning colour. The notice above the tabs disappears on its own. While the container restarts, the printers may show up as Disconnected for a few seconds: they come back on their own, and any prints in progress carry on running on the machine.

What if the new version gives you trouble? Put the previous version back in the image: line and deploy the same way. Then open a case in support so we can take a look.

---

Moving it to another computer

The agent's identity is inside the manifest (BP_AGENT_INSTANCE_ID), so the same file started on another machine is the same agent: with its printers, without asking for authorisation and with nothing else to copy over.

1. On the old computer, stop it: docker compose down in its folder, or delete the stack in Portainer.
2. Take the docker-compose.yml to the new computer and start it there with docker compose up -d.

Stop the old one before starting the new one: two computers with the same keys at the same time trip over each other's connection.

If your manifest is an older one and doesn't have the BP_AGENT_INSTANCE_ID line, when you start it on another computer the agent will show up as an installation awaiting authorisation (further down). Authorise it and it's still the same agent, with all its history.

Don't have the file any more? Then regenerate the keys and deploy the new manifest on the new computer.

---

Regenerating the keys

In the agent's window (⋮ → Edit menu), Deployment tab, Regenerate keys creates a new code and identity and shows you the manifest with them.

Use it in two cases:

• You've lost the manifest and need to deploy the agent again.
• You think someone has your keys, for example because an installation that isn't yours shows up.

It cuts the agent off immediately: the previous code and identity stop working the moment you click the button, and the agent stays disconnected until you deploy it again with the new manifest. This time you do paste the whole manifest, in place of the one you had, and start it again (docker compose up -d, or Update the stack in Portainer). The volume stays as it is.

If the agent never got to connect (it shows Not installed), regenerating doesn't cut anything off.

You don't need to regenerate to update. Changing the image version is enough.

---

Authorising installations

The installation from the manifest you copied goes straight in. Any other installation using that same code waits for your approval: you'll see a red notice above the tabs and, inside the agent, under Status, the installation listed in Installations awaiting authorisation, with the name of the computer it's connecting from.

With a current manifest this hardly ever happens. It's normal for it to happen with an older agent, deployed with a manifest without BP_AGENT_INSTANCE_ID, when you move it to another machine, delete its volume or reinstall it from scratch.

Click Authorise if you recognise the computer. Authorising one revokes the previous one's access.

---

Removing it

1. In BolloPrint, on the agent's row, ⋮ → Delete menu. Its printers leave the list with it (their history isn't lost: see The local agent).
2. On your computer, stop and delete the container: docker compose down in its folder, or delete the stack in Portainer. BolloPrint can't do it for you.
3. If you're not going to use it again, delete its volume too:

docker volume rm bolloprint_agent_identity

---

What NOT to do

• Don't use the same manifest on two computers at once. For two computers, two agents, each with its own.
• Don't regenerate the keys to update. It cuts the agent off until you deploy it again.
• Don't create a new agent to update. Updating is the same agent on a different version; a new one would have different keys and its printers wouldn't carry over on their own.
• Don't change the keys in the manifest by hand or copy them into another installation.

---

Frequently asked questions

Do I have to open ports? No. The agent calls BolloPrint, not the other way round, and it doesn't publish any port on your computer.

Do I lose printers or history when I update or move it? No. The printers and everything they've printed live in BolloPrint, not in the agent.

Can I skip versions? Yes. Go straight to the one shown in the Deployment tab.

What's the volume for? So the agent can keep its log of the last few days and the versions it downloads when it updates. On agents deployed with an older manifest, its identity too. It doesn't store print data.

Does it work on a Raspberry Pi? Yes. The image works on Intel/AMD and ARM computers; Docker picks the right one by itself.