First-time setup

After the server is running (single host or Kubernetes), set up each organization (tenant) in this order. The commands use yarma-api; on a single host prefix them with docker compose exec api /yarma-api -config-dir /etc/yarma, on Kubernetes with kubectl -n yarma exec deploy/yarma-api -- /yarma-api -config-dir /etc/yarma.

Where things are in the console. The left menu holds day-to-day work, grouped as Support (sessions), Endpoints (Devices, Monitoring, Patching), Software & automation (Software catalog, Software Center, Automation) and Insights (Reports, Audit log). Organization configuration lives under Administration → Settings, grouped as Organization (Users and roles, Sign-in and identity), Devices (Enrollment, Unattended access) and Subscription (License); My account is there too. Each person sees only what their roles allow; breadcrumbs at the top show where you are.

1. Organization and first administrator

YARMA_BOOTSTRAP_ADMIN_PASSWORD='<password>' yarma-api bootstrap \
  -tenant acme -name "Acme Corp" -admin-email [email protected]

This creates the tenant acme and a GlobalAdmin. Run it again with another -tenant for each additional organization. Users sign in at the console by entering the organization slug. Without YARMA_BOOTSTRAP_ADMIN_PASSWORD, a password is generated and printed once.

2. Sign-in

Local accounts (default when no identity provider is configured): passwords plus optional authenticator-app MFA, which each user enables under their account (user menu). Enable it at least for every administrator. Add people in Settings → Users and roles with an initial password that you give them; they can change it themselves.

Identity provider (recommended): in Settings → Sign-in and identity add an OIDC, SAML 2.0 or LDAP / Active Directory provider. Register YARMA at the provider with:

Set the allowed email domains and the default role for self-provisioned users (leave the role empty to grant nothing until an administrator assigns one). MFA is then enforced by your provider. For an MSP or any server where tenants are not trusted with your network, set auth.block_private_directories: true so tenant-configured providers cannot reach private addresses.

Roles

Role bindings can be scoped to a site, department, region or device group. Every denial is written to the audit log.

Managing users

Settings → Users and roles (GlobalAdmin) lists everyone with access, how they sign in, their roles, MFA status, last sign-in and whether they are active, locked or disabled. From there you can:

• add a local user, or invite a user who signs in through your identity provider (the account is claimed at their first sign-in);
• change roles, each optionally limited to a site, department, region or device group (effective immediately);
• rename, disable (signs the user out everywhere) or enable a user;
• for local accounts, set a new temporary password and/or remove the authenticator so the user enrols again — this also clears a lockout.

You cannot disable yourself or change your own roles, and the organization always keeps at least one active, organization-wide GlobalAdmin. Every change is in the audit log (user.* actions).

3. License

Devices cannot enroll until the organization has a license. The server trusts only licenses signed by the key in license.public_key_file (license.pub, given to init.sh --license-pub or the yarma-license-pub secret).

In Settings → License:

• Activate online: enter the activation key from the License Center (requires license.center_url).
• Offline or air-gapped activation: download the activation request, take it to the License Center customer portal, and upload the license file you get back.
• Or install a license file directly: paste it in Settings → License, or run yarma-api license install -tenant acme -file acme.lic.

The self-hosted Community Edition is free for up to 14 devices (registration with a verified email is required); larger fleets buy a paid license in the License Center portal (pricing). After a purchase, press Refresh from License Center in Settings → License (online installations also refresh daily). Running your own license issuer (for example a fully self-contained installation) works with yarma-license from the server tarball: yarma-license keygen -out ./keys once, keep license.key offline, give license.pub to the server, and issue licenses with yarma-license issue -key ./keys/license.key -org "Acme Corp" -plan community -devices 14. At 80, 90 and 95 % of the device limit the console warns; at the limit new enrollments are refused, while enrolled devices keep working.

4. Enrollment

In Settings → Enrollment create a token: how many devices may use it and for how long. Use short-lived, limited tokens for manual installs and a separate token per deployment wave for mass rollouts; revoke a token as soon as its rollout is done. The page then shows a one-line install command per operating system with the token and the agent CA's fingerprint filled in; devices download the agent from your server and trust only that CA. Treat the command like a password while the token is valid. Details and manual installation: agents.

5. Policies and features

6. Verify

• Audit: sign-ins, enrollments and setting changes appear in the audit log.
• yarma-api verify checks the schema version and every tenant's audit hash chain.
• Start an attended session to a test device and confirm that the consent prompt appears on the device. If the session connects but shows no video, check TURN (troubleshooting).

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