ResoluteOS Documentation¶

Introduction¶

ResoluteOS is designed to provide a secure, consistent, and centrally managed environment for thin client deployments. Its focus is on reducing administrative overhead while ensuring that devices remain predictable, maintainable, and easy to troubleshoot. At the heart of the system is the RMM (Remote Monitoring and Management) console, which provides administrators with a single point of control over large estates of devices.

Where traditional desktop management often relies on piecemeal tools or manual processes, ResoluteOS centralises these functions into a unified platform. Every device runs the ResoluteOS agent, which communicates securely with the management server, reporting its status and executing assigned tasks. Administrators gain visibility and control, while end users are provided with a locked-down but functional client environment that can be tailored to business requirements.

Key design principles include:

Security-first operation -- Devices communicate over encrypted channels, with authentication handled through registration tokens and cryptographic keys. This ensures only trusted agents can join and remain part of the managed estate.
Simplicity of deployment -- Device imaging and installer creation are integrated into the console. This avoids the need for complex build pipelines or manual configuration steps.
Modular control -- Instead of hardcoding functionality, ResoluteOS uses modules to apply and maintain configuration, software, and updates. Standard modules are provided for common use cases, while custom modules allow administrators to extend functionality.
Operational visibility -- Every action executed on a device produces a detailed report, enabling administrators to audit behaviour, confirm compliance, and re-run failed steps without reimaging or starting from scratch.
User transparency -- While the environment is controlled, users are still given basic tools for connectivity and session management. Networking, monitor layout, and peripheral management are handled through a simple configuration interface that does not require elevated privileges.

The end result is a platform that bridges the gap between traditional thin client solutions and modern RMM systems. For environments with hundreds or thousands of endpoints, ResoluteOS provides a way to ensure each one is consistently deployed, correctly configured, and always manageable.

ResoluteOS+¶

ResoluteOS+ is a licensed upgrade tier that unlocks premium vendor modules, enabling thin clients to connect to third-party virtual desktop and application delivery platforms alongside or instead of Inuvika OVD. Supported vendors include:

Citrix -- Citrix StoreFront and Gateway
Omnissa -- VMware Horizon (PCoIP and BLAST)
Parallels RAS -- Parallels Remote Application Server
Microsoft RDP / AVD -- Standard RDP and Azure Virtual Desktop

All deployment, console management, module operations, troubleshooting, and best practices described in this guide apply equally to ResoluteOS+ environments. The only difference is the addition of premium vendor modules, documented in the ResoluteOS+ Modules section. A ResoluteOS+ licence is required to use them; contact sales@inuvika.com for licensing information.

Deployment¶

Deployment begins with the RMM Console, which is the central management point for all ResoluteOS devices. Without the console, there is no way to create installer images, issue tokens, or maintain a consistent configuration across your estate. Installing it correctly is therefore the foundation of every environment.

Prerequisites¶

Before beginning installation, you should prepare:

Linux server capable of running Docker -- The console is deployed as a Docker Compose stack. A modern distribution such as Ubuntu or Debian is recommended.
Domain name -- A DNS hostname must point to the server. This is used for secure certificate generation and is how administrators will access the console.
Ports 80 and 443 available -- Port 80 is used for certificate validation, and 443 for secure access. Both must be reachable from the internet if you intend to use Let's Encrypt for SSL certificates.
Structured agent tree plan -- Think about how you will organise devices: by site, by tenant, or by department. This decision informs how tokens are created and how modules are assigned later.

Installation of the RMM Console¶

Install Docker

If Docker is not already installed, the simplest method is to use the official convenience script:
```
curl -fsSL https://get.docker.com | sh
```
This installs both Docker Engine and the Compose plugin in one step.
Prepare the stack directory
```
mkdir -p /opt/stacks/resoluteos
```
All configuration files for the console will live in this directory. Keeping them in a dedicated path makes backup and restoration straightforward.
Docker Compose file

Copy the provided compose.yaml into /opt/stacks/resoluteos. This file defines the services that make up the console, including the proxy server, and supporting components.
```
curl -o /opt/stacks/resoluteos/compose.yaml https://docs.resoluteos.com/compose.yaml
```
If you intend to use Network Install or Live Stream, the Compose stack must include an nginx service to serve installer images at the /static path. Add the following to your compose.yaml after the watchtower: block, and before the final volumes: block making sure your tabs line up:
```
nginx:
  image: nginx
  restart: unless-stopped
  volumes:
    - pb_iso:/usr/share/nginx/html:ro
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.pxe-server.rule=Host(`${API_HOSTNAME}`) && PathPrefix(`/static`)"
    - "traefik.http.routers.pxe-server.entrypoints=websecure"
    - "traefik.http.services.pxe-server.loadbalancer.server.port=80"
    - "traefik.http.routers.pxe-server.tls=true"
```
Without this service, the console will not serve installer images and Network Install and Live Stream will not function.
Environment configuration

Inside /opt/stacks/resoluteos, create a .env file with your settings:
```
PB_ENCRYPTION_KEY=
[email protected]
API_HOSTNAME=rmm.example.com
TZ=America/Toronto
```
- PB_ENCRYPTION_KEY -- Encrypts the database. This must be a random 32-character string. You can generate one with:
```
openssl rand -base64 24
```
  Important
  
  This key is critical: without it, backups cannot be restored. Treat it like a root password and keep it secure.
- LETSENCRYPT_EMAIL -- Used for SSL certificate issuance and renewal notifications.
- API_HOSTNAME -- Must be a publicly resolvable hostname so Let's Encrypt validation succeeds.
- TZ -- Sets the server's timezone. This ensures that logs and scheduled tasks are aligned with local time.
Start the console
```
cd /opt/stacks/resoluteos
docker compose up -d
```
Within a few minutes, the stack will be running. Access it via https://<API_HOSTNAME> or using the IP address of the server on port 8090 (e.g. http://<IP ADDRESS>:8090).

The default administrator account is:

Email: [email protected]
Password: inuvika123

When the console is accessed for the first time, a setup wizard runs. This process ensures the server is correctly licensed and baseline modules are installed:

Restore from backup -- If this is a replacement server, you may restore a previous backup here.
Hostname confirmation -- Confirms the DNS hostname matches the console's configuration.
Licence key -- Required to proceed. Trial licences are available from presales@inuvika.com; production licences from sales@inuvika.com. If the console does not have internet access, use the Manual Offline Activation option, which is a two-step process:
1. Get Subscription Key -- The wizard generates a curl command. Run this command on any machine that has internet access. It contacts https://my.inuvika.com/api/v1/resoluteos and returns a subscription key.
2. Apply Subscription Key -- Paste the returned subscription key into the wizard and click Apply to complete activation.
Baseline modules download -- Installs modules that are required in every environment (such as Kiosk Setup, OVD Desktop Client, and Hardware Info).

Note

Best practice is to create named accounts for each administrator and delete the default to avoid shared credentials.

Registration Tokens¶

Tokens are unique strings that control how devices register into the agent tree.

Embedding a token into an installer image ensures that any device imaged from it appears directly in the correct branch.
Tokens can be created per site, tenant, or department. For example, an MSP might assign one token per customer, while a school might assign tokens per campus.
If a token is compromised, it can be revoked. Already-registered devices are not affected.

Info

See the Tokens section later in this guide for full details of how they are managed.

Imaging Thin Clients¶

The console supports two installer types, selected when creating a new image in Settings -> Agent Installer.

Image Builder -- Ubuntu 24.04¶

Creates a pre-built ResoluteOS ISO image based on Ubuntu 24.04 LTS. This is the standard installer for x86-based thin clients. It uses a SystemRescue-based image written to USB and supports all deployment methods, including Network Install and Live Stream.

See Agent Installer Settings below for the full list of configuration options.

Raspberry Pi Image¶

Creates a customised ResoluteOS image for Raspberry Pi 3, 4, and 5. The image is pre-built in the same way as the Ubuntu installer and requires only an image name and registration token to generate. It is written to a microSD card or USB drive using Balena Etcher.

Important

Network Install and Live Stream are not supported for Raspberry Pi clients. Pi devices must be installed directly from the image.

Agent Installer Settings (Ubuntu 24.04)¶

The following options are available when creating an Image Builder -- Ubuntu 24.04 image:

Image name -- The filename of the generated image. A clear naming convention (e.g., site-branch-date) makes identification easier later.
RMM Server URL -- The URL of the management console. Pre-populated from your environment.
Registration Token -- Ensures devices register into the correct branch automatically.
Enable PXE+Live Stream Support -- Must be enabled if you intend to use this image with the Network Install or Live Stream modules. When enabled, the console makes the installer image available at the /static endpoint so PXE hosts can download it. If left off, network-based installation will not work.
Use Custom CA Certificate -- Enable this if your RMM server uses a certificate signed by an internal or private CA. When enabled, the CA certificate fields below become visible. The certificate is published to the /static endpoint on the console and downloaded by devices automatically on first boot, before agent registration begins.
- Root CA Certificate -- The root CA certificate in PEM format.
- Subordinate CA Certificate -- Optional. The intermediate CA certificate in PEM format. Only required if your CA chain includes an intermediate certificate. If provided, it is combined with the root certificate into a single bundle.
Override Source URLs -- Enable to replace the default download sources used during image creation.
- Override SystemRescue ISO URL -- Replaces the default SystemRescue ISO source with a custom URL.
- Override ResoluteOS Image URL -- Replaces the default ResoluteOS image source with a custom URL.

Once defined, the console generates a configured installer image. It can be downloaded from the Agent Installer page.

Every time an installer image is built, the console also refreshes an offline mirror of the Inuvika OVD Desktop Client installers (both x86_64 and arm64) at the /static/ovd/ endpoint, published under stable filenames. This happens automatically and requires no configuration -- see OVD Desktop Client for how to make devices use this mirror instead of downloading directly from Inuvika's archive.

Note

Installed devices default to DHCP. Network settings (including static IP and Wi-Fi) can be changed after boot via the ResoluteOS Configuration Tool. SSH is enabled by default; the admin password is admin until the Kiosk Setup module runs and sets it. Timezone, locale, and keyboard layout are configured via the Kiosk Setup module.

Note

SecureBoot must be disabled in firmware while imaging a device -- the installer media itself is not signed, so firmware won't boot it under SecureBoot. The deployed OS is unaffected by this: once installation completes, SecureBoot can be safely re-enabled, and ResoluteOS will boot normally with it on.

Writing the Image¶

The image can be written to USB sticks using tools like Balena Etcher. Etcher is recommended as it works consistently across Windows, macOS, and Linux and avoids writing errors.

First Boot¶

When a device boots after installation, it launches the ResoluteOS Configuration Tool automatically.

On DHCP networks -- the device obtains an address automatically and attempts to register with the console immediately.
On static or Wi-Fi networks -- configure the network connection in the Configuration Tool first (set a static Ethernet IP or join a Wi-Fi network), then click Restart Agent to trigger registration.

If a custom CA certificate was configured at image creation time, the device downloads and installs it automatically before attempting agent registration. This ensures that RMM servers using private PKI are trusted without any manual certificate management on the device.

Registration uses the token embedded in the image at creation time. Once registered, the device inherits the modules assigned to its branch and checks in with the console for configuration.

Devices without a matching group land in Unassigned and must be moved manually.

Network Install¶

For large rollouts, the Network Install module converts an existing ResoluteOS agent into a PXE build server, enabling fully network-based installations without USB media.

How It Works¶

When the Network Install module is applied to an agent, it:

Downloads the latest ResoluteOS installer image directly from the console.
Extracts and builds a deployable image from it.
Sets up the following services on the agent:
- dnsmasq (proxy DHCP) -- Responds to PXE boot requests without replacing your existing DHCP server.
- TFTP -- Serves the boot kernel and initrd to PXE-booting clients.
- HTTP (Apache) -- Serves the installation image to booting clients.

Other devices on the same subnet that are set to PXE boot will receive the ResoluteOS installer and install it to local disk.

Both BIOS and UEFI clients are supported.

Requirements and Constraints¶

The agent must first be installed via USB before it can serve as a PXE host.
Only one PXE host should exist per subnet. Network Install and Live Stream are mutually exclusive -- they cannot run on the same node, and only one of them should be active on any given subnet. Running both on the same subnet will produce unpredictable results.
The host's assigned token determines which branch all PXE-installed devices join. Ensure the correct token is assigned before enabling the module.
For multi-site or VLAN environments, PXE requires careful DHCP and routing configuration.

Important

The recommended deployment pattern is to dedicate a ResoluteOS node solely to this purpose. This node should reside in its own branch, separate from the devices it serves, so that management modules targeting client devices are not inadvertently applied to the PXE host.

Note

The Network Install host uses proxy DHCP mode, meaning it works alongside your existing DHCP server rather than replacing it. No changes to your DHCP infrastructure are required.

Live Stream¶

Live Stream is a network boot mode where devices run ResoluteOS entirely from RAM, with no installation to local disk. Each boot starts from a clean, consistent OS state served from a network host.

This is suited to stateless kiosk deployments where persistent local storage is undesirable, or where rapid provisioning of large numbers of devices is required.

How It Works¶

Live Stream uses the same core services as Network Install -- dnsmasq (proxy DHCP), TFTP, and HTTP (Apache) -- with the addition of NFS for per-device persistent storage. When a device PXE-boots from a Live Stream host:

The boot kernel and initrd are delivered via TFTP.
The device fetches the ResoluteOS filesystem image (~1.5-2 GB) over HTTP and decompresses it into RAM.
The RMM server address and registration token are read from kernel command line parameters (rmm_server= and rmm_token=), injected at boot by a systemd unit.
If a custom CA certificate is configured on the console, it is downloaded and installed before the agent starts, ensuring the RMM server is trusted.
The agent registers with the console and modules are applied.

Per-device configuration (such as the agent identity) is stored on an NFS share on the Live Stream host, so the device retains its identity across reboots without writing to local disk.

Because every boot starts from a clean image, configuration drift is impossible -- the device always comes up in exactly the state defined by its assigned modules.

Hardware Requirements¶

Live Stream devices load the entire OS image into RAM. Minimum and recommended memory:

	RAM
Minimum	4 GB
Recommended	8 GB

Devices with less than 4 GB of RAM will fail to boot in Live Stream mode.

Requirements and Constraints¶

A Live Stream host must first be installed via USB and assigned the Live Stream module.
Only one Live Stream host should exist per subnet. Network Install and Live Stream are mutually exclusive -- they cannot run on the same node, and only one of them should be active on any given subnet.
The host's assigned token determines which branch all Live Stream devices join.
Boot time is longer than a locally installed device, as the full image must be fetched and decompressed on every boot. On a typical LAN, expect 2-5 minutes.
Live Stream is not suitable for devices that require local persistent writes (e.g., local print spoolers or locally cached applications).

Important

The recommended deployment pattern is to dedicate a ResoluteOS node solely to this purpose. This node should reside in its own branch, separate from the devices it serves, so that management modules targeting client devices are not inadvertently applied to the Live Stream host.

Note

On subsequent boots, a Live Stream device checks in as already registered. To ensure modules are re-applied on every boot (as expected for stateless devices), enable the Live Boot compliance flag in the device or branch settings. This instructs the RMM to treat every check-in from a live boot device as requiring a full compliance pass.

Modules¶

Modules are the mechanism by which ResoluteOS devices are configured and controlled. Every thin client receives its behaviour from the modules assigned to the branch of the agent tree it belongs to. This inheritance model allows global settings to cascade across the environment while still permitting local overrides when required.

There are three main categories of modules:

Baseline modules -- Installed automatically in every environment and usually applied to the All branch.
Optional modules -- Available to administrators to extend functionality when needed.
Custom modules -- Defined by administrators, allowing for unlimited flexibility through scripting.

Baseline Modules¶

Baseline modules are included with every installation and are applied against the Main branch of the tree by default. They provide the essential functionality needed for any thin client deployment.

Kiosk Setup¶

The Kiosk Setup module defines how the device presents itself to the user and how tightly locked down the local environment is. Its options cover visual branding, security settings, locale, and application launch behaviour:

Hostname prefix -- Ensures devices follow a predictable naming convention. Hostnames are often the first identifier used by support staff, so consistency here is valuable.
Master volume -- Sets the default sound level at boot. Useful in environments like classrooms or offices where noise needs to be controlled.
Screensaver and timeout -- Defines whether the display blanks after inactivity. For kiosks or signage, this is usually disabled. For offices, it can help conserve energy.
Maintenance mode -- Boots the device into a standard Linux desktop instead of kiosk mode. Useful for IT staff, but normally disabled in production to prevent user access.
Admin terminal -- If enabled, administrators can press Ctrl+Alt+T to launch a terminal directly on the device. This provides a local troubleshooting tool without needing SSH access. The admin password is required.
Wallpaper and background colour -- Allows visual branding or differentiation between environments.
Show hostname/IP -- Overlays the device's hostname and IP address on the screen. Handy for helpdesk support as users can quickly report their device details.
System Locale -- Sets the system locale (e.g., en_US.UTF-8). Ensures the correct language and character encoding for the environment.
Keyboard Layout -- Sets the keyboard layout (e.g., us, gb). Ensures the physical keyboard matches what the OS expects.
Use App Launcher -- When enabled, the device boots into a launcher screen instead of directly into the configured application. This allows users to choose from multiple available applications (such as the OVD Desktop Client, Google Chrome, or other configured apps). Required when using Google Chrome (Multi-Instance).
Enable Proxy -- When enabled, routes device traffic through a proxy server. Configures a system-wide proxy for shell sessions, APT package management, and the RMM agent service. The following options appear when enabled:
- Proxy Type -- Protocol used to connect to the proxy: HTTP, HTTPS, or SOCKS5.
- Proxy Host -- Hostname or IP address of the proxy server.
- Proxy Port -- Port number of the proxy server. Defaults to 3128.
- No Proxy -- Comma-separated list of hosts that should bypass the proxy (e.g. localhost,127.0.0.1,.internal.example.com).
- Proxy Authentication -- Enable if the proxy requires credentials. When enabled:
  - Proxy Username -- Username for proxy authentication.
  - Proxy Password -- Password for proxy authentication.

Together, these options control whether a device is a sealed appliance, a flexible endpoint, or a multi-application launcher.

Note

The system packages this module installs (audio, Bluetooth, display, and kiosk-shell tooling) are checked against what is already present on the device before anything is downloaded. On a device imaged from a current installer, these packages are already baked in and no network access is required at all. Only genuinely missing packages are fetched, so a device with limited or proxied internet access still completes setup as long as it was imaged from an up-to-date installer.

OVD Desktop Client¶

This module installs and configures the Inuvika OVD Desktop Client, which is the core application for accessing virtual desktops. ResoluteOS supports desktop mode only.

Key options include:

Use Offline Source -- When enabled, the OVD Desktop Client installer is downloaded from this RMM server's own /static/ovd/ mirror instead of Inuvika's public archive. This mirror is refreshed automatically every time an Agent Installer image is built (see Agent Installer Settings), so it stays current without any manual steps. Enable this for devices on networks with restricted or no direct internet access.
Server address -- The URL of the OVD Session Manager.
Default username and language -- Can be pre-filled to simplify the login experience.
UI controls -- Options to hide "remember me" or advanced settings, reducing the chance of user error.
Toolbar shortcut -- Places the client in the local taskbar for environments not using kiosk mode.
Keyboard handling -- Options for Unicode support, ignoring remote keyboard layouts, and ensuring proper mapping between local and remote sessions.
Disable static shares -- Prevents local directories from being redirected into the remote session, improving security in tightly controlled deployments.
Enable RemoteFX -- Improves performance for graphically demanding workloads.
Kiosk mode -- Disables some features of the client to simplify the user experience, and improve security in a shared device scenario.

This module determines how seamless or locked-down the user experience is. A call centre might use kiosk mode with no advanced settings, while a lab might expose more options for flexibility.

Mozilla Firefox¶

Firefox is included both as a general-purpose but locked-down browser and because it is required for two core functions:

SAML2 login -- The browser is used during authentication for single sign-on.
User Security Console -- Users access this to manage two-factor authentication and passwords.

Without Firefox, these processes cannot function, making it a required baseline module.

If the OVD Desktop Client module is installed, Firefox runs in kiosk mode full screen with the provided URL.

System Update¶

This module ensures devices remain up to date with security patches and software updates.

Updates are applied automatically in the background.
Kernel updates may require a reboot, which the device handles gracefully.

For administrators, this removes the need to manually maintain each device and ensures consistency across the estate.

Hardware Info¶

The Hardware Info module collects and reports detailed information from each device, including:

Operating system version and kernel.
Uptime.
CPU model and number of cores.
Memory and swap usage.
Storage capacity and usage.

This information is invaluable for capacity planning and troubleshooting. For example, a site deploying video conferencing might discover that devices with 2 GB of RAM are struggling, prompting an upgrade.

Optional Modules¶

Optional modules extend functionality beyond the baseline. They can be applied where needed but are not installed by default.

Network Install¶

This module converts an agent into a PXE build server, enabling network-based installation of ResoluteOS across a subnet. See Network Install in the Deployment section for full details of how it works.

Key constraints:

The agent must already be running ResoluteOS (installed via USB) before this module is applied.
Only one Network Install host should exist per subnet.
The host's token determines the branch all PXE-installed devices join.

Live Stream¶

This module converts an agent into a PXE live boot server. Devices that PXE-boot from this host run ResoluteOS entirely from RAM with no local installation. See Live Stream in the Deployment section for full details.

Key constraints:

The agent must already be running ResoluteOS (installed via USB) before this module is applied.
Only one Live Stream host should exist per subnet.
Client devices require a minimum of 4 GB RAM; 8 GB is recommended.

Network Utilities¶

Adds a suite of diagnostic tools to the device, such as ping, traceroute, and nslookup.

Enables on-site staff to quickly test connectivity.
Useful for first-line support to confirm if a device has basic network reachability.

Set Admin Password¶

Allows administrators to centrally define and rotate the local admin password on thin clients.

Can be run once or scheduled to repeat regularly.
Helps maintain security compliance and ensures old credentials are retired.

Important

This module should be applied to all devices. The default admin password (admin) is set at first boot and remains in place until this module runs. Apply it early to avoid leaving devices with the default credential.

Azure AD / Entra ID Kiosk Authentication¶

Adds an Entra ID (Azure AD) login gate that must be passed before the kiosk environment loads. This ensures only authenticated users can access the device session.

Settings include:

Azure AD Tenant ID -- The directory (tenant) ID from your Azure AD registration.
Azure AD Application (Client) ID -- The application (client) ID of the registered app in Azure AD.
Require Azure AD Authentication -- Enables the authentication gate. When off, the module is installed but authentication is not enforced.
Session Timeout (minutes) -- How long a session remains active before requiring re-authentication. Set to 0 for no timeout.
Idle Timeout (minutes) -- How long the device can be idle before the session expires. Set to 0 for no idle timeout.

Automatic Network Printer Discovery and Mapping¶

Automatically discovers available network printers on the subnet using driverless printing and configures them for immediate use on the endpoint. Printers are then available for redirection via the OVD Enterprise Desktop Client.

No manual printer configuration is required. The module handles discovery, driver matching, and queue creation automatically.

FabulaTech Workstation Upgrade¶

Upgrades FabulaTech Workstation packages to the latest defined versions. This module is updated regularly to track FabulaTech's release schedule, ensuring USB and peripheral redirection components remain current and compatible.

Install Custom Deb Package¶

Installs a .deb package from a supplied URL. Useful for deploying proprietary or internally distributed software that is not available from a standard repository.

Provide the direct download URL to the .deb file in the module settings. The package will be downloaded and installed on the endpoint.

Google Chrome (Multi-Instance)¶

Installs Google Chrome and adds one or more shortcut entries to the App Launcher, each opening a specific URL in a dedicated Chrome window.

Important

This module requires Use App Launcher to be enabled in the Kiosk Setup module. It is not compatible with single-application kiosk mode.

Each instance is configured with:

Shortcut Name -- The label displayed in the App Launcher for this entry.
Homepage URL -- The URL Chrome opens for this instance.
App Mode -- When enabled, Chrome opens without browser UI (address bar, tabs), presenting the URL as a standalone application.
Incognito Mode -- When enabled, Chrome opens in incognito mode, leaving no local browsing data between sessions.

Multiple instances of this module can be applied to provide users with several distinct Chrome-based application shortcuts alongside other launcher entries such as the OVD Desktop Client.

ResoluteOS+ Modules¶

The following modules are available with a ResoluteOS+ licence. They install and configure third-party virtual desktop and application delivery clients on the endpoint. All other module behaviour -- scheduling, priorities, settings inheritance, task reporting -- is identical to standard modules.

Citrix¶

Installs the Citrix Workspace client and configures it to connect to a Citrix StoreFront or Gateway environment.

Citrix Configuration

StoreFront URL -- The full URL to the Citrix StoreFront or Gateway (e.g., https://storefront.example.com/Citrix/StoreWeb). If left empty, the client presents a login UI for the user to enter the address manually.

Omnissa (VMware Horizon)¶

Installs the Omnissa Horizon client and configures it to connect to a VMware Horizon environment using PCoIP or VMware Blast.

Connection Configuration

Server Address -- Hostname or IP address of the Horizon Connection Server.
Username -- Account name for login. Leave empty for interactive entry.
Domain -- Domain name for authentication.
Password -- Password for login. Leave empty for interactive entry (recommended).
Auto Connect to Broker -- Automatically connects to the broker on startup without waiting for user input.
Non-Interactive Mode -- Suppresses dialogs and runs without user prompts.
Default Broker -- Sets a default broker address separate from the primary server.
SSL Verification Mode -- Controls certificate verification: Full verification, Warn if insecure, or No verification. Leave as Default unless your environment requires otherwise.
Custom CA Certificate URL -- URL to a custom CA certificate (.crt or .pem) for environments using private PKI.
Disconnected Behavior -- Action taken when all sessions disconnect: exit the client or stay open.

Desktop Configuration

Desktop Name -- Name of the desktop pool to connect to automatically.
Full Screen Mode -- Launches the desktop in full screen.
All Monitors -- Spans the desktop across all connected monitors.
Enable Display Scaling -- Enables high DPI scaling for sharp rendering on high-resolution displays.
BLAST Dynamic Resolution -- Enables dynamic resolution adjustment for the BLAST protocol. Disable if the display appears clipped.
Once Mode -- Exits the client after the desktop session disconnects.

UI Configuration

Hide Menu Bar -- Hides the menu bar, suitable for kiosk deployments.
Auto Hide Toolbar -- Automatically hides the connection toolbar during a session.

Protocol Options

Default Protocol -- Preferred display protocol: Auto, PCoIP, or VMware Blast.
Enable H.264 -- Enables H.264 video codec for improved performance.
Enable HEVC -- Enables HEVC (H.265) for higher quality at lower bandwidth.
Enable MMR -- Enables multimedia redirection for smoother media playback.

USB Redirection

Auto Connect USB at Startup -- Automatically redirects connected USB devices when the session starts.
Auto Connect USB on Insert -- Automatically redirects USB devices as they are plugged in.
Allow Auto Device Splitting -- Permits composite USB devices to be split into individual components for redirection.
Allow Smart Card -- Permits smart card reader redirection.
Include USB Families -- Restricts redirection to specific USB device families (e.g., storage, hid).
Include VID:PID -- Explicitly includes specific USB devices by vendor/product ID (e.g., 1234:5678).
Exclude VID:PID -- Explicitly excludes specific USB devices by vendor/product ID.

Storage and Device Redirection

Share Removable Storage -- Shares removable storage devices with the remote desktop.
Enable Real-Time Audio-Video (RTAV) -- Enables webcam and microphone redirection into the session.

Parallels RAS¶

Installs the Parallels Remote Application Server client and configures it to connect to a Parallels RAS environment.

Connection Configuration

Operating Mode -- Determines how the client connects and what it presents to the user:
- Gateway Access (default) -- Connects through a Parallels gateway.
- Direct Access -- Connects directly to the server without a gateway.
- Application List -- Displays a list of published applications for the user to choose from.
- Terminal Server -- Connects to a terminal server session.
- Terminal Server Fullscreen -- Connects to a terminal server in full screen.
- Terminal Server Fullscreen (All Monitors) -- Full screen across all connected monitors.
Server Address -- Address of the Parallels RAS server (e.g., server:port or ssl://server:port).
Username -- Username for login. Supports domain format (user@domain).
Password -- Password for login. Leave empty for interactive entry (recommended).
Domain -- Domain name for authentication.

Application Configuration

Application Name -- Name of a specific published application to launch directly. Used when Operating Mode is set to Application List or a Terminal Server mode.

Microsoft RDP / AVD¶

Installs and configures an RDP client for connecting to Windows Remote Desktop Services, standalone RDP hosts, or Azure Virtual Desktop environments.

Server Configuration

RDP Server -- Hostname or IP address of the RDP server. Required.
RDP Server Port -- Port for the RDP connection. Defaults to 3389.

UI Configuration

Window Title -- Title shown on the login dialog. Defaults to RDP Login if not set.
Show Domain Field -- Displays a domain field in the login dialog.
Default Domain -- Pre-fills the domain field with a specified value.

Display Settings

Color Depth -- Bit depth for the session: 8, 15, 16, 24, or 32 bit. Defaults to 32 bit.
Enable Dynamic Resolution -- Allows the session resolution to adjust when the window is resized.
Enable Multiple Monitors -- Spans the session across all available monitors.

Performance Settings

Connection Type -- Optimises RDP behaviour for the network type: Auto-detect, LAN, Broadband, WAN, Satellite, or Modem.
Enable Compression -- Enables RDP data compression to reduce bandwidth.
Enable Desktop Composition -- Enables Aero and desktop composition effects.
Enable Menu Animations -- Enables animated menus in the remote session.
Enable Window Drag -- Shows window contents while dragging.
Enable Themes -- Enables Windows visual themes in the session.
Enable Wallpaper -- Shows the remote desktop wallpaper.
Enable Font Smoothing -- Enables ClearType font rendering.

Graphics Settings

Enable GFX H264 -- Enables H.264 hardware acceleration (AVC444) for improved graphics performance.
Enable GFX Progressive -- Enables progressive graphics rendering, improving responsiveness on slower connections.

Device Redirections

Audio Redirection -- Controls audio output: bring to client, leave on server, or disable.
Redirect Microphone -- Redirects the local microphone into the remote session.
Redirect Printers -- Redirects locally configured printers into the session.
Redirect Smart Cards -- Redirects smart card readers for authentication within the session.
Redirect USB Devices -- Automatically redirects USB devices to the remote session.
Redirect Drives -- Redirects all mounted drives into the session. Useful where no local storage should be accessible.

Security Settings

Enable Network Level Authentication (NLA) -- Requires NLA for authentication before the session is established. Recommended for security.
Security Protocol -- Forces a specific security protocol: Default, TLS, NLA, RDP, or FIPS.

Advanced Settings

Keyboard Layout -- Keyboard layout code passed to the RDP session (e.g., 0x409 for US English). Leave empty for auto-detect.
Extra xfreerdp3 Options -- Additional command-line options passed directly to the underlying xfreerdp3 client for advanced configuration not covered by the fields above.

Custom Modules¶

Custom modules are where ResoluteOS becomes a flexible automation tool. Administrators can define scripts to perform almost any action required on the devices.

Structure of a Custom Module¶

Script -- Usually a Bash script or an Ansible playbook. Runs with root privileges.
Settings -- Passed to the script as environment variables. For example:
```
PRINTER_IP=192.168.100.20
PRINTER_NAME=AccountsPrinter
```
These make the same module reusable across multiple branches.
Scheduling -- If left empty, the module runs once when applied. Otherwise, a CRON expression defines repeat intervals. Use the pen icon for a user-friendly editor.
Priority -- Determines the execution order when multiple modules are queued; higher numbers run first.
Output capture -- Task output can be collected and viewed in Task Reports for debugging and auditing.
Metadata -- JSON format, used to define the user interface for entering settings when applying the module.

When users fill out or modify fields in the module configuration form, their input is reflected in the Settings field. Each change updates the corresponding value. If a field's value matches its defaultValue, it is omitted from Settings to avoid redundancy.

Each field can specify properties such as:
- type -- the field type text (default), boolean, integer, select, timeout, color, image, or section.
- key -- the variable name passed to the script
- label -- display name in the UI
- description -- help text for users
- placeholder -- hint text shown when the text field is empty
- default -- initial value. The setting is not defined when it matches this.
- required -- whether the field must be filled (true/false, default false)
- min / max -- limits for integer fields
- obfuscate -- hides input for sensitive fields (e.g. passwords)
- multiline -- allows multiple lines of text for text fields
- options -- choices for select fields (e.g. {"value1": "Label 1", "value2": "Label 2"})
- depend_on -- conditional display, e.g. {"field": "KEY", "value": true}
Use these properties to build dynamic, user-friendly forms for module configuration.

Examples¶

Example 1: Bash script for adding a printer¶

Script 1¶

#!/bin/bash
lpadmin -p "$PRINTER_NAME" -E -v "ipp://$PRINTER_IP/ipp/print" -m everywhere

Metadata 1¶

{
  "fields": [
    {
      "label": "Printer Configuration",
      "type": "section"
    },
    {
      "type": "text",
      "key": "PRINTER_IP",
      "label": "Printer IP Address",
      "required": true,
      "description": "The IP address of the printer to add."
    },
    {
      "type": "text",
      "key": "PRINTER_NAME",
      "label": "Printer Name",
      "required": true,
      "description": "The name to assign to the printer."
    }
  ]
}

Example 2: Ansible playbook for installing custom software¶

Script 2¶

#!/usr/bin/env -S ansible-playbook -c local -i localhost, --diff
---
- name: Optional Software Installation
  hosts: all
  vars:
    install_htop: "{{ lookup('env', 'INSTALL_HTOP', default=True) | bool }}"
  tasks:
    - name: Ensure htop is installed if requested or removed if not
      apt:
        name: htop
        state: "{{ 'present' if install_htop else 'absent' }}"

Metadata 2¶

{
  "fields": [
    {
      "label": "Optional packages",
      "type": "section"
    },
    {
      "default": true,
      "key": "INSTALL_HTOP",
      "label": "Install htop",
      "description": "Whether to install the htop package. If disabled, htop will be removed.",
      "type": "boolean"
    }
  ]
}

Best Practices for Modules¶

When creating custom modules, consider the following guidelines:

Test in a non-production branch before applying globally.
Make scripts idempotent -- running them multiple times should not cause harm.
Log clearly -- output should explain what was attempted and what succeeded or failed.
Security awareness -- remember that scripts run as root. Only trusted administrators should be allowed to create or modify them.

Custom modules effectively allow administrators to automate almost any repeatable task across their environment, reducing the need for manual intervention and ensuring consistency.

Info

Ansible playbooks are inherently idempotent, easy to read, and provide structured logging. Using Ansible simplifies complex tasks, improves reliability, and makes module scripts easier to maintain and audit.

Operations¶

The Operations section describes how administrators use the ResoluteOS management console on a day-to-day basis. The layout of the console is designed to be logical and consistent, starting with a high-level overview of the environment and moving through the objects being managed, the tasks that act on them, and finally the access and configuration layers.

Dashboard¶

The Dashboard provides a high-level view of the environment, giving administrators a quick way to check estate health at a glance.

Key panels include:

Total Agents -- number of registered agents, with a breakdown of how many are online.
Tasks -- number of executed tasks and how many succeeded.
Active Tasks -- any jobs still running.
Agent Status -- summary view of whether agents are available and communicating.
Task Reports -- highlights if script outputs are available.
Container Health -- status of the containers that make up the console itself.
System Health -- statistics about the management server itself, including CPU usage, memory, open file descriptors, number of routines, database size, and uptime.

This page is most useful for a rapid health check: confirming that agents are online, scheduled tasks are running, and the management server is not under load. For troubleshooting, the Dashboard can indicate where further investigation is needed, such as unusually high resource usage or a drop in available agents.

Agents¶

The Agents page lists all devices connected to the system. Agents are grouped hierarchically, typically under a main branch and sub-groups such as "Devices" or customer-specific folders.

For each agent, the following details are displayed:

Hostname -- the machine's reported name.
Name -- a user-defined label.
Group -- the branch of the tree the agent is assigned to.
IP address -- the most recent network identity.
Flags -- indicators such as whether the agent is connected via a proxy, has custom settings applied, or is running an outdated agent version.

Agent Actions¶

When viewing a specific agent, several actions are available:

Task Reports -- a history of modules run on that agent. Deleting a report allows the associated task to be re-run.
Terminal -- opens a secure shell directly to the agent, useful for quick administrative checks.
Remote Control -- provides full screen shadowing of the agent's desktop, with controls for scaling, clipboard transfer, and sending key sequences (e.g. Ctrl+Alt+Del).
Check Now -- forces the agent to immediately check in with the server. This is useful for applying configuration changes or updates without waiting for the next scheduled interval.
Move -- reassigns an agent to a different group. This is useful for reorganising estates or moving machines into production from testing.
Edit -- allows hostname and other metadata to be changed.

Agents are the foundation of the management system: every other operation (modules, tasks, monitoring) ultimately ties back to the agents in the tree.

Module Operations¶

Modules define the actions that can be applied to agents. They may be standard, pre-supplied modules (e.g., Kiosk Setup, OVD Desktop Client, Mozilla Firefox, System Update, Hardware Info) or custom modules defined by administrators.

Managed Modules¶

Baseline modules are automatically assigned to the Main branch of the agent tree. These include:

Kiosk Setup -- configures the thin-client environment, locale, keyboard, and application launch mode.
OVD Desktop Client -- installs the Inuvika client.
Mozilla Firefox -- installs and configures Firefox, used for SAML2 authentication and user security console access.
System Update -- updates the underlying OS.
Hardware Info -- gathers system hardware and OS information.

These modules have specific behaviours. For example, System Update executes unattended upgrades. Hardware Info produces structured data on CPU, memory, uptime, and other metrics.

Custom Modules Operations¶

Administrators can also define their own modules. A custom module is essentially a Linux script, optionally with settings and metadata. Ansible can be used inside modules for consistency with built-in functionality.

Key fields when creating a module include:

Name/Description -- labels for identification.
Schedule -- cron-style syntax. If empty, the module runs once when applied.
Capture Output -- stores standard output for review in task reports.
Priority -- determines the execution order when multiple modules are queued; modules with higher priority run first.
Settings -- key-value pairs passed to the script. These can be set at the module level, overridden at the group level within the hierarchy, or customized for each agent individually. The priority order is: Agent > Groups > Module.

This makes modules flexible: they can handle one-off deployments (e.g. installing a package), regular maintenance (e.g. nightly log rotation), or estate-wide configuration (e.g. applying a new security policy).

Tasks¶

The Tasks page shows a history of all module executions across the estate. Each task record includes:

Status -- success, failure, or still running.
Module -- which module was executed.
Agent -- which device it ran on.
Start/End time -- timestamps for duration tracking.

Clicking a task reveals full details, including the module's standard output. This allows administrators to review exactly what actions were performed. For example, a Firefox install might show the apt transactions, repository key updates, and configuration steps carried out.

A key behaviour is that deleting a task report allows the task to be re-run on that agent. This provides a quick way to retry without redefining the module or re-scheduling.

Tokens¶

Registration tokens control how new agents are added to the system. Each token has:

Name -- descriptive label.
Value -- the secret string used during registration.
Group -- which branch of the agent tree the new device will join.
Enabled -- whether the token is currently usable.

When creating installation images or onboarding devices, tokens are embedded to ensure agents automatically enrol into the correct group. Tokens therefore form the bridge between deployment and day-to-day management. For details on embedding tokens into image creation, see the Deployment section.

Users¶

The Users section manages access to the management console itself. At present, there is only one role type: Administrator.

For each user, the following fields are defined:

Email -- login identity.
Password -- console authentication.
Name -- display name.
Avatar -- optional user icon.

Users can be added or removed here, but since all accounts are administrators, this section is primarily about controlling who has access to manage the estate.

Settings¶

The Settings section configures the behaviour of the management console. It is divided into several tabs:

General -- subscription information, maximum agents, renewal dates, and the RMM URL.
Email -- SMTP server details for sending notifications. Supports TLS, authentication methods, and EHLO/HELO configuration.
Backup -- allows manual or scheduled backups of the console database. Supports S3 storage backends, with fields for bucket, region, endpoint, and access key.
Updates -- displays the current version of the running container services in the rmm-server Compose project. Allows manual updates of the stack.
Agent Installer -- repository of generated installer images used to install ResoluteOS agents. Installers can be created and downloaded here.

Settings should be treated carefully, as changes affect all users and agents connected to the console.

Best Practices¶

The ResoluteOS console provides a flexible framework for managing thin-clients, but how it is used day-to-day makes a huge difference to stability, security, and performance. The following recommendations cover common operational areas and establish practices that will help maintain a reliable deployment.

Token Management¶

Use dedicated tokens per group¶

Instead of a single global token, create separate registration tokens for each branch of the agent tree (for example, "Testing," "Production," or per customer). This prevents accidental mis-assignment and makes it easier to rotate tokens without affecting unrelated machines.

Rotate tokens periodically¶

Treat registration tokens like passwords. Expire and replace them on a regular schedule, particularly after onboarding campaigns or whenever a token has been widely distributed.

Disable old tokens¶

Don't leave tokens enabled after use. Once machines are registered, disable or delete the token to reduce the chance of rogue devices enrolling.

Module Design and Use¶

Keep modules small and focused¶

A module should ideally do one thing (e.g. install Firefox, update certificates, apply a display config). Smaller modules are easier to troubleshoot and can be re-run independently.

Leverage priorities¶

Use the Priority field to order modules sensibly. For example, run base OS updates first (high priority), then install applications, then apply cosmetic settings.

Schedule with care¶

Don't overload agents by scheduling too many modules at the same time. Stagger updates or maintenance windows to spread the load, particularly in large estates.

Test before rollout¶

Always assign new or modified modules to a small test group first. Once verified, move them into the Main or Production branch.

Capture output where possible¶

For diagnostic purposes, enable output capture on modules unless the output is excessively large. This makes troubleshooting far easier later.

Task Management¶

Re-run by deleting reports¶

Remember that deleting a task report re-runs the task on that agent. Use this sparingly, and ideally only after reviewing the output to confirm the cause of failure.

Monitor durations¶

A sudden increase in execution time for routine modules (e.g. System Update) can indicate network problems, repository issues, or performance bottlenecks.

Review regularly¶

Build a habit of reviewing recent tasks and their statuses from the Tasks page. This provides an early warning system for systemic issues.

Agent Organisation¶

Use groups logically¶

Plan your agent tree around how you intend to manage devices. Group by site, department, or role -- not just Devices. This allows different modules to be targeted appropriately.

Move devices as they progress¶

New devices may initially be placed in a Staging group, where test modules and a distinctive wallpaper indicate they are in preparation. After validation, devices can be moved to production branches and assigned the appropriate module set.

Keep metadata updated¶

Use the Edit option to keep agent names and details accurate. A clean inventory makes searching and reporting much simpler.

Network Install and Live Stream Hosts¶

One host per subnet, one role per host¶

Network Install and Live Stream are mutually exclusive. A single node cannot run both, and a subnet must not have both active simultaneously. Decide which deployment method applies to each subnet and assign only that module to the host.

Dedicate a node and isolate it in its own branch¶

Deploy a dedicated ResoluteOS node for Network Install or Live Stream rather than reusing an existing client device. Place this node in its own branch in the agent tree, separate from the devices it serves. This prevents client-targeted modules from being applied to the host and keeps management clean.

Keep the host token correct¶

All devices installed or booted via a Network Install or Live Stream host inherit the host's token. Verify the host's token assignment before running any large-scale rollout.

Ensure adequate bandwidth¶

Network Install and Live Stream both serve a ~1.5-2 GB image. On congested networks, simultaneous boots may degrade performance. Consider staggering boot sequences or segmenting rollouts.

Live Stream RAM requirements¶

Before deploying Live Stream clients, confirm all target hardware has at least 4 GB of RAM. Devices with less will fail to boot. 8 GB is strongly recommended for production use.

User and Access Control¶

Keep accounts minimal¶

Since all users are administrators, only create accounts for staff who genuinely need console access. Fewer accounts mean lower risk.

Rotate passwords¶

Ensure admin passwords are rotated regularly and follow strong password practices. ResoluteOS checks passwords against common leaks when they are set.

Monitor who has access¶

Periodically review the Users page and remove accounts no longer required.

Backups and Recovery¶

Enable automated backups¶

Configure scheduled backups rather than relying on manual exports. Store these in an S3 bucket, like Amazon S3 or MinIO, to ensure they are offsite and protected.

Test restores¶

Backups are only useful if they can be restored. Regularly test importing backups into a secondary console.

Protect encryption keys¶

When generating the initial encryption key, store it securely. Losing this key will prevent restoration of backup data encrypted in the database.

System Health¶

Watch the Dashboard¶

The Dashboard is a useful pulse check. Make it part of the daily routine to glance at agent counts, active tasks, and system health metrics.

Investigate anomalies early¶

Spikes in CPU or memory usage, or sudden drops in available agents, should be treated as warnings and investigated immediately.

If you notice high File Descriptors usage on the dashboard, you may need to increase the maximum allowed for Docker. On most Linux systems, this is controlled by the ulimit setting and systemd service configuration. To raise the limit:

Edit the Docker service override file:
```
sudo systemctl edit docker
```
Add the following lines to set a higher limit (e.g., 1,000,000):
```
[Service]
LimitNOFILE=1000000
```

Reload systemd and restart Docker:

sudo systemctl daemon-reload
sudo systemctl restart docker

This sets the maximum number of open files for Docker containers. Adjust the value as needed for your environment. You can verify the new limit with:

cat /proc/$(pidof dockerd)/limits | grep "Max open files"

Keep the console updated¶

Apply updates to the console itself during maintenance windows. This ensures compatibility with agents and avoids security drift.

Remote Access and Control¶

Use Remote Control sparingly¶

Remote shadowing is powerful, but it is best reserved for support and troubleshooting. Where possible, rely on modules or terminal access to perform tasks at scale.

Leverage Terminal for fixes¶

If a module fails, terminal access provides a way to check logs or run commands interactively without needing to rebuild the module.

Clipboard management¶

Remember that clipboard syncing allows sensitive data to be transferred between local and remote machines. Use it carefully and clear contents when done.

End User Client Management¶

ResoluteOS provides a simple but capable configuration interface for end users. This ensures that devices can be deployed and maintained with minimal IT intervention, while still giving users access to basic system controls such as networking and display settings.

The client management interface is accessed by right-clicking the desktop. A small menu appears with the following options:

ResoluteOS Configuration -- launches the configuration panel.
Windows -- opens a window switcher to cycle between active applications.
Restart -- reboots the device.
Shut Down -- powers off the device.

These controls are intentionally streamlined to avoid clutter or unnecessary complexity.

Configuration Panel¶

When ResoluteOS Configuration is selected, the user is presented with a multi-tab panel. This centralises all client-side management into a single location.

System Tab¶

Displays general device information, including:

ResoluteOS build version and build date.
Privacy policy link.
Machine information such as hostname, OS, architecture, and kernel version.
Current uptime.
Agent status (including the URL of the management server and whether the agent is active).

This tab provides reassurance that the device is correctly enrolled and communicating with the management platform.

Configuration¶

The Configuration tab groups miscellaneous hardware controls:

Audio output -- Selects the default audio output device when multiple outputs are available (e.g., built-in speakers, a monitor's HDMI audio, or a USB headset).
Backlight -- On laptop hardware where supported, controls screen brightness.

Ethernet¶

The Ethernet configuration tab allows control of wired network settings. Options include:

Disabled -- turns off the Ethernet adapter.
DHCP -- default behaviour, automatically requesting an IP address from the network.
Static -- allows manual configuration of IP, subnet, gateway, and DNS.

Once changes are made, clicking Apply Configuration activates the settings.

Wi-Fi¶

If a Wi-Fi adapter is present, this tab provides wireless management. Users can:

Scan for available networks.
Connect using standard authentication methods (WPA2, WPA3, etc.).
Toggle the interface on or off.
Manage a list of saved networks -- add a new network, remove a saved one, or choose which saved network to connect to.

If no Wi-Fi hardware is available, the panel simply reports No Wi-Fi interfaces found.

Bluetooth¶

The Bluetooth panel provides options for pairing and managing wireless peripherals such as keyboards, mice, headsets, or speakers. Users can:

Enable or disable the adapter.
Scan for nearby devices.
Pair or unpair devices as needed.

If no adapter is present, the interface reports No Bluetooth adapter found.

Monitors¶

The Monitors tab is used to configure display settings. Features include:

Detection of all attached monitors.
Setting a monitor as Primary.
Adjusting resolution.
Changing orientation (landscape, portrait, flipped).
Choosing Mirror or Extend mode for multi-monitor setups.
Arranging the position of multiple monitors (side by side, stacked, etc.) when in Extend mode.
Viewing technical details (connector type, resolution, position).

This ensures dual-screen or multi-monitor deployments can be adjusted at the client level without requiring IT intervention.

Summary¶

The end user client management functions strike a balance: they expose enough configuration to support normal use (networking, peripherals, and display management), but they avoid overcomplicating the interface. Most deeper controls are reserved for administrators via the management console, keeping the client experience lightweight and predictable.

Troubleshooting¶

Even with careful planning and best practices, issues will arise in day-to-day operations. ResoluteOS provides visibility into tasks, agents, and modules, but effective troubleshooting requires knowing where to look and how to interpret the information presented.

General Troubleshooting Process¶

When an issue occurs, follow this basic flow:

Check Task Status
- Navigate to the Tasks page or the Task Reports tab for the affected agent.
- Confirm whether the task shows a green success icon or a red failure state.
Review Task Output
- Click into the task result to view logs.
- Use the Standard Output section to identify which step failed (e.g., package not found, permission denied).
Re-run if Needed
- If the error was temporary (such as a network failure), delete the task report. This will allow the task to re-run on that agent.
Escalate to Terminal or Remote Control
- If repeated failures occur, use the built-in Terminal to inspect logs directly on the machine.
- For user-visible problems, Remote Control allows shadowing the session to reproduce the issue interactively.
Document and Resolve
- Note the cause and resolution in your internal tracking. This ensures recurring issues can be resolved faster in future.

Task Failures¶

Symptoms

Task reports show a red failure icon, or exit status includes non-zero codes.
Checks
- Review output for failed commands.
- Confirm whether dependencies (like repositories or Python libraries) are available.
- Look for permission errors.
Resolution
- Adjust the module and re-deploy.
- Delete the failed report to re-run the corrected module.
- Use Terminal to validate fixes manually before committing changes to the module.

Module Misconfiguration¶

Symptoms

Modules run successfully but do not produce the desired state (e.g., software not installed, settings not applied).
Checks
- Confirm the module definition. Was the target path, package name, or registry key correct?
- Validate conditions: is the module being applied to the correct group of agents?
Resolution
- Edit and simplify the module to confirm the core function works.
- Use test groups before rolling changes to all agents.

Agent Not Responding¶

Symptoms

An agent appears offline in the console, or tasks do not run.
Checks
- Confirm the device has network connectivity.
- Check that the RMM agent service is running.
- Validate that the agent has not been moved to a disabled group.
Resolution
- Restart the agent service or reboot the device.
- Re-register the agent using a fresh token if necessary.
- Ensure firewall rules allow connectivity back to the console.

Agent Failing to Register -- TLS Certificate Error¶

Symptoms

The agent attempts to register but fails with a TLS error such as certificate signed by unknown authority. This occurs when the RMM server uses a certificate issued by an internal or private CA that the device does not yet trust.
Checks
- Confirm that Use Custom CA Certificate was enabled when the installer image was created.
- On the device, check whether /usr/local/share/ca-certificates/resoluteos-ca.crt exists.
- Check the CA install service: systemctl status resoluteos-ca-install
- Confirm the CA bundle is accessible on the server: curl -k https://<rmm-server>/static/ca-bundle.pem
Resolution
- If the cert file is missing, the CA install service may have failed or the image was built without the custom CA option. Re-create the installer image with Use Custom CA Certificate enabled and re-image the device.
- If the service failed, check its journal: journalctl -u resoluteos-ca-install
- If the cert is present but registration still fails, run update-ca-certificates manually and restart the agent: systemctl restart rmm-agent

OVD Desktop Client Fails to Download on a Restricted Network¶

Symptoms

The OVD Desktop Client module fails, with task output showing a failed download from archive.inuvika.com.
Checks
- Confirm whether the device has direct outbound internet access, or is behind a firewall/proxy that blocks it.
- Check whether Use Offline Source is enabled on the module.
- If it is enabled, confirm the mirror exists on the console: curl -I https://<rmm-server>/static/ovd/ovd-edc-amd64.run (or ovd-edc-arm64.tar.bz2 for Raspberry Pi devices).
Resolution
- If the device has no direct internet access, enable Use Offline Source on the module so it pulls from the console's own /static/ovd/ mirror instead.
- If the mirror files are missing or stale, build a new Agent Installer image (any image, PXE support not required) -- this automatically refreshes both files at /static/ovd/.
- If a Custom download URL is set, it takes precedence over both the offline mirror and Inuvika's archive -- clear it if you want the module to use the offline mirror or public archive again.

SecureBoot Enabled During Imaging¶

Symptoms

The installer media won't boot, or displays an on-screen message that SecureBoot is enabled and imaging cannot proceed.
Checks
- Confirm SecureBoot's current state in the device's firmware setup.
Resolution
- Disable SecureBoot in firmware, then boot from the installer media again.
- SecureBoot can be safely re-enabled once installation completes -- the deployed OS supports it independently of the installer media.

Network Install or Live Stream Host Issues¶

Symptoms

PXE clients fail to boot, hang at a black screen, or receive no PXE offer.
Checks
- Confirm the host's Network Install or Live Stream module ran successfully (check Task Reports).
- Verify the installer image is accessible over HTTP from the subnet: curl -I http://<host-ip>/liveboot/filesystem.squashfs
- Check TFTP is serving files: attempt tftp <host-ip> and get vmlinuz from another device.
- Confirm dnsmasq is running on the host: systemctl status dnsmasq
- Verify there is only one PXE host on the subnet.
Resolution
- If the image is missing or stale, delete the module's task report and re-run it to trigger a fresh build.
- If TFTP permissions are incorrect, ensure kernel and initrd files in /srv/tftp are world-readable (chmod -R a+r /srv/tftp).
- If clients hang after booting the kernel, the image may still be decompressing in RAM. Allow 2-5 minutes before concluding there is a fault.

Live Stream Device Not Registering¶

Symptoms

A Live Stream device boots successfully but does not appear in the RMM console.
Checks
- On the device, check /boot/firmware/resoluteos.txt to confirm the RMM URL and token were injected correctly.
- Verify the RMM agent service is running: systemctl status rmm-agent
- Confirm the token embedded in the Live Stream host's kernel cmdline is valid and enabled in the console.
Resolution
- If resoluteos.txt is empty, the token injection service did not run. Check systemctl status resoluteos-token and run it manually to confirm it works: bash /etc/resoluteos-token.sh
- Restart the RMM agent after confirming the token file is populated: systemctl restart rmm-agent

Hardware Information Missing¶

Symptoms

Running the Hardware Info module produces incomplete or missing data.
Checks
- Verify the agent has sufficient privileges to collect hardware data.
- Confirm the device is not in a restricted environment (e.g., certain VMs hide information).
Resolution
- Run Hardware Info locally in Terminal to see what the OS reports.
- Update the agent to the latest version to ensure compatibility.

Remote Control Issues¶

Symptoms

Remote Control fails to start, displays a black screen, or disconnects unexpectedly.
Checks
- Confirm the agent has a graphical session running.
- Validate that clipboard, scaling, and input controls are functional.
Resolution
- Restart the agent session.
- Reduce scaling (e.g., set to 1:1) if performance is poor.
- If the issue persists, fall back to Terminal for support.

Backup and Restore Failures¶

Symptoms

Scheduled backups fail, or restore attempts produce errors.
Checks
- Confirm storage backend credentials (e.g., S3 keys).
- Ensure the encryption key is available and valid.
Resolution
- Re-run backups manually to verify connectivity.
- Restore to a test instance first to isolate the failure cause.
- Rotate credentials if authentication fails.

Network and Connectivity Problems¶

Symptoms

Agents appear online intermittently, or tasks fail due to timeouts.
Checks
- Use the System or Ethernet/WiFi configuration panels to confirm IP and DNS settings.
- Test connectivity from Terminal with ping or curl.
Resolution
- Adjust configuration in the console and re-apply.
- Move the device to a test group to reduce load while troubleshooting.
- Confirm firewall rules are not blocking agent <-> console communication.

Troubleshooting Tips¶

Always start at the Tasks page -- it's the most direct view into what happened.
Use delete to re-run sparingly. If a task fails more than once, investigate root cause before repeating.
For complex problems, use Terminal first, then escalate to Remote Control if user context is required.
Keep logs and outputs -- copy them before closing the result window, especially when investigating with multiple admins.
Apply fixes incrementally -- change one thing at a time and validate.

Conclusion¶

ResoluteOS provides a structured, manageable, and secure way to deploy and operate thin clients at scale. By combining a central management console with lightweight endpoint software, it balances administrator control with end-user simplicity.

Key takeaways from this guide:

Deployment establishes the foundation -- from installing the console and generating encryption keys, through USB imaging with SysRescue-based installers, network-based installation via the Network Install module, and stateless kiosk deployments via Live Stream.
Modules are the core building blocks, defining how agents behave. Baseline modules deliver the essentials, while custom modules provide flexibility.
Operations give administrators visibility and direct control, from dashboards and task reports to remote terminals and shadowing sessions.
Best Practices ensure environments remain secure, consistent, and easy to maintain by applying structured approaches to tokens, modules, tasks, and backups.
Troubleshooting provides a logical process to follow when issues arise, reducing downtime and improving resolution speed.
End User Client Management offers just enough local control for users to connect and configure peripherals, without compromising the locked-down nature of the OS.

ResoluteOS is designed to grow with your environment. As your deployment scales, the same principles -- modularity, visibility, and control -- continue to apply. Administrators can expand functionality through custom modules, refine estate structure with tokens and groups, and maintain confidence through monitoring and backups.

With these practices in place, ResoluteOS becomes more than just a thin-client operating system: it becomes a platform for simplified, repeatable, and reliable desktop delivery.

Appendix¶

CRON Expression Format¶

A cron expression represents a set of times, using 5 space-separated fields.

Field name	Mandatory?	Allowed values	Allowed special characters
Minutes	Yes	0-59	* / , -
Hours	Yes	0-23	* / , -
Day of month	Yes	1-31	* / , -
Month	Yes	1-12 for JAN to DEC	* / , -
Day of week	Yes	0-6 for SUN to SAT	* / , -

Special Characters¶

Asterisk ( * )

The asterisk indicates that the cron expression will match for all values of the field; e.g., using an asterisk in the 5^th field (month) would indicate every month.
Slash ( / )

Slashes are used to describe increments of ranges. For example 3-59/15 in the 1^st field (minutes) would indicate the 3^rd minute of the hour and every 15 minutes thereafter. The form */... is equivalent to the form first-last/..., that is, an increment over the largest possible range of the field. The form N/... is accepted as meaning N-MAX/..., that is, starting at N, use the increment until the end of that specific range. It does not wrap around.
Comma ( , )

Commas are used to separate items of a list. For example, using 1,3,5 in the 5^th field (day of week) would mean Mondays, Wednesdays and Fridays.
Hyphen ( - )

Hyphens are used to define ranges. For example, 9-17 in the 2^nd field (hours) would indicate every hour between 9am and 5pm inclusive.

ResoluteOS Documentation¶

Introduction¶

ResoluteOS+¶

Deployment¶

Prerequisites¶

Installation of the RMM Console¶

First Login¶

Registration Tokens¶

Imaging Thin Clients¶

Image Builder -- Ubuntu 24.04¶

Raspberry Pi Image¶

Agent Installer Settings (Ubuntu 24.04)¶

Writing the Image¶

First Boot¶

Network Install¶

How It Works¶

Requirements and Constraints¶

Live Stream¶

How It Works¶

Hardware Requirements¶

Requirements and Constraints¶

Modules¶

Baseline Modules¶

Kiosk Setup¶

OVD Desktop Client¶

Mozilla Firefox¶

System Update¶

Hardware Info¶

Optional Modules¶

Network Install¶

Live Stream¶

Network Utilities¶

Set Admin Password¶

Azure AD / Entra ID Kiosk Authentication¶

Automatic Network Printer Discovery and Mapping¶

FabulaTech Workstation Upgrade¶

Install Custom Deb Package¶

Google Chrome (Multi-Instance)¶

ResoluteOS+ Modules¶

Citrix¶

Omnissa (VMware Horizon)¶

Parallels RAS¶

Microsoft RDP / AVD¶

Custom Modules¶

Structure of a Custom Module¶

Examples¶

Example 1: Bash script for adding a printer¶

Script 1¶

Metadata 1¶

Example 2: Ansible playbook for installing custom software¶

Script 2¶

Metadata 2¶

Best Practices for Modules¶

Operations¶

Dashboard¶

Agents¶

Agent Actions¶

Module Operations¶

Managed Modules¶

Custom Modules Operations¶

Tasks¶

Tokens¶

Users¶

Settings¶

Best Practices¶

Token Management¶

Use dedicated tokens per group¶

Rotate tokens periodically¶

Disable old tokens¶

Module Design and Use¶

Keep modules small and focused¶

Leverage priorities¶

Schedule with care¶

Test before rollout¶

Capture output where possible¶

Task Management¶

Re-run by deleting reports¶

Monitor durations¶

Review regularly¶

Agent Organisation¶