Get Started
User guideAgents

Install the agent on macOS

You need an enrollment token. The portal shows the command below with your address and token filled in; copy it from there.

Install

In Terminal, as an administrator:

sh
curl -fsSL https://YOUR-PORTAL/install-macos.sh | sudo PATCHPILOT_ENROLLMENT_TOKEN='ppe_…' sh -s -- --server https://YOUR-PORTAL

The installer:

  1. downloads the agent for the Mac's processor (Intel or Apple silicon) from your portal and checks that it is genuine;
  2. installs it to /opt/patchpilot/bin/patchpilot-agent;
  3. asks whether to install Homebrew, if the Mac has none (see below);
  4. starts it as the launchd daemon com.patchpilot.agent, which also starts at boot;
  5. waits up to 60 seconds for the Mac to enroll, then deletes the token.

What gets updated

  • macOS updates, from Apple.
  • Homebrew packages and apps, where Homebrew is installed.

The Homebrew question

RemediForge updates third-party apps on a Mac (Chrome, Zoom, VS Code and many more) through Homebrew. If the Mac has no Homebrew, the installer asks:

text
patchpilot: install Homebrew on this Mac? [Y/n]
  • Yes: the installer installs Homebrew (this can take several minutes). Homebrew belongs to the person signed in at the Mac; if nobody is, to the account that ran sudo.
  • No: apps are still listed and checked for vulnerabilities, but they cannot be updated from the portal.

macOS updates come from Apple either way. If Homebrew cannot be installed, the agent is still installed and runs without it.

Installing without anyone to answer

For scripted installs (MDM, remote scripts), answer in advance, and choose the account if nobody will be signed in:

sh
curl -fsSL https://YOUR-PORTAL/install-macos.sh | sudo PATCHPILOT_HOMEBREW=install PATCHPILOT_HOMEBREW_USER=jane PATCHPILOT_ENROLLMENT_TOKEN='ppe_…' sh -s -- --server https://YOUR-PORTAL

With no answer and nobody at the keyboard, the installer chooses skip. Running the installer again keeps the earlier answer unless you set PATCHPILOT_HOMEBREW again, so the same command with PATCHPILOT_HOMEBREW=install installs Homebrew on a Mac that said no before.

What the portal sees

The agent lists the Mac's applications and its Homebrew formulae, and the device's Installed packages tab shows them. Common applications (Chrome, Firefox, Zoom, VS Code, VLC and others) and Homebrew formulae (Node.js, OpenSSL, Python, PHP, PostgreSQL, curl, Git and others) are checked for known vulnerabilities. Apple's own applications are covered by macOS updates.

Macs enrolled before 30 September 2026 need an agent upgrade from the Agents page before their applications appear.

When a patch job fails

In the job's log What it means
"macOS could not be downloaded" / "did not download from Apple" The Mac could not finish downloading from Apple. The agent refreshes Apple's list and tries once more by itself. If it still fails, check that the Mac reaches swcdn.apple.com and swdist.apple.com with no proxy or web filter in the way, then run the job again
"The following directories are not writable by your user", "Permission denied", "is not writable" Something run with sudo (often pip or npm) left a folder owned by root. The agent repairs this inside Homebrew by itself; a folder outside Homebrew has to be given back to its owner by hand
"You are using macOS on Intel x86_64 … Tier 3" Homebrew no longer has ready-made packages for Intel Macs, so every Homebrew update is compiled on the Mac. Sixty packages can take several hours. Keep the Mac on power
"sudo was stopped after 4h0m0s" (or "timed out") after the Homebrew lines The compile took longer than that. Run the job again: what was already upgraded is skipped. On an Intel Mac, consider leaving large packages (MySQL, Node, Python) out of the job
"… is downloaded and installs when the Mac restarts for it" macOS updates are downloaded by the job and installed by a restart. With Reboot: If required, the agent has softwareupdate restart the Mac and the update installs; the job finishes once the Mac is back. With Never, the device stays Reboot pending: use Restart Now in System Settings → General → Software Update. A restart from the Apple menu does not install it

The agent keeps the Mac awake while it installs. A laptop on battery with its lid closed still sleeps, and the job pauses until it wakes.

On Apple silicon, macOS asks for an administrator's password to install a macOS update, which the agent does not have. There the update is downloaded, and someone has to press Restart Now in Software Update.

Checking the agent

sh
sudo launchctl print system/com.patchpilot.agent
tail -f /var/log/patchpilot-agent.log

If it does not enroll

Message What to do
"download failed: is … reachable from this host?" The Mac cannot reach your portal on port 443
"the agent did not enrol within 60s" Check /var/log/patchpilot-agent.log and Enrollment attempts in the portal
"this installer is for macOS; on Linux use install.sh" You ran the macOS command on Linux; use the Linux command

Next

Install the agent on macOS | RemediForge