LabelZoom Print Agent

Beta feature

The cloud print agent is currently in beta and available to a limited group of users. Cloud enrollment and printing may change, and access is gated behind a feature flag on your account. To request access, apply for the private beta. Local (browser) printing — the original behavior — is generally available and does not require beta access.

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 phones home, 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)   └──────────────────┘                    └─────────┘

1. You add an agent in the LabelZoom dashboard and get a one-time enrollment code.
2. You install the agent and enroll it with that code; it stores its credentials locally.
3. The agent opens an outbound WebSocket to LabelZoom and registers your printers.
4. 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 (beta access required).

---

Windows

The recommended way to run the agent on Windows is the native installer. 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 advanced/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

1. Download and run labelzoom-print-agent-setup.exe. The wizard installs the agent to Program Files\LabelZoom\Print Agent.
2. 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.
3. 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

Any thermal printer that supports RAW printing over TCP/IP (port 9100), including Zebra (ZPL), Datamax/Honeywell (DPL), SATO, TSC (TSPL), and other direct-thermal / thermal-transfer printers. On Windows, USB printers are also supported via a RAW pass-through driver — see Install a Windows printer for RAW label printing.

Troubleshooting

• /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 or the agent won’t connect — enrollment codes are single-use and expire. Generate a fresh code in the dashboard and re-enroll (enroll --code <code>). Confirm the machine has outbound HTTPS/WSS access to api.labelzoom.com, and that your account has beta access.
• Nothing prints — verify the printer is reachable on port 9100 (nc <printer-ip> 9100) and that a USB printer on Windows uses the Generic / Text Only RAW driver and is shared to all users.