> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inkrelay.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://printeasy.adfinite.com/#download) 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`](https://downloads.adfinite.com/agent/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

<Tabs>
  <Tab title="macOS">
    Run the one-liner in Terminal:

    ```bash theme={null}
    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`](https://downloads.adfinite.com/agent/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:

    ```bash theme={null}
    sudo printeasy-agent open
    ```

    <Note>
      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.
    </Note>
  </Tab>

  <Tab title="Windows">
    In an administrator PowerShell, run the one-liner:

    ```powershell theme={null}
    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`](https://downloads.adfinite.com/agent/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:

    ```powershell theme={null}
    & "C:\Program Files\PrintEasy\printeasy-agent.exe" open
    ```

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

    ### 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.
  </Tab>

  <Tab title="Linux">
    Run the one-liner:

    ```bash theme={null}
    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`](https://downloads.adfinite.com/agent/latest.json).

    ```bash theme={null}
    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:

    ```bash theme={null}
    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`.

    ```bash theme={null}
    systemctl status printeasy-agent
    sudo printeasy-agent open
    ```
  </Tab>
</Tabs>

## 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](/guides/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`:

```json theme={null}
{ "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:

```bash theme={null}
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](#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](#use-a-proxy).
* A computer shows offline in the dashboard when its agent is not connected. Check the network, then the log.

## Uninstall

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    sudo printeasy-agent uninstall && sudo rm -rf /usr/local/libexec/printeasy-agent /usr/local/bin/printeasy-agent && sudo pkgutil --forget com.adfinite.printeasy.agent
    ```
  </Tab>

  <Tab title="Windows">
    Open Settings, Apps, choose PrintEasy Agent, then Uninstall.
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    sudo apt remove printeasy-agent
    # or
    sudo dnf remove printeasy-agent
    ```
  </Tab>
</Tabs>

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.