Connecting an Agent

The Agent is a small piece of software that runs on a computer at your site and maintains a secure connection to Pluraprint. It’s the only thing that talks directly to your physical printers: once it’s connected, every printer you add to that site becomes reachable from your dashboard, no matter where you are.

You’ll need at least one agent running at each site that has printers. A single agent can typically serve every printer at that location, as long as it’s on the same local network as the printers.

Step 1: Generate an enrollment token#

1. Open Agents under the Fleet section of the sidebar.
2. Select Enroll Agent.
3. Choose the Site this agent belongs to.
4. Give the agent a recognizable name (for example, main-lab-agent or library-front-desk).
5. Select Generate Token.

You’ll be shown an Agent ID and a one-time enrollment token, along with an expiration time. Copy both. You’ll need them in the next step, and the token can’t be retrieved again once you close the dialog.

Step 2: Deploy the agent#

The agent runs as a small service on a computer at your site. This can be a dedicated mini PC, an existing server, or a virtual machine, as long as it stays powered on and connected to the internet, and is on the same local network as your printers.

Whichever way you run it, the agent needs these four settings:

Environment variable	Value
AGENT_SERVER_URL	The web address of your Pluraprint deployment
AGENT_ID	From Step 1
AGENT_ENROLLMENT_TOKEN	From Step 1
AGENT_NAME	A friendly name (matches what you entered in Step 1)

With Docker#

Create a folder for the agent on the machine that will run it, put the four settings in a .env file there, and start it:

docker run -d \
  --name pluraprint-agent \
  --restart unless-stopped \
  --network host \
  --env-file .env \
  -v pluraprint-agent-data:/data \
  ghcr.io/lemony-click/pluraprint-agent:latest

--network host lets the agent see your printers directly. Several printer protocols, network discovery, and Bambu Lab’s MQTT and file transfer: don’t survive the address translation a normal Docker network applies, so the agent won’t find those printers without it.

The /data volume holds the agent’s identity once it enrolls. Keep it: if you delete it, the agent has to be enrolled again with a fresh token.

If you’d rather manage it as a Compose service, the repository ships a ready-made docker-compose.agent.yaml that does the same thing.

Without Docker#

Sites that don’t run containers can use a standalone executable instead. Each Pluraprint release publishes agent binaries for Linux, macOS, and Windows, with a SHA256SUMS.txt to verify a download against. Download the one for your platform, set the same four environment variables, and run it as a service: systemd on Linux, a Windows service, or a launchd job on macOS.

After it starts#

The agent connects to Pluraprint, completes enrollment automatically using the token, and establishes a persistent connection. The token is consumed and can’t be reused.

The agent only ever dials out. It never accepts incoming connections, so it needs no inbound firewall rule and no port forwarding.

Checking agent status#

Back on the Agents page, your agent will show one of the following statuses:

Status	Meaning
Pending enrollment	A token has been generated but the agent hasn’t connected yet.
Online	The agent is connected and ready.
Offline	The agent has connected before but isn’t currently reachable.
Revoked	The agent’s access has been permanently disabled.

The page also shows the agent’s software version, how many printers (devices) it’s connected to, and when it was last seen.

Leave the page open while you deploy. It updates on its own as an agent enrolls, connects, or drops, so Pending enrollment becomes Online within moments of the agent starting. There is nothing to refresh.

My agent isn’t showing as Online#

• Confirm the computer running the agent has internet access and can reach your Pluraprint server address.
• Check that the enrollment token hadn’t expired before the agent started.
• Confirm any firewall on the network allows outbound connections from the agent.
• It’s normal for an agent to briefly show Offline after a network blip. It reconnects automatically, and the page follows it back to Online by itself.

Rotating or revoking an agent#

• Rotate token generates a new enrollment token for an agent that’s already connected. The agent’s current connection is closed, and it must re-enroll using the new token to reconnect. Use this if you suspect a token or credential has been exposed.
• Revoke permanently disables an agent. Its connection is closed and it can’t reconnect. Any printers it served are disabled to avoid leaving them in a stuck state. Use this when retiring a machine for good: to bring that location back online, enroll a new agent.

What’s next#

With an agent online, you’re ready to add the printers at this site.

→ Adding a Printer