LabelZoom Print Agent

The LabelZoom Print Agent is a small program you install on a machine near your printers. It lets LabelZoom send label commands (ZPL, EPL, DPL, TSPL, …) straight to your thermal printers in their native language, so barcodes and text reproduce exactly.

It runs in either — or both — of two modes:

Local mode (generally available): the LabelZoom Web App in your browser posts print jobs to the agent on localhost, and the agent forwards them to a printer on your network over TCP port 9100.
Cloud mode (beta): the agent registers against your LabelZoom account with a one-time enrollment code and holds a single outbound WebSocket to the cloud. Jobs triggered from the dashboard, the REST API, or your integrations are pushed down in real time and printed to the printers you configure online. Because the connection is outbound-only, there are no inbound ports to open and no firewall or NAT changes. Jobs queued while the agent is offline drain automatically when it reconnects.

How cloud mode works

┌──────────────┐   push job    ┌──────────────────┐   TCP 9100 / USB   ┌─────────┐
│  LabelZoom   │ ────────────► │   Print Agent    │ ─────────────────► │ Printer │
│  cloud/API   │  (WebSocket,  │  (your machine)  │   (RAW ZPL/EPL…)   │ (Zebra) │
└──────────────┘   outbound)   └──────────────────┘                    └─────────┘

You add an agent in the LabelZoom dashboard and get a one-time enrollment code.
You install the agent and enroll it with that code; it stores its credentials locally.
The agent opens an outbound WebSocket to LabelZoom and registers your printers.
Print jobs from the dashboard, API, or integrations are pushed to the agent and sent to the printer.

Prerequisites

A machine on the same network as your printer(s), able to reach them on TCP port 9100 (network printers) — or a printer connected by USB on Windows.
For cloud mode: outbound HTTPS/WSS access to api.labelzoom.com and a one-time enrollment code from your LabelZoom dashboard.

Windows

The native installer is the recommended way to run the agent on Windows. It installs the agent as a background Windows service — no Docker and no console window to keep open — that auto-starts on boot.

Downloads (latest release):

labelzoom-print-agent-setup.exe — the installer (recommended).
lz-print-agent.exe — the standalone executable, for portable use or scripting.

Released binaries are EV code-signed (RJF Technology Solutions LLC), so Windows SmartScreen shows the verified publisher and does not warn.

Install

Download and run labelzoom-print-agent-setup.exe. The wizard installs the agent to Program Files\LabelZoom\Print Agent.
On the Enrollment page, optionally paste the one-time enrollment code from your LabelZoom dashboard to enable cloud printing (beta). Leave it blank to run in local (browser) mode only — you can enroll later.
The installer registers and starts the LabelZoom Print Agent service (auto-starts on boot).

The local browser-print endpoint listens on http://localhost:52045 (the port the web app uses). Verify it’s running:

curl http://localhost:52045/ping     # -> {"message":"pong"}

Manage the service

From an administrator prompt, in the install directory:

lz-print-agent.exe service status                  # running | stopped | unknown
lz-print-agent.exe enroll --code <ENROLLMENT_CODE> # enroll (or re-enroll) for cloud mode (beta)
lz-print-agent.exe service restart                 # apply a config change

Config & logs: credentials at %ProgramData%\LabelZoom\agent.yaml; the service writes logs to %ProgramData%\LabelZoom\logs\agent.log (there is no console under the service).
Uninstall: via Settings → Apps (Add/Remove Programs); this stops and removes the service.
USB / local printers: network (TCP 9100) printers work out of the box. A USB printer must be installed for all users / shared to be visible to the service (which runs as LocalSystem), and should use the Generic / Text Only driver for RAW pass-through — see Install a Windows printer for RAW label printing.

Docker

Docker is the easiest way to run the agent on Linux, macOS, or any host with a container runtime. Pre-built images are on Docker Hub: labelzoom/print-agent.

Local (browser) mode

A bare docker run starts the agent in local mode for browser printing:

docker run -d -p 52045:8080 --restart unless-stopped labelzoom/print-agent

The agent listens on port 8080 inside the container; the example remaps it to 52045 on the host (the port the web app uses). Port 8080 is commonly taken, so a high port (50000+) is recommended.

Cloud mode (beta)

Pass your one-time enrollment code with LZ_ENROLL_CODE; the agent enrolls on first start and then connects to the cloud. Mount a volume so the saved credentials survive container restarts — otherwise the agent re-enrolls, and the code is single-use:

docker run -d --name lz-print-agent \
  --restart unless-stopped \
  -e LZ_ENROLL_CODE=<ENROLLMENT_CODE> \
  -v lz-agent-config:/etc/labelzoom \
  labelzoom/print-agent

In cloud mode the connection is outbound-only, so no -p port mapping is needed. Add one only if you also want local browser printing from the same container.

Docker Compose

services:
  lz-print-agent:
    image: labelzoom/print-agent:latest
    restart: unless-stopped
    environment:
      # Cloud mode (beta): drop this line for local-only browser printing.
      - LZ_ENROLL_CODE=<ENROLLMENT_CODE>
    volumes:
      - lz-agent-config:/etc/labelzoom
    # Uncomment for local browser printing on the host:
    # ports:
    #   - "52045:8080"

volumes:
  lz-agent-config:

docker compose up -d

On Linux, run the agent with Docker (above) — a native Linux binary isn’t published yet.

Configuration reference

Setting	Default	Notes
Enrollment code	—	One-time code from the dashboard. Flag `--code` or env `LZ_ENROLL_CODE`.
Config / credentials file	`%ProgramData%\LabelZoom\agent.yaml` (Windows), `/etc/labelzoom/agent.yaml` (Linux/macOS)	Override with `--config` or `LZ_CONFIG`.
API base URL	`https://api.labelzoom.com`	Override with `--api` or `LZ_API_BASE_URL`.
Local daemon address	`:8080`	Local browser-print listener. Override with `--local` or `LZ_LOCAL_ADDR`.
Printer port	`9100`	Standard RAW port for network thermal printers.

CLI subcommands:

lz-print-agent enroll --code <code>   Register this machine with a dashboard pairing code
lz-print-agent run                    Run the agent (cloud mode if enrolled, else local-only)
lz-print-agent version                Print the version

Supported printers

Network printers (TCP 9100). Any thermal printer that accepts RAW commands on port 9100, from any agent (Windows or Docker): Zebra (ZPL), Datamax/Honeywell (DPL), Intermec/Honeywell (IPL), SATO (SBPL), TSC (TSPL), and other direct-thermal / thermal-transfer printers. Pick the Zebra printer type in the dashboard for a ZPL printer: the agent then reads the printer’s own status (media out, head open, paused) and identity. For other brands pick Generic, which reports reachability only.

USB and local printers (Windows only). A Windows agent can print to any printer installed in Windows — USB, LPT, or a shared queue — in one of two modes:

RAW — the label commands go to the printer unchanged. Use the Generic / Text Only driver; see Install a Windows printer for RAW label printing.
Driver — for printers that do not speak a label language at all, such as Rollo, DYMO, and Brother label printers. LabelZoom renders the label in the cloud at the printer’s resolution (203 or 300 dpi) and the agent prints it through the installed Windows driver.

A Docker agent (Linux, macOS, NAS) prints to network printers only; there is no USB or driver path outside Windows yet.

Security

Outbound only. In cloud mode the agent opens one outbound WebSocket to api.labelzoom.com and polls the same host over HTTPS. Nothing listens for inbound connections; there are no ports to open, and it works behind NAT and outbound-only firewalls. (Local browser mode additionally listens on localhost for the web app.)
What the enrollment code is. A single-use, 15-minute pairing code tied to your account. Redeeming it gives the agent a long-lived agent key — the only credential it ever holds — and consumes the code. The key is saved on the machine in agent.yaml, readable by the agent’s user only; LabelZoom stores only a hash of it. Treat the file like a password: anyone who has it can print to your printers.
Revoking an agent. Remove the agent in the dashboard. Its key stops working immediately and its printers are removed with it; the software on the machine can be uninstalled at leisure (it logs a clear “re-enroll” error). To move an agent to another machine, remove it and enroll again with a fresh code.
What the agent does on the machine. It makes outbound HTTPS/WSS connections, writes its own config and log, lists the printers installed in Windows so the dashboard can offer them, and sends bytes to the printers you configured. It accepts no commands other than print jobs for those printers.
What LabelZoom stores. A print job’s document is stored while the job is in flight, so an offline agent can pick it up later, and is deleted as soon as the agent confirms the print. A failed job keeps its document for about a day so you can retry it, then it is deleted too; the job’s status history stays for 30 days. Printer status reports and configuration labels are stored so the dashboard can show them. See Cloud Print limits for the retention note alongside the plan terms.

Printing copies

When a print request asks for copies, the agent sends the job to the printer that many times. This works for every printer the agent serves — network or USB, RAW or Windows driver — but it needs an up-to-date agent. If an agent serving the printer is too old to print copies, a request for more than one copy is refused with 422 agent_update_required and nothing prints. Requests without copies keep printing as before.

Windows: enrolled installs update themselves automatically unless Automatically install updates was turned off during setup. To update right away, run lz-print-agent.exe update from an administrator prompt in the install directory, or download and run the latest installer.
Docker: the container doesn’t update itself. Pull the latest labelzoom/print-agent image and recreate the container — docker compose pull && docker compose up -d with Docker Compose, or docker pull labelzoom/print-agent, then remove the old container and start it again with the same docker run command. With the configuration volume mounted as shown in Cloud mode, the new container keeps its enrollment.

Windows driver printers

A Windows printer set to the Windows driver print mode in the dashboard — for label printers such as DYMO, Brother, and Rollo that don’t speak a printer language — receives each label as an image and prints it through its installed Windows driver. For those printers the agent sets the driver’s copy count, and the copies print collated, as on any other printer.

Some Windows drivers limit the copy count. If the driver can’t print as many copies as requested, the job fails with an error giving the driver’s maximum — it never prints a different number. Ask for fewer copies per job, or split the run into several jobs.

Troubleshooting

Where to look first. On Windows the service logs to %ProgramData%\LabelZoom\logs\agent.log; with Docker, docker logs lz-print-agent. Every job the agent handles is logged with its outcome, and the dashboard’s printer Queue shows each job’s status and the error the agent reported, if any. Include both when you contact support.

/ping doesn’t respond — the agent isn’t running or the port is remapped. On Windows check lz-print-agent.exe service status; with Docker check the host port in your -p mapping.
Enrollment fails — codes are single-use and expire after 15 minutes. Mint a new one in the dashboard and re-enroll (enroll --code <code>). “Invalid or expired enrollment code” from a Docker agent that used to work means the container was recreated without its volume (Watchtower and docker compose up on a new image both do this): the saved key was lost and the old code replayed. Mount -v lz-print-agent:/etc/labelzoom and enroll again.
The agent shows Offline in the dashboard but is running — it cannot reach api.labelzoom.com over HTTPS and WebSocket. Corporate proxies and TLS-inspecting firewalls are the usual cause: the WebSocket upgrade must be allowed through, and a proxy that re-signs certificates is rejected. Allow api.labelzoom.com on port 443 without inspection.
A job stays “queued” — no agent bound to that printer is online. Check the agent’s status on the Printers page; a queued job prints the moment an agent reconnects.
The agent is online but nothing prints — the job will show failed in the Queue with the agent’s error. The common ones: the printer is not reachable on port 9100 from the agent’s machine (nc <printer-ip> 9100 there, not from your laptop); a Windows printer name that does not match the installed queue exactly; a USB printer installed for one user only (the service runs as LocalSystem — share it or install it for all users); or a driver that is not RAW (see the RAW driver guide).
Labels come out wrong — wrong size, rotated, or garbled — the printer’s native language in the dashboard does not match the printer (a ZPL printer set up as EPL, say), or a driver-mode printer is set to the wrong dpi. Fix the printer’s settings and print again; nothing is cached.
“Limit reached” or “too many requests” — you have hit one of the beta limits. The Printers page shows how much of each you have used and when the daily job count resets.