SoftAgent User Manual

Confirm the environment meets requirements and prepare for installation.

1. Confirm the target PC is running Windows 10/11 x64.
2. Confirm you have administrator account privileges (the installer will trigger a UAC elevation prompt).
3. Confirm the firewall allows inbound UDP traffic on port 6500 (SoftAgent's listening port).
4. The installer package is self-contained — no .NET runtime needs to be pre-installed on the target machine.

• Can run programs as administrator (UAC elevation accepted).
• UDP port 6500 is not occupied by another program.

• Multiple controlled PCs can use the same installer — configure port and reporting address independently on each.
• For exhibition projects, recommended to set all controlled PCs to auto-login with an administrator account so the auto-start task triggers reliably.

Complete installation and confirm SoftAgent is running normally in the system tray.

1. Double-click SoftAgent-Setup-version.exe and click Yes in the UAC prompt to allow administrator privileges.
2. Follow the installer wizard to complete installation (default: C:\Program Files\SoftAgent\).
3. On the completion page, optionally check 'Launch SoftAgent now', or start manually after.
4. After startup, SoftAgent appears in the system tray (no main window opens).
5. Right-click the tray icon and select 'Open Config' — confirm the main window appears with 4 tabs (Properties / Programs / Watchdog / Settings).

• SoftAgent icon appears in the system tray.
• Task Manager shows both SoftAgent.App and SoftAgent.Watchdog processes running.
• Right-clicking the tray shows: Open Config / Status / Pause Watchdog / Open Log Directory / About / Exit.

SoftAgent uses a dual-process architecture: the App process handles functionality, and the Watchdog monitors and auto-restarts the App if it crashes — they mutually guard each other.

Complete basic configuration and confirm the agent works via UDP ping.

1. Double-click the tray icon to open the main window, switch to the Settings tab.
2. Confirm the listening port is 6500 (or change as needed), and check 'Auto-start' to register the scheduled task.
3. For SoftControl integration, enter the SoftControl machine's IP:port in the 'Report Address' field.
4. Click 'Save and Apply' to save configuration.
5. Open PowerShell and send a ping to verify:
6. $u = New-Object System.Net.Sockets.UdpClient
7. $b = [Text.Encoding]::UTF8.GetBytes('ping')
8. $u.Send($b, $b.Length, '127.0.0.1', 6500)
9. $r = $u.Receive([ref](New-Object System.Net.IPEndPoint([Net.IPAddress]::Any, 0)))
10. [Text.Encoding]::UTF8.GetString($r)
11. Receiving ok:pong confirms the agent is working normally.

• Sending ping receives ok:pong response.
• Auto-start checkbox in Settings tab is saved.
• Running schtasks /Query /TN SoftAgent shows the registered scheduled task.

• Changing port but forgetting to click 'Save and Apply', so the change doesn't take effect.
• Entering the HTTP management console port instead of the UDP listening port.

Master the command format and risk levels for safe use of SoftAgent.

1. Command format: verb or verb:arg (argument follows the first colon), e.g. volume:80 or ping.
2. Success response: ok:<code>, e.g. ok:pong or ok:volume.
3. Failure response: err:<code>, e.g. err:wol.invalidMac.
4. Three risk levels: Safe (no disruption, repeatable) / Disruptive (interrupts session/process but no data loss) / Destructive (shutdown/restart/logoff etc.).
5. Destructive commands show a confirmation dialog in the UI. When triggered remotely, the caller is responsible for confirming intent.

• Sending ping receives ok:pong, confirming connection and command format are correct.
• Sending describe receives a JSON capability list with all supported commands and their risk levels.

The describe command returns the full capability list of this SoftAgent instance, including each command's name, description, risk level, and whether confirmation is required — useful for capability discovery when integrating with SoftControl or AI systems.

Master Safe commands for daily volume control and status monitoring.

1. Connectivity probe: ping (responds ok:pong, confirms agent is online).
2. Get capability list: describe (returns JSON listing all commands with descriptions and risk levels).
3. Device discovery: discover (returns a heartbeat snapshot JSON with hostname, IP, MAC, volume, guard status).
4. Volume up one step: volup (default +5% per call).
5. Volume down one step: voldown (default -5% per call).
6. Toggle mute: mute (toggle between muted and unmuted).
7. Get primary NIC MAC address: getmac (returns uppercase hyphen-separated format, e.g. AA-BB-CC-DD-EE-FF).
8. Send Wake-on-LAN magic packet: wol:AA-BB-CC-DD-EE-FF (wake the machine with specified MAC).
9. Keyboard simulation: key:^s (Ctrl+S), key:{F5} (F5 key), key:Hello (type characters).

• ping command returns ok:pong.
• volup/voldown changes the controlled machine's volume.
• wol command wakes the target machine (requires WoL enabled on target).

• Use discover to quickly get the current state of a controlled machine (IP, volume, guard status) — useful for SoftControl batch health checks.
• key: uses Microsoft SendKeys syntax: ^ is Ctrl, % is Alt, + is Shift, special keys in braces like {ENTER}.

Master screen lock, process start/stop, and cancel-shutdown commands.

1. Lock screen: lock (locks the current workstation — re-login to restore).
2. Cancel a pending delayed shutdown/restart: cancelshutdown (use during shutdown countdown).
3. Start a watchdog item by ID: run:id (e.g. run:db-player starts the item named db-player).
4. Stop a watchdog item by ID: stop:id (stops and pauses watchdog — process won't be auto-restarted).
5. Start a managed program by index: startpro:0 (starts the program at index 0 in the managed programs list).
6. Stop a managed program by index: killpro:0.
7. Stop all managed programs: killall.

• After lock, the controlled machine shows the lock screen.
• After run:id, the corresponding watchdog item starts — status changes from Stopped to Running in the Watchdog tab.
• cancelshutdown sent during a shutdown countdown cancels the shutdown.

• Use run/stop with watchdog ID (a stable identifier) rather than startpro/killpro with index (index changes when items are deleted or reordered).
• Watchdog IDs are configured in SoftAgent's Watchdog tab. Update SoftControl commands if you rename an ID.

Safely execute destructive operations like shutdown, restart, and logoff.

1. Delayed shutdown (recommended): shutdown:60 (shutdown after 60 seconds, cancelshutdown can cancel during countdown).
2. Immediate shutdown (use with caution): shutdown (no delay, cannot cancel).
3. Delayed restart (recommended): reboot:60 (restart after 60 seconds).
4. Restart into BIOS/UEFI: reboot:firmware (requires UEFI firmware support).
5. Logoff current user: logoff (confirm no unsaved data before executing).
6. Enable/Disable UAC: uac:off / uac:on (registry change, requires restart to take effect, requires admin).
7. Enable/Disable touchscreen edge gestures: edgeswipe:off / edgeswipe:on.
8. Enable/Disable Windows startup auto-repair: autorepair:off / autorepair:on.

• After shutdown:60, the system shows a countdown notification 'shutting down in 60 seconds'.
• cancelshutdown sent during the countdown cancels the shutdown.

• Sending shutdown without a delay, making it impossible to cancel — the controlled machine shuts down immediately.
• After uac:off, not rebooting and assuming UAC is already disabled (requires restart to take effect).

Shutdown commands require administrator privileges. If insufficient permissions, a clear error code like err:power.denied is returned — no silent failure.

Complete basic configuration so SoftAgent can be correctly discovered and controlled by SoftControl.

1. Open the SoftAgent main window and switch to the Settings tab.
2. Listening Port (default 6500): SoftControl and other controllers send UDP commands to this port.
3. Report Address (format IP:port): SoftAgent sends periodic heartbeat JSON to this address; enter SoftControl's IP and listening port.
4. Heartbeat Interval (seconds): default 10 seconds; heartbeats contain hostname, IP, MAC, volume, guard status, etc.
5. Auto-start Delay (seconds): delay after login before SoftAgent starts (useful for waiting for network readiness).
6. Click 'Save and Apply' after changes — port changes show a persistent 'Restart Required' notice; other changes take effect immediately.

• Configuration takes effect immediately after saving (port changes require restart).
• If a reporting address is configured, SoftControl should start receiving periodic heartbeat JSON from this SoftAgent.

• For multiple controlled PCs, recommend using the same port (6500) across all to simplify batch command entry in SoftControl.
• Leaving report address empty means SoftAgent won't proactively send heartbeats but will still respond to UDP commands.

Modify controlled machine IP configuration through SoftAgent's interface without RDP.

1. Open the main window, switch to the Properties tab, and select the target network card in the network panel dropdown.
2. After selecting a NIC, current IP, subnet mask, gateway, DNS, and MAC address are auto-filled.
3. Toggle 'Static IP / DHCP' mode: fields are editable in Static mode; read-only in DHCP mode.
4. Fill in the target IP, subnet mask, gateway, and DNS (Static mode).
5. Click 'Change IP Settings' and confirm in the confirmation dialog.
6. IP change is a destructive operation — the current connection drops after the change. Reconnect with the new IP.

• After the change, the controlled machine can be pinged successfully at the new IP address.
• SoftAgent heartbeat JSON shows the updated IP address.

Changing IP is destructive. Before proceeding, confirm the new IP is reachable on the LAN to avoid losing remote access to the controlled machine.

Configure auto-start so SoftAgent automatically resumes running after the controlled PC restarts.

1. In the main window Settings tab, check 'Auto-start'.
2. Click 'Save and Apply'.
3. Verify with: schtasks /Query /TN SoftAgent in PowerShell — confirm the scheduled task is registered.
4. Task trigger: ONLOGON (triggers after user login) with HIGHEST privilege level.
5. To set a startup delay (wait for network or dependent services), set seconds in the 'Auto-start Delay' field.
6. To disable auto-start, uncheck 'Auto-start' and save.

• schtasks /Query /TN SoftAgent shows the task exists and is enabled.
• After restarting the controlled PC, SoftAgent automatically appears in the system tray after login.

Complete SoftAgent command setup in SoftControl for button-based control of controlled machines.

1. Enter SoftControl admin panel and open Command Management.
2. Create a new command, select UDP protocol.
3. Set target address to the controlled PC's IP (e.g. 192.168.1.101).
4. Set port to SoftAgent's listening port (default 6500).
5. Set command text to the specific command, e.g.: volup (volume up), mute (toggle mute), lock (lock screen), shutdown:60 (shutdown in 60s).
6. Save and test the command individually — confirm the controlled machine responds correctly.
7. Bind the verified command to a button on SoftControl's front-end interface.

• After SoftControl sends the UDP command, the controlled machine's SoftAgent executes the action.
• SoftControl logs show the command was sent successfully (OK response).

• Create a command set for each controlled machine, using the device name as a prefix (e.g. 'Hall-PC-01_Shutdown') for easy maintenance.
• For batch operations like closing the exhibition, use SoftControl's command groups — add shutdown commands for multiple machines to one group and trigger once.

Configure heartbeat reporting to monitor controlled machine online status from SoftControl.

1. In SoftAgent settings, configure the report address to SoftControl's IP:port (SoftControl's external UDP interface, default 8818).
2. SoftAgent immediately sends one heartbeat on startup, then continues at the configured interval (default 10 seconds).
3. Heartbeat JSON includes: agentId (unique device identifier), hostname, ip/mac (network info), volume/muted (audio state), guards (watchdog process states), uptimeSeconds.
4. To actively query a controlled machine's current state, send discover from SoftControl — SoftAgent returns a heartbeat snapshot.
5. The guards field in heartbeats indicates whether watchdog processes are running normally, revealing crashes or give-up states.

• SoftControl receives periodic heartbeat JSON from SoftAgent.
• Sending discover receives a JSON response with hostname, IP, volume, and other info.

Configure crash auto-restart watchdog for exhibition applications.

1. Open the SoftAgent main window and switch to the Watchdog tab.
2. Click 'Browse...' to select the .exe to guard, optionally set a name and watchdog ID (stable identifier used for run/stop commands).
3. Click 'Add' to put it in the watchdog list. Individual toggle controls whether this item's watchdog is enabled.
4. The master watchdog toggle is at the top of the tab — disabling pauses all watchdog (synced with tray 'Pause Watchdog' menu).
5. Status badges show the state of each item: Running / Stopped / Crashed / GaveUp (watchdog abandoned after too many crashes in the time window).
6. After a crash, SoftAgent restarts with exponential backoff (initial 5 seconds, doubling each time; abandoned after limit exceeded in time window).

• The guarded program shows 'Running' status in the watchdog list.
• Manually killing the guarded process and SoftAgent automatically restarts it after a delay.
• Heartbeat JSON guards field reflects the latest watchdog states.

Don't change the watchdog ID arbitrarily — SoftControl run/stop commands depend on it. If you rename an ID, update the corresponding SoftControl commands.

Restore the UDP command control channel.

1. Confirm SoftAgent is visible in the system tray (process is running).
2. Confirm the sending port matches SoftAgent's configured listening port (default 6500).
3. Check whether Windows Firewall allows inbound UDP traffic on port 6500.
4. Try ping from localhost (127.0.0.1) first to rule out network issues, then try remotely.
5. Check log files in %ProgramData%\SoftAgent\logs\ for command reception records.

• Sending ping to 127.0.0.1 receives ok:pong, confirming SoftAgent and UDP port are working.
• Sending ping from a remote machine also receives a response, confirming network path is clear.

Ensure SoftAgent runs with administrator privileges to support all system-level commands.

1. Confirm SoftAgent runs with admin rights: auto-start uses scheduled task HIGHEST privilege; for manual start, right-click the exe and 'Run as administrator'.
2. If commands are triggered via SoftControl, SoftControl itself doesn't need admin rights — privileges are determined by SoftAgent on the controlled side.
3. Check the 'Elevated' column for SoftAgent.App.exe in Task Manager's Details tab — should show 'Yes'.
4. If not running as admin, exit SoftAgent and restart it as administrator.

• Task Manager Details tab shows 'Yes' in the Elevated column for SoftAgent.App.exe.
• volup/voldown commands respond normally (no admin required — useful for basic verification).
• lock command locks the controlled machine screen (Disruptive level — confirms privilege is correct).

Diagnose and fix auto-start failures.

1. Run schtasks /Query /TN SoftAgent in PowerShell to confirm the scheduled task exists.
2. If the task doesn't exist, open SoftAgent's Settings tab, re-check 'Auto-start', and save.
3. Confirm the PC uses auto-login (common in exhibitions) rather than waiting for manual login — the task trigger is ONLOGON, requiring a user to log in.
4. If set up for auto-login, confirm the auto-login account has permissions to run the task (requires administrator account).
5. Check recent logs in %ProgramData%\SoftAgent\logs\ for startup failure reasons.

• schtasks /Query /TN SoftAgent output contains ONLOGON trigger and HIGHEST privilege.
• After restarting the controlled PC and logging in, SoftAgent automatically appears in the system tray.

Understand why watchdog gave up and restore monitoring of the target application.

1. In the SoftAgent main window Watchdog tab, check the status badge — confirms 'GaveUp' state.
2. Check log files in %ProgramData%\SoftAgent\logs\ for the specific crash reason (errors before each crash).
3. Fix the root cause of the guarded application's crashes (config error, missing dependency, port conflict, etc.).
4. After fixing, toggle the watchdog item's individual switch off then on in the Watchdog tab (or send run:id from SoftControl) to re-trigger watchdog.
5. Confirm the watchdog item status changes to 'Running' and stays stable over time.

• After fixing the guarded application, watchdog status changes from 'GaveUp' to 'Running'.
• Heartbeat JSON shows the corresponding watchdog item status updated to running.

GaveUp is intentional behavior to prevent infinite restart storms from impacting system resources. The real solution is to fix the root cause of the crash — not to manually re-trigger watchdog repeatedly.