Set up the Farin label print agent

The Farin label agent connects one location computer to the Zebra network printers at that location. Staff can submit saved label batches from Print Labels, including from a phone or tablet, without installing the agent on each device.

Browser print remains available without an agent. For design and product setup, see Design and print reusable product labels.

Quick facts

Start here

Use one active agent per location. One agent can serve the Zebra printers it can reach on that local network.
A manager creates the one-use pairing code and can disconnect an agent. The code expires after 10 minutes.
The agent is a standalone program; it does not require Node.js. Pair and run it as the same operating-system user so both commands use the same private config file.
If this computer has the older Node agent installed, stop it before starting the Rust agent. Both programs use the same config and pairing token.
It makes outbound HTTPS connections to Farin and local printer connections for discovery and printing. It does not listen for inbound connections.
An agent can report that a printer accepted data, but that does not prove the labels physically came out.

Choose a computer and download the right build

Keep browser print as a fallback

The agent is optional. You can still print from the current device through its normal print dialog while setting up or troubleshooting the location computer.

Use a computer that stays powered on and connected to the printer network. For a Raspberry Pi Zero 2 W or 3 A+, use Raspberry Pi OS Lite 64-bit Bookworm or newer (glibc 2.36 or newer). For Linux x64, use Ubuntu 22.04 or newer, or a compatible distribution with glibc 2.35 or newer. Confirm that the operating system is 64-bit before selecting a Linux build.

In Print Labels, open Set up a site printer and choose the build that matches the computer: Linux ARM64 for those Raspberry Pi models, Linux x64 for a 64-bit Intel or AMD Linux computer, macOS ARM64 for Apple silicon, macOS x64 for an Intel Mac, or Windows x64 for a 64-bit Windows computer. Both macOS builds require macOS 13.0 or newer. The Windows archive includes its MSVC runtime, so no separate Visual C++ runtime installation is needed. Farin shows the version next to the download and links to checksums for that same version.

Use the downloadable archive provided by Farin. Do not download a binary from a third-party mirror.
Download the matching SHA256SUMS file from the Farin setup panel and verify the archive before extracting it. Keep it beside the downloaded archive. On Linux, use sha256sum --ignore-missing --check SHA256SUMS; on macOS, use shasum -a 256 --ignore-missing --check SHA256SUMS. On Windows, compare Get-FileHash .\farin-label-agent-windows-x64.zip -Algorithm SHA256 with the Windows archive entry in SHA256SUMS.
The macOS releases are not signed or notarized by Apple. After the archive checksum matches, macOS may show its normal first-run security prompt. If you choose to continue, use the standard Privacy & Security → Open Anyway flow; do not disable Gatekeeper or remove the quarantine flag.
If Farin reports that no agent release is available, use Browser print until a release is published.

Create a pairing code and pair the computer

Create a one-use code for the location

In Print Labels, open Set up a site printer, choose the printer location, enter a clear agent name, then create a pairing code. Pair the computer before the code expires in 10 minutes.

Only a manager can create the code or disconnect an agent. A location can have one active agent; disconnect its existing agent before pairing a replacement.

Pair as the operating-system account that will run the agent

Extract the archive, open a terminal or PowerShell in the program folder, and run the pairing command shown in Farin. It includes the one-use code and your Farin server address; do not share or save the command. The command follows this form on Linux or macOS: ./farin-label-agent pair --code CODE --server HTTPS_URL. On Windows, use .\farin-label-agent.exe pair --code CODE --server HTTPS_URL. Add --name NAME only if you want to change the agent name.

The agent saves its pairing token in a config file for the current operating-system account. On Linux and macOS it uses ~/.config/farin/label-agent.json (or $XDG_CONFIG_HOME/farin/label-agent.json when set); on Windows it uses %APPDATA%\Farin\label-agent.json. Unix file permissions are restricted by the agent; Windows uses the account’s existing file permissions. Protect the file like a password. Do not send it in support messages or copy it to another location.

Add a printer on another private subnet when needed

The agent searches the local private network for compatible printers. If a printer is on another private subnet and cannot be discovered, run ./farin-label-agent add-printer --host PRIVATE_IP from the extracted folder on Linux or macOS, or .\farin-label-agent.exe add-printer --host PRIVATE_IP in PowerShell on Windows. Use the printer’s current private IPv4 address, then restart the agent so it scans that address.

Keep the agent running after restart

From the extracted folder, run ./farin-label-agent run on Linux or macOS, or .\farin-label-agent.exe run in PowerShell on Windows, to start the agent in the foreground. For regular use, configure the operating system to start it automatically and restart it if it exits. The service or task must run as the same operating-system account that you used for pairing; otherwise it will look for a different config file.

Linux with systemd

Extract the Linux archive, open a terminal in its versioned folder, and run ./install.sh as the regular Linux user who will run the agent. The helper installs farin-label-agent to ~/.local/bin and the supplied systemd user unit to ~/.config/systemd/user (or $XDG_CONFIG_HOME/systemd/user when set). It does not start the service yet. Pair from that same account with ~/.local/bin/farin-label-agent pair --code CODE --server HTTPS_URL, then start the unit.

Enable and start the user service with systemctl --user enable --now farin-label-agent.service. Check it with systemctl --user status farin-label-agent.service and journalctl --user -u farin-label-agent.service.
The unit runs as your Linux user so it reads that user’s pairing config. Do not run the installer or pairing command as root and then start the user unit under another account. To start a user service at boot even when that account has not logged in, an administrator can run sudo loginctl enable-linger USER for the same account.

Windows with Task Scheduler

The Windows ZIP contains the executable but does not install a background service. From PowerShell in the extracted version folder, pair with .\farin-label-agent.exe pair --code CODE --server HTTPS_URL and run .\farin-label-agent.exe run to test it. Press Ctrl+C to stop the foreground run before configuring the task.

In Task Scheduler, choose Create Task. On General, set the user to the same Windows account used to pair the agent, select Run whether user is logged on or not, and leave Run with highest privileges unchecked. Windows keeps the config at %APPDATA%\Farin\label-agent.json for this account; do not choose SYSTEM.
On Triggers, add At startup. On Actions, choose Start a program. Set Program/script to the full path of farin-label-agent.exe, such as C:\Users\USERNAME\farin-label-agent-vVERSION\farin-label-agent.exe; set Add arguments to run; and set Start in to the extracted folder, such as C:\Users\USERNAME\farin-label-agent-vVERSION. Replace USERNAME and VERSION and use your actual extraction path.
On Settings, enable restarting the task if it fails. Save the task, enter the account password if Windows asks for it, then start the task once and confirm it appears online in Farin.

macOS with launchd

The macOS archive includes install.sh; it installs the executable to ~/.local/bin but does not install a launchd unit. Extract the archive, open Terminal in its versioned folder, and run ./install.sh. Pair with ~/.local/bin/farin-label-agent pair --code CODE --server HTTPS_URL; use ~/.local/bin/farin-label-agent run to test, then press Ctrl+C before setting up launchd.

Run mkdir -p ~/Library/LaunchAgents ~/Library/Logs, then create or edit ~/Library/LaunchAgents/app.farin.label-agent.plist in a plain-text editor as a property-list XML dictionary. Set Label to app.farin.label-agent; set ProgramArguments to an array containing /Users/USERNAME/.local/bin/farin-label-agent and run; set RunAtLoad and KeepAlive to true; and set both StandardOutPath and StandardErrorPath to /Users/USERNAME/Library/Logs/farin-label-agent.log. Replace USERNAME with the account name. This launches the binary and saves output to the log file.

Validate the file with plutil -lint ~/Library/LaunchAgents/app.farin.label-agent.plist, then load it with launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/app.farin.label-agent.plist. Check it with launchctl print gui/$(id -u)/app.farin.label-agent; stop or unload it with launchctl bootout gui/$(id -u)/app.farin.label-agent.
A LaunchAgent starts only after that user signs in and runs as that account, so pair under the same account. If printing must start before login, ask your administrator to configure a service account and pair the agent under that account.

Connect printers and send a test batch

The agent uses outbound HTTPS to reach Farin. On the local network it uses HTTP on printer port 80 to discover Zebra model, identity, readiness, and label dimensions, then TCP port 9100 to send the print data. It does not open an inbound port. Allow those outbound connections in local firewall rules; do not forward ports from the internet to the agent or printer.

In Print Labels, refresh devices and wait for the agent and printers to appear. Confirm the printer has the correct label stock loaded, create a small test batch, and check the printed label before a larger run. The design’s default printer can be saved from Edit label designs.

A phone or tablet can submit work through the Farin PWA. Install no agent on the mobile device; the paired location computer does the network printing.
Keep the agent and printer on a network that allows local device-to-device traffic. Guest Wi-Fi or wireless client isolation can block discovery and printing.

Protect, update, and disconnect the agent

The pairing code can be used once and expires after 10 minutes. The saved agent token lets that computer check in and receive jobs for its paired location, so keep the config file readable only by the operating-system account that runs the agent.
If the computer is replaced, sold, or may have exposed its config file, disconnect the agent in Set up a site printer. This revokes its token. Create a fresh code and pair the replacement computer.
Agent releases do not install themselves. Check the version with ~/.local/bin/farin-label-agent --version on Linux or macOS, or .\farin-label-agent.exe --version in PowerShell from the extracted folder. Download and verify the latest published build from Farin, stop the service or task, replace the program, then start it again. Keep the config file and any .pending journal file in place.

Replace a disconnected agent with pending outcomes

Stop and review the old agent

Stop the old service or scheduled task, then disconnect the old agent in Set up a site printer. Physically inspect the printer output and review the pending or uncertain jobs in Farin before resetting the local pairing. A disconnected token cannot acknowledge its saved outcomes.

Archive the old local pairing and pair again

Run ~/.local/bin/farin-label-agent reset --archive on Linux or macOS, or .\farin-label-agent.exe reset --archive in PowerShell on Windows. Run it as the same operating-system account that owned the old config. It archives the private config and pending journal; it does not send or replay print jobs. Create a fresh pairing code, pair the replacement under the account that will run it, and start the service or task again.

Keep the archive private because it contains the old pairing token. The old jobs remain in Farin history. Resolve them by checking the physical output and Farin history; only manually retry an unresolved job after confirming its output to avoid duplicates.

Troubleshoot connection and print issues

The agent or printer does not appear

Check that the computer is powered on, connected to the internet, and on the expected location network. Confirm the agent process or system service is running, then refresh devices in Farin.

Check that local firewall rules allow the computer to reach the printer on HTTP port 80 and TCP port 9100. Make sure the printer is powered on, connected to the same private network, reporting ready, and not isolated behind guest Wi-Fi. If it is on a different subnet, add its current private IP with add-printer --host PRIVATE_IP.

The printer received a new DHCP address

The agent matches a printer by its MAC address or serial number and can rediscover it after its address changes. Refresh devices after a network change. If a printer still cannot be found, check its new address and subnet, then run farin-label-agent add-printer --host NEW_PRIVATE_IP and restart the agent.

The agent is offline after Wi-Fi loss or a computer restart

Reconnect the computer to the location network. Confirm its automatic task or service starts after boot and runs under the account that has the pairing config. A LaunchAgent on macOS starts at user login; a Windows startup task or Linux systemd service can start before a user signs in.

A job is marked uncertain

An interrupted printer write or missing acknowledgement can leave the result uncertain. The printer may have accepted all, some, or none of the data. The agent does not automatically resend an uncertain job. Check the printer and physically inspect the labels first, then use Farin’s deliberate retry action only after you decide a possible duplicate is acceptable.

A successful TCP send confirms that bytes were accepted by the printer connection, not that correct labels came out. Always inspect the first label in a batch.