PrintHook

Agent installation and setup

Install and set up the PrintHook Agent

Put the agent on the computer that can already print to your queues. It runs as a system service, connects outbound to PrintHook, and keeps working when nobody is signed in to the desktop.

← Help center

Before you install

Confirm that the printer works from the operating system first. PrintHook uses the Windows print spooler on Windows and CUPS on macOS and Linux; it does not replace the printer driver or create a queue. Windows needs Windows 10 1809 or Server 2019 or later. macOS needs version 12 or later. Linux needs systemd, CUPS 2.x, and cups-client. Docker needs Docker 20.10 or later plus the host CUPS socket or a reachable network CUPS server.

The agent makes outbound HTTPS and WebSocket connections on port 443. No inbound firewall rule is needed. If the site uses a proxy or TLS inspection, make the proxy available to the system service and install the corporate root in the machine trust store. The troubleshooting guide explains the built-in network checks.

Choose an installer

  • Windows: download the x64 or arm64 MSI from Setup in the console and run it as an administrator. It installs the PrintHookAgent Windows service and a tray helper. Printers must be installed for the machine so the SYSTEM account can see them.
  • macOS: use the universal .pkg for Intel or Apple silicon. It installs a LaunchDaemon and the PrintHook menu bar app.
  • Linux: use the .deb on Debian, Ubuntu, or 64-bit Raspberry Pi OS, or the .rpm on Fedora, RHEL-family systems, and openSUSE. The package creates the printhook service user and starts the systemd unit.
  • Docker: use ghcr.io/printhook/printhook-agent, persist /var/lib/printhook, and either mount /run/cups/cups.sock or set CUPS_SERVER. The image does not contain a CUPS server.

Enroll the computer

Open PrintHook from the tray or menu bar after an interactive installation. Sign in once with a verified account that has the owner, administrator, or operator role. The service exchanges those credentials for an agent-scoped computer key and stores only that key. You can instead create a computer key under Computers → Add computer and paste it into Advanced settings. For unattended deployment, pass the server URL and computer key to the installer or run printhook-agent enroll --server https://api.printhook.io --client-key ck-... --data-dir <directory> as an administrator.

Enroll golden images after cloning. If several machines share one copied install_uuid, their sessions replace one another. Delete that identifier before capturing the image, then enroll each clone separately.

Verify the setup

  1. Open Setup in the console and wait for the computer to show connected.
  2. Select the computer and confirm that the expected printers appear. A queue missing here is usually not visible to the service account.
  3. Choose one printer and submit the one-page setup test. Use a PDF queue if you do not want paper.
  4. Wait for the tracked job to reach a visible success or failure. A successful agent report means the operating system spooler accepted the job; confirm physical output separately.

Enrollment security

Console two-step verification protects browser sign-in. The agent sign-in never asks for an authenticator or recovery code. It uses the account password once over HTTPS, requires a verified address and an allowed role, sends a new-computer email notice, and retains only the computer key. Revoke that key from the console if the machine is lost or retired. Never put passwords or computer keys in support messages or diagnostic files.

Back to the PrintHook help center