Install the Atlas Reach Agent on Linux

Install the Atlas Reach agent on Linux with the .deb and .rpm packages: mint an enrollment token, and more.

Before you begin

  • An Atlas AVD administrator account, to mint an enrollment token and approve the device
  • Linux with systemd on x64 or ARM64: Debian, Ubuntu, RHEL, Fedora, Rocky, Alma, SUSE, openSUSE, or a derivative
  • Root or sudo on the machine (the agent runs as a system service)
  • Outbound HTTPS (443) from the machine to your Atlas AVD address
  • For live remote view and control: an X11 session, or a Wayland session with the opt-in portal support turned on

Which package do I need?

Download the package for the machine's distribution family and CPU from the Download Agent menu at the top of the Atlas Reach page:

  • Debian, Ubuntu, and derivatives: atlas-reach-agent_amd64.deb (x64) or atlas-reach-agent_arm64.deb (ARM64).
  • RHEL, Fedora, Rocky, Alma, SUSE, openSUSE, and derivatives: atlas-reach-agent.x86_64.rpm (x64) or atlas-reach-agent.aarch64.rpm (ARM64).

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 the machine's distribution family: Linux · Debian / Ubuntu, Linux · RHEL / Fedora, or Linux · SUSE / openSUSE. Atlas shows one command, with your server address and token filled in, that downloads the package for the machine's CPU, installs it, writes the config file, and starts the agent. Paste it into a terminal on the machine (it uses sudo).

Step 2, Option B: Install by hand on Debian / Ubuntu (.deb)

Install the package for the machine's architecture, set the config file, and restart the service:

sudo apt-get install -y ./atlas-reach-agent_amd64.deb   # or _arm64.deb
sudo vi /etc/atlas-reach-agent/config.json
#   set "serverUrl" and "enrollmentToken"
sudo systemctl restart atlas-reach-agent

Step 2, Option B: Install by hand on RHEL / Fedora or SUSE (.rpm)

Install with dnf (or zypper on SUSE), set the same config file, and restart the service:

sudo dnf install -y ./atlas-reach-agent.x86_64.rpm   # or .aarch64.rpm
# SUSE / openSUSE:
# sudo zypper --non-interactive install --allow-unsigned-rpm ./atlas-reach-agent.x86_64.rpm
sudo vi /etc/atlas-reach-agent/config.json
#   set "serverUrl" and "enrollmentToken"
sudo systemctl restart atlas-reach-agent

The packages enable the service but leave it stopped until it is configured, so always finish with the restart.

Desktop sessions and remote control

Telemetry works on any machine. Live remote view and control depend on the desktop the machine runs:

  • X11 (Xorg): works out of the box.
  • Wayland (GNOME or KDE): supported through the desktop portal as an opt-in; see the next section.
  • Headless server: there is no screen to share, so the console is unavailable. Telemetry, scripts, and updates keep working.
  • Clipboard sync: install xclip (or xsel).
  • Consent prompt, banner, and chat: drawn with GTK 3. Install it (libgtk-3-0 or gtk3) on minimal images. Without it the session still works, it just shows no prompt, banner, or chat.

Wayland sessions

To use live remote control on a Wayland desktop, turn on desktop-portal capture in the agent's environment file and restart the service. The first time an operator connects, approve the screen-share prompt on the machine once and choose "remember".

echo 'ATLAS_REACH_WAYLAND_CAPTURE=1' | sudo tee -a /etc/atlas-reach-agent/agent.env
sudo systemctl restart atlas-reach-agent

The config file and its settings

The agent reads /etc/atlas-reach-agent/config.json. Matching ATLAS_* environment variables win over the file, setting by setting; you can put them in /etc/atlas-reach-agent/agent.env instead. Restart the service after changing either.

  • serverUrl (ATLAS_SERVER_URL): required. The address of your Atlas AVD deployment, for example https://atlas.contoso.com.
  • enrollmentToken (ATLAS_ENROLLMENT_TOKEN): the token from Step 1. It is removed from the file once the agent has enrolled.
  • sampleIntervalSeconds (ATLAS_SAMPLE_INTERVAL_SECONDS): optional. Defaults to 60 and is kept between 60 and 300.
  • autoUpdate (ATLAS_AUTO_UPDATE): optional. Set to false if your own package repository or configuration management rolls out agent updates.
  • remoteControl: optional. Defaults to true. Set to false for a telemetry-only machine.

On first start the agent exchanges the enrollment token for its own long-lived device credential, stores it in libsecret (or a machine-bound encrypted file on headless hosts), and clears the token from the config file.

Deploying across a fleet

Push the package and a pre-filled config.json (or agent.env) with your configuration-management tool or MDM, so each machine 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 clone enrolls as its own device.

Step 3: Verify and approve

Within about a minute, the machine 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 machine 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. Read the agent's log with journalctl -u atlas-reach-agent.

The remote session experience

When an operator connects, the machine 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 machine 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 machine can message each other during the session.
  • Multiple monitors: the operator can pick which display to view, or all displays at once.

Updates, re-installs, and removal

  • The agent checks once a day for a newer version and updates itself with the same package type it was installed from (.deb or .rpm). Use Check for update on a device to do it now.
  • Re-installing on the same machine 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 machine 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