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.

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

1. 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.

2. 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.

3. 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
   

4. 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.

5. 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).

First Login

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.
• 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 ISO 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

Once the console is online, you can create custom installer images for your thin clients.

Agent Installer Settings

In Settings → Agent Installer, the following options are defined:

• Image name -- The filename of the generated ISO. A clear naming convention (e.g., site-branch-date) makes identification easier later.
• Token -- Ensures devices register into the correct branch automatically.
• Admin password -- Defines the local administrator account password on the thin client. This account is used only for troubleshooting and should not be shared widely.
• Network configuration
  • DHCP -- Automatically assigns network details. Recommended for most deployments.
  • Manual -- Prompts for static IP settings on first boot. Useful in labs or non-DHCP networks.
• Recovery partition -- Adds a boot option for recovery. Handy in test environments, but usually disabled in production to avoid confusion.
• Enable SSH -- Allows remote login for administrators. Powerful, but may be disabled in highly secure environments.
• Timezone, locale, keyboard -- Ensures the device matches user expectations (e.g., UK keyboard layout for UK sites).

Once defined, the console remasters the latest Ubuntu 24.04 LTS ISO with these settings applied. The result is a fully customised installer ISO.

Writing the ISO

The ISO 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. DVD media can also be used where necessary.

First Boot

When a device is booted from the installer, it:

1. Applies the defined settings (network, admin password, etc.).
2. Registers with the console using its embedded token (if enabled).
3. Inherits modules from its branch.
4. Checks in with the server for updates or additional configuration.

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

PXE Installs

For large rollouts, PXE can replace USB media.

• First, install one device using the ISO method.
• Assign it the Network Install module.
• This converts the device into a PXE server for its subnet.
• Other devices set to PXE boot will automatically install ResoluteOS from this host.

Important

• Only one PXE host should exist per subnet. Multiple PXE servers create unpredictable results.
• Ensure the PXE host has the correct token assigned, otherwise all devices it installs will appear in the wrong branch.
• For multi-site or VLAN environments, PXE requires careful DHCP and routing configuration.

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 both visual branding and security settings:

• 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 set during imaging 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.

Together, these options control whether a device is a sealed appliance or a flexible IT-managed endpoint.

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:

• 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 host, enabling network-based installations.

• It must first be installed via ISO before PXE can be enabled.
• Only one PXE host should exist per subnet to avoid conflicts.
• Devices PXE-booting from this host will automatically install ResoluteOS using the host's token.

This is particularly useful for large classrooms or labs where dozens of devices need to be provisioned quickly.

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 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.

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 define 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", "value2"])
  • 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.
• 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 ISOs 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 ISO 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 uploaded ISO 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.

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 Amaz on 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:

1. Edit the Docker service override file:

   sudo systemctl edit docker
   

2. Add the following lines to set a higher limit (e.g., 1,000,000):

   [Service]
   LimitNOFILE=1000000
   

3. 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.

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.

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).
• Arranging the position of multiple monitors (side by side, stacked, etc.).
• 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:

1. 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.
2. 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).
3. 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.
4. 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.
5. 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.

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, generating encryption keys, and creating ISOs, through to PXE-based rollout.
• 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.