Install the Atlas Reach Agent on macOS

Install the Atlas Reach agent on a Mac with the .pkg installer: mint an enrollment token, run the ready-made command or install by hand, and more.

Before you begin

  • An Atlas AVD administrator account, to mint an enrollment token and approve the device
  • A Mac with Apple silicon or an Intel processor
  • An administrator account on the Mac (the agent runs as a system launchd service)
  • Outbound HTTPS (443) from the Mac to your Atlas AVD address

Step 1: Mint an enrollment token

Open Atlas Reach (Atlas Operations → Reach in the sidebar), go to the Enrollment tab, click New token, give it a name, and click Mint token. One token can enroll a whole rollout and keeps working until you revoke it, and you can copy it again later from the Enrollment tokens list.

Step 2, Option A: Use the ready-made command

After minting (or with the View install commands action on a token's row), choose macOS in the panel. Atlas shows one command, with your server address and token filled in, that downloads atlas-reach-agent.pkg, installs it, writes the config file, and starts the agent. Paste it into Terminal on the Mac; it asks for your administrator password because it uses sudo.

Step 2, Option B: Install by hand

Download atlas-reach-agent.pkg from the Download Agent menu on the Atlas Reach page. Install it (double-click it, or use the command below), add your server address and enrollment token to the config file, then restart the agent:

sudo installer -pkg atlas-reach-agent.pkg -target /
sudo vi "/Library/Application Support/AtlasAVD/ReachAgent/config.json"
#   set "serverUrl" and "enrollmentToken"
sudo launchctl kickstart -k system/com.atlasavd.reach-agent

The installer picks the Apple silicon or Intel build for the Mac automatically, and it never overwrites an existing config.json, so re-running it keeps your settings.

Step 3: Allow Screen Recording and Accessibility

Telemetry works as soon as the agent is running. Live remote view and control also need two macOS privacy permissions for the agent: Screen Recording (to see the screen) and Accessibility (to send mouse and keyboard input). Approve them once in System Settings → Privacy & Security, or push a PPPC (Privacy Preferences Policy Control) profile from your MDM so no one has to click anything.

Without these permissions an operator sees a black screen and their input is ignored. Telemetry, scripts, and updates keep working.

The config file and its settings

The agent reads /Library/Application Support/AtlasAVD/ReachAgent/config.json. Restart the agent after changing it.

  • serverUrl: required. The address of your Atlas AVD deployment, for example https://atlas.contoso.com.
  • enrollmentToken: the token from Step 1. It is removed from the file once the agent has enrolled.
  • sampleIntervalSeconds: optional. Defaults to 60 and is kept between 60 and 300.
  • autoUpdate: optional. Set to false if your MDM rolls out agent updates instead.
  • remoteControl: optional. Defaults to true. Set to false for a telemetry-only Mac.

On first start the agent exchanges the enrollment token for its own long-lived device credential, stores it in the macOS System keychain, and clears the token from the config file.

Deploying hands-off with an MDM

For a fleet, push atlas-reach-agent.pkg and a pre-filled config.json with your MDM (Intune or Jamf), together with a PPPC profile that grants Screen Recording and Accessibility if you need remote control. Each Mac enrolls on first start with no per-machine touch. For golden images, leave the token out of the image and deliver it at first boot so each Mac enrolls as its own device.

Step 4: Verify and approve

Within about a minute, the Mac appears on the Devices tab of Atlas Reach. New devices wait as Pending approval until an administrator clicks Approve (unless the Auto-approve enrolled devices setting is on); once approved, the device is ready for remote view and control.

If the Mac does not appear, check that it can reach your Atlas AVD address over HTTPS, that serverUrl is right, and that the token has not expired, been deleted, or reached its device limit. The agent logs to /Library/Logs/AtlasAVD/reach-agent.log.

The remote session experience

When an operator connects, the Mac shows the same in-session prompts as Windows, drawn in the signed-in user's desktop. What appears depends on the consent policy (set globally, per tenant, or per host pool).

  • Consent: under an "ask the user" policy the Mac shows an Allow/Decline prompt before anything streams, and the session is refused if it is declined or times out. With no one signed in, the policy's timeout action decides (refuse by default).
  • Banner: attended sessions keep a "your screen is being viewed/controlled" banner up for the whole session, with a Stop sharing button the local user can click to end it.
  • Chat: the operator and the person at the Mac can message each other during the session.
  • Multiple monitors: the operator can pick which display to view, or all displays at once.
  • These prompts need a signed-in user.

Updates, re-installs, and removal

  • The agent checks once a day for a newer version and updates itself from the .pkg. Use Check for update on a device to do it now.
  • Re-installing on the same Mac with a valid token re-enrolls it with a fresh credential instead of creating a duplicate, so it is safe to bake into image updates.
  • To cut a Mac off, revoke the device on the Devices tab. Its next report is rejected and it stops reporting.
  • To remove the agent completely, see Uninstall the Atlas Reach Agent.

Next steps