labelzoom/print-agent repository overview

⁠LabelZoom Cloud Print Agent

A lightweight agent that lets you trigger label prints from the cloud to printers on your own network — think "Cloudflare Tunnel, but for label printers."

Install it on any machine that can reach your printers. It phones home to LabelZoom over a single outbound WebSocket (survives NAT/firewalls), so there are no inbound ports to open, no VPN, and no port forwarding. Your ERP/WMS/e‑commerce stack calls the LabelZoom API, and the label comes out on the right printer — wherever it is.

Manage agents and printers, trigger test prints, and watch live status from the Printers page at labelzoom.com⁠.

⁠Quick start

1. In LabelZoom, go to Printers → Add agent to get a one-time enrollment code (expires in 15 minutes).
2. Run the agent:

docker run -d --name lz-print-agent \
  -e LZ_ENROLL_CODE=<your-code> \
  -v lz-agent:/etc/labelzoom \
  labelzoom/print-agent

1. The agent appears on your Printers page. Add a printer (its IP/hostname on the agent's network) and send a test print.

The -v lz-agent:/etc/labelzoom volume persists the agent's identity, so restarts and upgrades reconnect without needing a new enrollment code.

⁠Environment variables

⁠Persistence

After enrollment, the agent writes its ID and key to /etc/labelzoom/agent.yaml. Mount a volume at /etc/labelzoom so it keeps its identity across restarts. Without a persisted volume, a restart requires a fresh enrollment code (codes are single‑use).

⁠Networking

• Outbound only: HTTPS/WSS to api.labelzoom.com (443). Nothing needs to listen for the cloud.
• To printers: the agent connects to your printers over the LAN using raw TCP (default port 9100).
• EXPOSE 8080 is only for the optional local browser‑print daemon (local mode) — it is not needed for cloud printing.

⁠High availability

A printer can be served by more than one agent. Run a second agent that can also reach the printer and add it as a failover on the Printers page; if the primary goes offline, a standby takes over automatically, and each job prints exactly once.

⁠Tags & architectures

• latest plus versioned tags.
• Multi‑architecture: linux/amd64 and linux/arm64.

⁠Notes

• Running on Windows desktop? Use the native LabelZoom installer instead of Docker — it can print to USB/LPT/local Windows printers as well as network printers.
• The agent's key is stored server‑side as a hash; treat the mounted config volume as a secret (it holds the agent key).

⁠Links

• Website / manage printers: https://www.labelzoom.com⁠
• Documentation: https://docs.labelzoom.com⁠