Add Windows Task Scheduler deployment guide for persistent daemon

[RCrushMe]

Summary

The official documentation covers Linux/macOS systemd deployment (docs/en/guide/getting-started.md) and the --background detached mode, but has zero guidance for running 1MCP as a persistent daemon on Windows.

Windows is a first-class platform for 1MCP (the npm package ships Windows binaries, 1mcp.cmd is the entry point), yet users must figure out daemon lifecycle management entirely on their own.

What's missing

1. No Windows Task Scheduler section in any of the 78 English docs or the README
2. No recommended schtasks / New-ScheduledTaskAction example for boot-persistent deployment
3. No guidance on RestartOnFailure, BootTrigger delay, or MultipleInstancesPolicy settings that matter for a reliable daemon
4. No post-boot verification checklist for Windows (the systemd section has systemctl status; Windows users get nothing equivalent)

Real-world configuration that works

This is a production-proven Windows Task Scheduler setup (running since 2026-07, survives reboots, auto-recovers on failure):

$node = "D:\nodejs\node.exe"
$entry = "$env:APPDATA\npm\node_modules\@1mcp\agent\build\index.js"
$workdir = "$env:APPDATA\npm\node_modules\@1mcp\agent"
$logfile = "$env:APPDATA\1mcp\logs\server.log"

$args = "$entry serve --transport http --host 127.0.0.1 --port 3100 " +
  "--enable-async-loading --async-min-servers 20 --async-timeout 120000 " +
  "--async-batch-notifications --enable-config-reload " +
  "--config-reload-debounce 500 --log-level info --log-file `"$logfile`""

$action   = New-ScheduledTaskAction -Execute $node -Argument $args -WorkingDirectory $workdir
$trigger  = New-ScheduledTaskTrigger -AtStartup
$settings = New-ScheduledTaskSettingsSet `
  -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries `
  -ExecutionTimeLimit (New-TimeSpan) `
  -RestartCount 5 -RestartInterval (New-TimeSpan -Minutes 2) `
  -StartWhenAvailable -MultipleInstances IgnoreNew

Register-ScheduledTask -TaskName '1mcp-daemon' `
  -Action $action -Trigger $trigger -Settings $settings `
  -Description '1MCP aggregated runtime' -RunLevel Highest

Post-boot verification

schtasks /query /tn '\1mcp-daemon' /fo LIST /v   # Status: Running
1mcp --status                                     # running (ready)
Get-NetTCPConnection -LocalPort 3100 -State Listen
Invoke-WebRequest http://127.0.0.1:3100/health/ready -UseBasicParsing | Select StatusCode  # 200

Why this matters

• Without async loading, serve blocks the HTTP port for 10-12s with many backends; Task Scheduler's health/restart logic can misinterpret this as a crash
• MultipleInstancesPolicy IgnoreNew prevents duplicate daemons after fast reboots
• BootTrigger delay (30s) gives the network stack time to initialize before upstream MCP connections are attempted
• The server.pid file in the user-scope config dir is what 1mcp proxy reads to discover the daemon - this interaction is undocumented for Windows

Proposed solution

Add a ### Windows: Task Scheduler section to the deployment docs (parallel to the existing systemd section), covering:

1. Full Register-ScheduledTask script with recommended flags
2. Key settings explained (RestartOnFailure, BootTrigger delay, MultipleInstancesPolicy)
3. Post-boot verification commands
4. server.pid / Runtime Scope interaction note

Related: #393 (async sub-parameters also undocumented)

[xizhibei]

Thanks for sharing the working setup. We’ll use this to develop and validate Windows guidance that aligns with the built-in runtime supervisor.

[xizhibei]

This was generated by AI during triage.

Triage outcome

This is a valuable documentation gap, but the proposed script should not be copied as-is. Further source tracing changes the earlier preliminary ownership recommendation: Windows Task Scheduler should be the sole supervisor of a foreground 1mcp serve process. Launching serve --background would detach a second supervisor, so Task Scheduler restart settings would no longer monitor the actual long-lived daemon.

Accepted deployment contract

• Run foreground 1mcp serve; do not use serve --background or serve --restart in this deployment model.
• Run as the same least-privileged Windows user that owns the selected Runtime Scope.
• Use password-backed non-interactive task logon with RunLevel Limited. Register the task from elevated PowerShell, prompt for credentials at registration, and never embed the password in a script.
• Do not recommend S4U, InteractiveToken, SYSTEM, Highest privileges, or a VBScript window-hiding wrapper by default. S4U may be documented only as an advanced local-only option with its network and encrypted-file restrictions.
• Use the standalone Windows binary from a stable absolute path as the primary action.
• For npm installations, invoke the generated 1mcp.cmd through cmd.exe as a secondary example. Do not hard-code node.exe or the package-internal build/index.js.
• Pass an explicit --config-dir so the task, status command, PID metadata, and logs share one Runtime Scope.
• Use AtStartup, StartWhenAvailable, MultipleInstances IgnoreNew, unlimited execution time, five restart attempts at two-minute intervals, and battery-tolerant settings.
• Do not gate the task on a Windows network profile and do not add a fixed boot delay by default. A fixed delay may be shown only as an optional domain or VPN workaround.
• Start with Start-ScheduledTask, stop with Stop-ScheduledTask, and restart by stopping then starting the scheduled task. Disable the task first when a stop must survive reboot.
• Observe with 1mcp serve --status --config-dir ..., /health/ready, /health/mcp, Task Scheduler state, and the configured log file.
• Remove --async-min-servers and --async-timeout from examples. Their retirement is specified by Document async loading sub-parameters.
• Keep the English and Chinese documentation aligned.

Microsoft documents that S4U has no network or encrypted-file access, password logon runs non-interactively with supplied credentials, IgnoreNew prevents overlapping task instances, and PT0S removes the default execution limit:

• https://learn.microsoft.com/en-us/windows/win32/api/taskschd/ne-taskschd-task_logon_type
• https://learn.microsoft.com/en-us/powershell/module/scheduledtasks/new-scheduledtasksettingsset?view=windowsserver2025-ps
• https://learn.microsoft.com/en-us/windows/win32/taskschd/tasksettings-executiontimelimit

Required Windows validation

Before publication, validate on a real Windows host:

• standalone binary and npm launch paths
• actual reboot-triggered start
• forced daemon failure followed by scheduler restart
• deliberate scheduler stop without respawn
• IgnoreNew with only one runtime PID
• Runtime Scope status and both health endpoints
• expected log output with no credential leakage

Request for help

@RCrushMe, since you have a working Windows deployment, would you be willing to implement this guide and validation as a pull request? That would be the most useful path. If implementation is not practical, validating a maintainer-authored PR on your Windows host would still unblock this work.

The maintainer does not currently have a Windows PC available, so real Windows verification is the remaining human gate.