Install the agent

Run the PrintEasy agent as a service on macOS, Windows or Linux.

The agent is a small background service that reports your printers and prints jobs sent to them. It lists the printers the operating system already knows, receives print jobs from the API and hands them to the local print spooler. It only makes outbound HTTPS and WebSocket connections (port 443), so no ports need to be opened. Install it once per computer.

Downloads

The download page lists every installer. You can also fetch files directly.

Every file lives under https://downloads.adfinite.com/agent/<version>/. The current <version> is the version field of latest.json, and its installers map lists the full URL of each file.

Platform	File
macOS	PrintEasyAgent-<version>.pkg
Windows	PrintEasyAgent-<version>-x64.msi
Debian and Ubuntu	printeasy-agent_<version>_amd64.deb, printeasy-agent_<version>_arm64.deb
Fedora, RHEL and SUSE	printeasy-agent_<version>_amd64.rpm, printeasy-agent_<version>_arm64.rpm
Linux tarball	printeasy-agent_<version>_linux_amd64.tar.gz, printeasy-agent_<version>_linux_arm64.tar.gz

Install

macOS

Run the one-liner in Terminal:

curl -fsSL https://downloads.adfinite.com/agent/install.sh | sudo sh

Or download the .pkg for your Mac and open it. Download links for every file are listed in latest.json.

The package installs the binary at /usr/local/libexec/printeasy-agent/printeasy-agent, adds a symlink at /usr/local/bin/printeasy-agent and registers a LaunchDaemon with the label com.printeasy.agent. Data lives in /Library/Application Support/PrintEasy.

Open the local UI with:

sudo printeasy-agent open

Unsigned builds: if macOS says the package cannot be opened, open System Settings, Privacy & Security, and choose Open Anyway, or run sudo installer -pkg PrintEasyAgent-<version>.pkg -target / in Terminal.

Windows

In an administrator PowerShell, run the one-liner:

irm https://downloads.adfinite.com/agent/install.ps1 | iex

Or download the .msi (PrintEasyAgent-<version>-x64.msi) and run it. Download links for every file are listed in latest.json.

The installer puts the agent in C:\Program Files\PrintEasy together with SumatraPDF.exe, which prints PDF jobs, and the third party licences in licenses\. The agent runs as the Windows service printeasy-agent under the LocalSystem account. Data lives in %ProgramData%\PrintEasy.

Open the local UI from an administrator prompt:

& "C:\Program Files\PrintEasy\printeasy-agent.exe" open

Unsigned builds: if SmartScreen shows Windows protected your PC, choose More info, then Run anyway.

Windows limitation: per-user network printers

Printers connected per user (\\server\printer) are not visible to the PrintEasy service, which runs as LocalSystem. Add the printer as a local TCP/IP printer, or make the connection machine-wide from an administrator prompt: rundll32 printui.dll,PrintUIEntry /ga /n\\server\printer, then restart the Print Spooler service.

The same notice is shown in the agent’s local UI.

PDF options on Windows

PDF jobs print through SumatraPDF. These options are honoured: pages, copies, fit_to_page, rotate (90 and 270), color, duplex, paper (A2 to A6, letter, legal, tabloid, statement) and bin. The options dpi, media, collate, nup and rotate 180 are ignored, and a warning is added to the job’s stateMessage. A bin name that contains a comma is also ignored with a warning.

Linux

Run the one-liner:

curl -fsSL https://downloads.adfinite.com/agent/install.sh | sudo sh

Or download the .deb, .rpm or tarball. Download links for every file are listed in latest.json.

sudo apt install ./printeasy-agent_<version>_amd64.deb
# or
sudo dnf install ./printeasy-agent_<version>_amd64.rpm

Use the arm64 files on ARM machines.

To install from the tarball instead, extract it, put the binary on the path and register the service:

tar -xzf printeasy-agent_<version>_linux_amd64.tar.gz
sudo install -m 0755 printeasy-agent /usr/local/bin/printeasy-agent
sudo printeasy-agent install && sudo printeasy-agent start

Linux needs CUPS. Install cups and cups-client, and cups-filters is recommended. The agent runs as the systemd unit printeasy-agent, and its data lives in /var/lib/printeasy.

systemctl status printeasy-agent
sudo printeasy-agent open

Sign in

After installing, the agent has no organization yet. Run printeasy-agent open (with sudo on macOS and Linux, from an administrator prompt on Windows) to open the local UI, which shows a code and a link. Open app.printeasy.adfinite.com/device, sign in, enter the code and approve the computer. Only organization owners and admins can approve a computer. If the code expires, start sign-in again from the local UI.

When approval completes, the computer appears under Computers in the dashboard and its status turns online.

Mark printers live

The agent lists every printer the operating system knows, but none of them accept API jobs until you mark them live. Turn on the Live toggle for a printer in the dashboard (Printers) or in the agent’s local UI. PrintEasy then reads the printer’s paper sizes, trays, duplex and color support, which you can inspect with GET /v1/printers/{id}. See Options and paper sizes.

Your plan limits how many computers you can connect. A computer over the limit is refused at sign-in.

Service commands

The agent is a system service. These commands need administrator rights (sudo on macOS and Linux, an administrator prompt on Windows).

Command	What it does
printeasy-agent status	Prints running, stopped or not installed
printeasy-agent start	Starts the service
printeasy-agent stop	Stops the service
printeasy-agent open	Opens the local UI
printeasy-agent uninstall	Removes the service registration
printeasy-agent version	Prints the installed version

Use a proxy

If the computer reaches the internet through an HTTP proxy, set it in one of three ways. Then restart the service.

1. At install time on Windows: msiexec /i PrintEasyAgent-<version>-x64.msi PROXY_URL="http://proxy:3128"
2. With the CLI on any OS: printeasy-agent install --proxy-url http://proxy:3128
3. In config.json in the data directory, set proxy_url:

{ "proxy_url": "http://proxy:3128" }

The data directory is /Library/Application Support/PrintEasy on macOS, %ProgramData%\PrintEasy on Windows and /var/lib/printeasy on Linux. config.json also accepts api_origin, local_ui_port (default 38457) and log_level.

The standard HTTPS_PROXY and NO_PROXY environment variables also work when they are set machine-wide, so the service can see them.

Verify a download

Each release publishes checksums.txt and a minisign signature. Fetch the public key from https://downloads.adfinite.com/agent/minisign.pub, then verify the signature and compare the hash of the file you downloaded:

minisign -Vm checksums.txt -P <key from https://downloads.adfinite.com/agent/minisign.pub>
sha256sum -c --ignore-missing checksums.txt

On macOS use shasum -a 256 -c instead of sha256sum -c.

Updates

The agent updates itself. It checks latest.json every 6 hours and when the server asks it to, verifies the signature and checksum, stages the new version and restarts. Rollouts are staged, so not every computer updates at the same moment. A version that fails to start twice is rolled back to the previous one.

Known limitations

• Windows: printers connected per user (\\server\printer) are invisible to the service because it runs as LocalSystem. Add them as local TCP/IP printers or make the connection machine-wide. Details are in the Windows tab under Install.
• Windows: PDF jobs ignore dpi, media, collate, nup and rotate 180, and add a warning to the job’s stateMessage.
• Unsigned builds: macOS Gatekeeper and Windows SmartScreen show a warning until signing certificates are in place. The bypass for each is in the Install tabs.

Troubleshooting

• Run printeasy-agent status first. If it says stopped, run printeasy-agent start.
• The local UI status screen shows whether the agent is signed in and connected, and explains platform limitations. If it does not load, another program may be using port 38457; printing keeps working. Set local_ui_port in config.json to use another port.
• The agent writes agent.log in its data directory: /Library/Application Support/PrintEasy on macOS, %ProgramData%\PrintEasy on Windows and /var/lib/printeasy on Linux. Set "log_level": "debug" in config.json for more detail, then restart the service.
• Behind a proxy, see Use a proxy.
• A computer shows offline in the dashboard when its agent is not connected. Check the network, then the log.

Uninstall

macOS

sudo printeasy-agent uninstall && sudo rm -rf /usr/local/libexec/printeasy-agent /usr/local/bin/printeasy-agent && sudo pkgutil --forget com.adfinite.printeasy.agent

Windows

Open Settings, Apps, choose PrintEasy Agent, then Uninstall.

Linux

sudo apt remove printeasy-agent
# or
sudo dnf remove printeasy-agent

After uninstalling, delete the computer from the dashboard so its agent token is revoked.