Agents

The agent runs as a system service (Windows service YarmaAgent, systemd yarma-agent, LaunchDaemon io.yarma.agent), connects outbound to the agent service on TCP 18443 with mutual TLS, and opens nothing on the device.

One-line install (recommended)

Settings → Enrollment creates a token and shows a ready-to-paste command for Windows, macOS and Linux. It downloads the agent from your YARMA server, checks the package's SHA-256, trusts only the agent CA whose fingerprint is in the command, enrolls and starts the service:

# Linux (x86_64: Ubuntu, Debian, RHEL, Rocky, Alma, Fedora, openSUSE) and macOS
curl -fsSL https://<console>/api/v1/agent/install.sh | sudo YARMA_TOKEN=<token> YARMA_CA_SHA256=<fingerprint> bash

# Windows, PowerShell as Administrator (also as an Intune or GPO script)
$env:YARMA_TOKEN='<token>'; $env:YARMA_CA_SHA256='<fingerprint>'; irm https://<console>/api/v1/agent/install.ps1 | iex

Running the same command on an enrolled device upgrades the agent; it needs no token then. On Linux the desktop helpers (screen sharing, support window) are added when a display manager is present; YARMA_DESKTOP=1 or 0 overrides that. The scripts, packages, CA and a manifest (/api/v1/agent/manifest) are public; enrolling still needs a token.

The server offers the packages placed in agents.downloads_dir (the native installer fills it from the release; see native install). Devices connect to agents.public_url, by default https://<console host>:18443; set it when agents use another name, for example a DNS-only record when the console is behind Cloudflare.

Manual install

Download the packages from Settings → Enrollment → Downloads for manual installation (or the release page). Every install needs three things:

• the agent server URL: https://<agents host>:18443, where the host is the name in the agent-service certificate (init.sh --agents-host, default the console name);
• an enrollment token from Settings → Enrollment;
• the agent CA certificate agent-ca.crt (Settings → Enrollment → Downloads, or https://<console>/api/v1/agent/ca.crt).

The installers write the configuration, enroll (the token is passed through the environment, never on a command line), and start the service. Once enrolled, the device keeps a per-device certificate that renews automatically; the token is no longer needed.

Windows

Windows 10/11 and Windows Server, x64. In an elevated PowerShell, from the unpacked yarma-agent-X.Y.Z-windows-x64.zip:

.\install.ps1 -Server https://yarma.example.com:18443 -Token <token> -CaFile .\agent-ca.crt

Files: C:\Program Files\YARMA Agent\ (program), C:\ProgramData\YARMA\Agent\ (agent.yaml, identity; SYSTEM and Administrators only).

Mass deployment (Intune Win32 app, Configuration Manager, GPO startup script, RMM): run install.ps1 as SYSTEM with the parameters above, or split it up:

1. msiexec /i yarma-agent-X.Y.Z-windows-x64.msi /qn /norestart. The service starts but waits until the device is enrolled.
2. Write C:\ProgramData\YARMA\Agent\agent.yaml and copy agent-ca.crt next to it:

   server_url: https://yarma.example.com:18443
   data_dir: C:/ProgramData/YARMA/Agent
   

3. With YARMA_AGENT_ENROLLMENT_TOKEN set in the environment, run "C:\Program Files\YARMA Agent\yarma-agent.exe" --config C:\ProgramData\YARMA\Agent\agent.yaml enroll --ca-file C:\ProgramData\YARMA\Agent\agent-ca.crt
4. Restart-Service YarmaAgent

Detection rule for Intune or Configuration Manager: the MSI product "YARMA Agent" for the install, and C:\ProgramData\YARMA\Agent\identity.json for a completed enrollment.

Unsigned or self-signed builds show SmartScreen warnings only when opened from a browser download; see code signing.

macOS

Apple silicon or Intel (universal package).

sudo installer -pkg yarma-agent-X.Y.Z-macos-universal.pkg -target /
sudo "/Library/Application Support/YARMA/Agent/install.sh" \
  --server https://yarma.example.com:18443 --token <token> --ca-file agent-ca.crt

Grant the agent Screen Recording and Accessibility in System Settings → Privacy & Security, or push a PPPC profile from your MDM for /Library/Application Support/YARMA/Agent/bin/yarma-agent. Without them sessions show no screen or cannot control it.

Mass deployment with an MDM: deploy the pkg, the PPPC profile, and a script that runs install.sh with the token. Logs: /Library/Logs/YARMA/agent.log.

Linux

Debian/Ubuntu/Raspberry Pi OS (.deb) and RHEL/Fedora/SUSE (.rpm) with systemd, on x86_64 (amd64, x86_64) and 64-bit ARM (arm64, aarch64). The packages need glibc 2.34 or newer: Ubuntu 22.04+, Debian 12+, Raspberry Pi OS Bookworm, RHEL/Rocky/Alma 9+, current Fedora and openSUSE. The one-line install picks the right package automatically.

# x86_64; on 64-bit ARM use the _arm64.deb / .aarch64.rpm files
sudo apt install ./yarma-agent_X.Y.Z_amd64.deb ./yarma-agent-desktop_X.Y.Z_amd64.deb
#   or: sudo dnf install ./yarma-agent-X.Y.Z-1.x86_64.rpm ./yarma-agent-desktop-X.Y.Z-1.x86_64.rpm
sudo /usr/share/yarma-agent/install.sh --server https://yarma.example.com:18443 \
  --token <token> --ca-file agent-ca.crt

Other distributions: unpack yarma-agent-X.Y.Z-linux-x86_64.tar.gz and run the same install.sh from it (installs to /usr/local/bin).

Files: /etc/yarma-agent/agent.yaml and agent-ca.crt, /var/lib/yarma-agent/ (identity, root only). Logs: journalctl -u yarma-agent. For Ansible, Salt or Puppet, install the packages and run install.sh once, guarded by the existence of /var/lib/yarma-agent/identity.json.

Raspberry Pi

Raspberry Pi 3, 4, 5 and 400 (and Compute Modules) work with a 64-bit operating system: Raspberry Pi OS (64-bit) Bookworm or later, or Ubuntu 22.04+ for Raspberry Pi. Check with uname -m; it must print aarch64. The 32-bit Raspberry Pi OS (armv7l) is not supported.

Use the same one-line Linux command from Settings → Enrollment. On a Pi with a desktop the screen sharing helpers are installed too (Wayland on Bookworm uses the desktop portal like any Wayland desktop; the user approves sharing). Headless Pis get the agent only: monitoring, inventory, terminal, scripts, apt patching and software installs.

Agent settings

agent.yaml (restart the service after changes):

yarma-agent --config <file> check-config validates the file.

Upgrade

Run the one-line install command again, or install the new package over the old one (apt install, dnf install, zypper install, msiexec /i … /qn, installer -pkg). The service restarts on the new version and keeps its identity and configuration; no re-enrollment is needed. Upgrade the server before the agents.

Uninstall

First retire the device (device page → Retire device): its certificate stops working immediately and it no longer counts against the license. Then remove the software:

The configuration and identity are kept by the package removal so a reinstall can reuse them; deleting them as shown makes the device forget its enrollment.

Documentation for Yarma 0.1.0-alpha.4. Something unclear? Ask us.