Windows Agent Installation Guide

This document shows how to install and manage the Windows agent for Unmeshed Job Scheduling Platform. The agent is a Java-based application which runs natively on Windows machines and executes the scheduled jobs as configured on the Unmeshed Platform. The integration between agent and Unmeshed platform is protected by an access key and secret and happens over an HTTPS connection.

The Windows agent requires Java 22 or higher. The agent package includes a bundled JRE in the jdk folder, which is the recommended approach for consistent operation.

• Windows 10/11 or Windows Server 2016/2019/2022 or newer versions
• Minimum 2GB RAM (4GB recommended)
• At least 4GB free disk space (for logs and temporary files)
• Network access to the Unmeshed platform
• Administrator privileges for service installation

This zip file contains the foundational components required for the agent to operate:

• jdk/ - Java Development Kit folder containing the bundled JRE
• worker-logback.xml - Logging configuration for the worker processes
• start_agent.bat - Batch script to start the agent

This zip file contains the main agent execution files:

• workers.jar - Main worker execution engine (will be created/updated)

The installation process involves two main steps: installing prerequisites and then the agent binary. We'll use C:\unmeshed\agent\ as the installation directory.

1. Create the installation directory:

   cmd

2. Download and extract the prerequisites package:

   cmd

   You should see the following files and directories:

1. Download and extract the agent binary package:

   cmd

   You should see:

In Windows, you configure the agent by editing the start_agent.bat file. This file contains all the necessary environment variables and Java settings.

Edit the start_agent.bat file:

The file should contain the following content with your specific values:

The UNMESHED_CMD_CUSTOM_WORKERS parameter allows you to create multiple custom cmd workers with different configurations. This is useful when you need different concurrency limits or want to separate workloads by namespace.

:::note For Windows agents, the ioThread parameter must always be set to false. :::

Each worker specification follows the format: namespace:name:maxConcurrentWorkers:false

• namespace: The namespace for this worker (e.g., "default", "prod", "dev")
• name: The worker name identifier that will be used in job definitions
• maxConcurrentWorkers: Maximum number of concurrent jobs this worker can handle
• ioThread: Must be set to false for Windows agents (required parameter)

Single Custom Worker:

This configuration will query for jobs in the prod namespace with the name high-priority-cmd and can run up to 100 concurrent tasks.

Multiple Custom Workers:

This configuration creates three workers:

• default:standard-cmd:50:false - Namespace default, jobs named standard-cmd, concurrency of 50
• prod:high-priority-cmd:100:false - Namespace prod, jobs named high-priority-cmd, concurrency of 100
• dev:testing-cmd:25:false - Namespace dev, jobs named testing-cmd, concurrency of 25

No Custom Workers (Default):

Use descriptive names that represent your host machine's purpose:

• Environment-based: prod-web-server-cmd, staging-db-cmd, dev-testing-cmd
• Function-based: batch-processing-cmd, real-time-cmd, backup-server-cmd
• Location-based: us-east-1-cmd, eu-west-1-cmd, on-premise-cmd

Why unique names matter: Using unique, descriptive names ensures that specific jobs will always run on the intended machine. For example, if you have a backup server with set UNMESHED_CMD_CUSTOM_WORKERS=default:backup-server-cmd:10:false, only jobs defined with the name backup-server-cmd in the default namespace will be executed on that machine.

Windows Task Scheduler is the native Windows solution and is recommended for most users. It's easier to set up and manage than third-party tools.

1. Open Task Scheduler:

   • Press Win + R, type taskschd.msc, and press Enter
   • Or search for "Task Scheduler" in the Start menu

2. Create Basic Task:

   • Right-click on "Task Scheduler Library" → "Create Basic Task"
   • Name: "Unmeshed Agent"
   • Description: "Starts the Unmeshed agent on system startup"
   • Click "Next"

3. Set Trigger:

   • Select "When the computer starts up"
   • Click "Next"

4. Set Action:

   • Select "Start a program"
   • Click "Next"

5. Configure Program:

   • Program/script: C:\unmeshed\agent\start_agent.bat
   • Start in: C:\unmeshed\agent
   • Click "Next"

6. Finish Setup:

   • Review your settings
   • Check "Open the Properties dialog for this task when I click Finish"
   • Click "Finish"

7. Configure Advanced Properties:

   • In the Properties dialog, go to the "General" tab
   • Check "Run with highest privileges"
   • Go to the "Settings" tab
   • Check "Allow task to be run on demand"
   • Check "Run task as soon as possible after a scheduled start is missed"
   • Click "OK"

The agent creates logs in the working directory. Look for the following log entry to confirm successful startup:

You should see a log entry similar to:

If you need to run the agent manually (for debugging purposes):

Follow these steps to upgrade:

1. Stop the agent:

   cmd

2. Download and extract the new agent binary:

   cmd

3. Start the agent:

   cmd

4. Verify the upgrade:

   cmd

1. Service fails to start:

   • Check file permissions: dir C:\unmeshed\agent
   • Verify Java installation: java -version
   • Check Windows Event Viewer for errors

2. Agent cannot connect to Unmeshed platform:

   • Verify network connectivity: ping <your-unmeshed-server>
   • Check authentication credentials in start_agent.bat
   • Verify firewall settings

3. Permission denied errors:

   • Ensure the service user has access to C:\unmeshed\agent
   • Check file permissions: C:\unmeshed\agent

4. Java memory issues:

   • Adjust JVM memory settings in start_agent.bat:
     • -Xms1024m (minimum heap size)
     • -Xmx1500m (maximum heap size)

The agent creates several log files:

• workers.log - Main worker process logs
• Windows Event Viewer - Service management logs

1. File Permissions: Ensure only authorized users can access the agent configuration files
2. Network Security: Use HTTPS connections to the Unmeshed platform
3. Authentication: Keep your auth ID and token secure and rotate them regularly
4. Service User: Run the service with minimal required privileges
5. Firewall: Configure firewall rules to allow only necessary outbound connections

Adjust JVM memory settings based on your system resources:

Adjust based on your system's CPU cores and workload:

Optimize network communication:

1. Service Auto-restart: Configure the Windows service to automatically restart if the process crashes
2. Log Rotation: Consider implementing log rotation for long-running deployments
3. Monitoring: Set up monitoring for the service status and resource usage
4. Backup: Regularly backup your start_agent.bat configuration file
5. Updates: Keep your Windows system updated for security patches
6. Resource Monitoring: Monitor CPU, memory, and disk usage during operation

For users who prefer a service style manager, you can use NSSM (Non-Sucking Service Manager).

1. Download NSSM from https://nssm.cc/download

2. Install the service:

   cmd

3. Additional NSSM Settings (Optional but Recommended):

   cmd

• Creating Client Credentials
• Worker Configuration
• Process Execution
• Agent Management
• Linux Agent Installation
• IBMi/AS400 Agent Installation