Skip to main content

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.

Prerequisites​

Java Runtime Environment (JRE)​

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.

System Requirements​

  • 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

Installation Files​

Prerequisites Package: unmeshed-prerequisites.zip​

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

Agent Binary Package: unmeshed-agent.zip​

This zip file contains the main agent execution files:

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

Contact your Unmeshed support team to request download links for the following agent packages:

  • unmeshed-prerequisites.zip - Prerequisites package
  • unmeshed-agent.zip - Agent binary package

Installation​

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

Step 1: Install Prerequisites​

  1. Create the installation directory:

    mkdir C:\unmeshed\agent
    cd C:\unmeshed\agent

  2. Download and extract the prerequisites package:

    # Download the prerequisites zip file
    # Extract the contents using Windows Explorer or command line
    # Right-click the zip file and select "Extract All" or use:
    powershell Expand-Archive -Path unmeshed-prerequisites.zip -DestinationPath C:\unmeshed\agent

    # Verify the extraction
    dir

    You should see the following files and directories:

    Directory of C:\unmeshed\agent

    jdk/                    <DIR>
    worker-logback.xml
    start_agent.bat

Install Agent Binary​

  1. Download and extract the agent binary package:

    # Download the agent binary zip file
    # Extract the contents (this will create/update workers.jar)
    powershell Expand-Archive -Path unmeshed-agent.zip -DestinationPath C:\unmeshed\agent

    # Verify the extraction
    dir *.jar

    You should see:

    workers.jar

Configuration​

Configure the Agent​

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:

notepad start_agent.bat

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

@echo off
setlocal enabledelayedexpansion

echo Running as user: %USERNAME%
echo Current directory: %CD%
echo PATH: %PATH%

rem Set current directory
set CURRENT_DIR=C:\unmeshed\agent

rem Set Java home to use bundled JDK
set JAVA_HOME=%CURRENT_DIR%\jdk
set PATH=%JAVA_HOME%\bin;%PATH%

rem Set Java options
set JAVA_OPTS=-Xms1024m -Xmx1500m

rem Set required environment variables
set UNMESHED_AUTH_ID=<< your auth id >>
set UNMESHED_AUTH_TOKEN=<< your auth token >>
set UNMESHED_ENABLE_FILE_WATCHER=false
set UNMESHED_ENGINE_URL=<< your engine url >>
set UNMESHED_FILE_WATCHER_MAX_CONCURRENT_WORKERS=10
set UNMESHED_CMD_CUSTOM_WORKERS=
set UNMESHED_CMD_MAX_CONCURRENT_WORKERS=1000

rem Check if Java is accessible
where java >nul 2>&1
if errorlevel 1 (
    echo Error: Java not found in PATH
    exit /b 1
)

rem Start the application
echo Starting workers.jar...
java %JAVA_OPTS% -jar "%CURRENT_DIR%\workers.jar" > "%CURRENT_DIR%\workers.log" 2>&1

Configuration Parameters​

FieldDescription
JAVA_HOMEPoints to the bundled JDK in C:\unmeshed\agent\jdk
PATHUpdated to include the bundled JDK bin directory
JAVA_OPTSJVM memory settings (-Xms1024m for minimum, -Xmx1500m for maximum heap)
UNMESHED_AUTH_IDYour authentication ID from the Unmeshed Platform
UNMESHED_AUTH_TOKENYour authentication token from the Unmeshed Platform
UNMESHED_ENGINE_URLHTTPS URL for your Unmeshed server
UNMESHED_CMD_CUSTOM_WORKERSAdvanced Configuration: Comma-separated list of custom worker specifications in the format namespace:name:maxConcurrentWorkers:false

Example: default:custom-cmd:50,prod:high-priority:100

Format: Each specification contains 4 parts separated by colons:
- namespace: The namespace for this worker (e.g., "default", "prod")
- name: The worker name identifier
- maxConcurrentWorkers: Maximum number of concurrent jobs this worker can handle
- ioThread: Must be set to false for Windows agents (required parameter)

Default Behavior: If left empty, the agent registers a default cmd worker under the "default" namespace with the name "cmd"
UNMESHED_CMD_MAX_CONCURRENT_WORKERSMaximum number of concurrent cmd commands that can be executed simultaneously
UNMESHED_ENABLE_FILE_WATCHEREnable/disable file watching capabilities
UNMESHED_FILE_WATCHER_MAX_CONCURRENT_WORKERSMaximum concurrent file watcher workers

UNMESHED_CMD_CUSTOM_WORKERS Configuration​

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.

Format​

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)

Examples​

Single Custom Worker:

set UNMESHED_CMD_CUSTOM_WORKERS=prod:high-priority-cmd:100:false

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:

set UNMESHED_CMD_CUSTOM_WORKERS=default:standard-cmd:50:false,prod:high-priority-cmd:100:false,dev:testing-cmd:25:false

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):

set UNMESHED_CMD_CUSTOM_WORKERS=
# This registers a default cmd worker under "default" namespace with name "cmd"

Naming Recommendations​

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 Service Setup​

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"

Verify Task Scheduler Setup​

# Check if the task is created
schtasks /query /tn "Unmeshed Agent"

# Check if Java process is running
tasklist /fi "imagename eq java.exe"

# Check agent logs
type C:\unmeshed\agent\workers.log

Verification​

Check Agent Logs​

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

type C:\unmeshed\agent\workers.log

You should see a log entry similar to:

[date - time] [pool-3-thread-1] INFO io.unmeshed.client.UnmeshedClient - Currently running

Check Process Status​

# Check if Java process is running
tasklist /fi "imagename eq java.exe"

# Check Windows Event Viewer for any service errors
eventvwr.msc

Operating the Unmeshed Agent​

Service Management Commands​

# Start the agent (if using Task Scheduler)
schtasks /run /tn "Unmeshed Agent"

# Stop the agent (if using Task Scheduler)
taskkill /f /im java.exe

# Check task status
schtasks /query /tn "Unmeshed Agent"

Manual Process Management​

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

cd C:\unmeshed\agent
start_agent.bat

Upgrading the Unmeshed Agent​

Follow these steps to upgrade:

  1. Stop the agent:

    taskkill /f /im java.exe

  2. Download and extract the new agent binary:

    cd C:\unmeshed\agent
    # Download and extract unmeshed-agent.zip

  3. Start the agent:

    schtasks /run /tn "Unmeshed Agent"

  4. Verify the upgrade:

    schtasks /query /tn "Unmeshed Agent"
    type C:\unmeshed\agent\workers.log

Troubleshooting​

Common Issues​

  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)

Log Analysis​

The agent creates several log files:

  • workers.log - Main worker process logs
  • Windows Event Viewer - Service management logs
# View worker logs
type C:\unmeshed\agent\workers.log

# Search for specific errors
findstr /i "error" C:\unmeshed\agent\workers.log

Security Considerations​

  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

Performance Tuning​

Memory Configuration​

Adjust JVM memory settings based on your system resources:

set JAVA_OPTS=-Xms2048m -Xmx4096m

Concurrency Settings​

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

UNMESHED_CMD_MAX_CONCURRENT_WORKERS: 2000

Batch Processing​

Optimize network communication:

UNMESHED_WORK_RESPONSE_BATCH_SIZE: 200

FAQs & Notes​

  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

Alternative: Using NSSM (Advanced Users)​

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

NSSM Installation​

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

  2. Install the service:

    # Run as Administrator
    nssm install UnmeshedAgent "C:\unmeshed\agent\start_agent.bat"
    nssm set UnmeshedAgent AppDirectory "C:\unmeshed\agent"
    nssm set UnmeshedAgent Description "Unmeshed Agent Service"
    nssm set UnmeshedAgent Start SERVICE_AUTO_START
    nssm set UnmeshedAgent AppStopMethodSkip 0
    nssm set UnmeshedAgent AppStopMethodConsole 1500
    nssm set UnmeshedAgent AppStopMethodWindow 1500
    nssm set UnmeshedAgent AppStopMethodThreads 1500

  3. Additional NSSM Settings (Optional but Recommended):

    # Set service to restart on failure
    nssm set UnmeshedAgent AppRestartDelay 10000

    # Set service account (optional - uses Local System by default)
    # nssm set UnmeshedAgent ObjectName ".\username" "password"

    # View all current settings
    nssm dump UnmeshedAgent

Verify NSSM Service​

# Check if service is running
sc query UnmeshedAgent

# Check if process is running
tasklist /fi "imagename eq java.exe"

# Check agent logs
type C:\unmeshed\agent\workers.log

NSSM Service Management​

# Start the service
net start UnmeshedAgent

# Stop the service
net stop UnmeshedAgent

# Check service status
sc query UnmeshedAgent