Skip to content
Documentation menu · version 0.1.0-alpha.4

Quick start

A working YARMA server on one Ubuntu machine and the first device enrolled, in about 15 minutes. Prefer not to run a server? YARMA Cloud does it for you; skip to first-time setup.

1. Prepare

  • Account and license key. Register with your work email. Your free Community Edition license (up to 14 devices) is created right away and its activation key is emailed to you. Missed it? In your dashboard choose Email me a new key.
  • A server with Ubuntu 24.04: 4 vCPU, 8 GB RAM and 50 GB disk for up to 500 devices (sizing). A fresh VM or container is best.
  • A DNS name for the console, e.g. yarma.example.com, and an HTTPS reverse proxy (for example Nginx Proxy Manager, Caddy or a load balancer) that forwards it to the server's port 18080 with WebSockets enabled.
  • Ports forwarded to the server: TCP 18443 for agents (pass-through, no TLS termination), UDP/TCP 3478 and UDP 49160–49200 for the session relay (network ports). If the console name is behind a proxy such as Cloudflare, use a separate DNS-only name for agents.

2. Download

Download the server bundle for the current release from the download page and check it:

V=<version from the download page>
curl -fLO https://yarma.avadeja.com/downloads/$V/yarma-server-native-$V-linux-amd64.tar.gz
curl -fLO https://yarma.avadeja.com/downloads/$V/SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS
tar xzf yarma-server-native-$V-linux-amd64.tar.gz
cd yarma-server-native-$V-linux-amd64

3. Install

sudo ./install.sh --domain yarma.example.com --trusted-proxy <proxy IP>/32 --clamav

The installer sets up PostgreSQL, Redis, NATS, object storage, the TURN relay, ClamAV, the API and the console as system services, generates every password, key and certificate, and schedules daily backups. Useful options: --turn-ip <public IP>[/<private IP>] behind NAT, --agent-host agents.example.com when agents use another name. All options: Ubuntu server installation.

Check it: curl -s http://127.0.0.1:18080/api/readyz answers "status":"ready", and https://yarma.example.com shows the sign-in page.

4. Create your organization and administrator

sudo YARMA_BOOTSTRAP_ADMIN_PASSWORD='<a strong passphrase>' \
  yarma-cloud-admin bootstrap -tenant acme -name "Acme Corp" -admin-email [email protected]

Open https://yarma.example.com, enter organization acme and sign in. Turn on authenticator-app MFA under My account. To sign in with your identity provider (Entra ID, Okta, Google, SAML, Active Directory) instead, see first-time setup.

5. Activate the license

In Settings → License choose Activate online and enter the activation key from your email. Without a license, devices cannot enroll.

6. Enroll the first device

In Settings → Enrollment create a token, choose the device's operating system and copy the command, then run it on the device:

# Linux and macOS
curl -fsSL https://yarma.example.com/api/v1/agent/install.sh | sudo YARMA_TOKEN=<token> YARMA_CA_SHA256=<fingerprint> bash

# Windows, PowerShell as Administrator
$env:YARMA_TOKEN='<token>'; $env:YARMA_CA_SHA256='<fingerprint>'; irm https://yarma.example.com/api/v1/agent/install.ps1 | iex

The device appears under Devices within a few seconds. Mass deployment, manual packages and uninstalling: installing agents.

Next

  • First-time setup: users and roles, sign-in, policies, notifications.
  • Backups before you rely on it.
  • Upgrading: download the newer bundle and run sudo ./install.sh again; settings, keys and data are kept.

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