AI-Powered
Operations Agent
for Windows Fleets

What it is

A single-binary .NET 9 WinForms app (PeopleWorksAgent.exe) that runs on every host you want to monitor. Installs in seconds, no IIS, no SQL Server, no .NET Framework, no Java. Self-contained.

Two run modes

• Tray mode — interactive, with a notify icon, ideal for workstations or RDP hosts.
• Windows Service mode — background, runs as SYSTEM, survives logouts. Installs from the tray app itself or via the dashboard with UAC elevation.

How it polls

The agent polls /api/{tenant}/tareas/pendientes on a schedule. Adaptive polling ("Modo Receso") slows the cadence when the host is idle to save bandwidth:

active   → 30s
quiet 1m → 60s
quiet 5m → 2m
quiet 15m → 5m
quiet 1h → 10m

A single command from the dashboard wakes the agent back up to 30s immediately.

Self-update

Every heartbeat carries the agent's version. If the server's latest.json says a newer build is available, the agent downloads it, swaps the binary, and restarts — no manual rollout across the fleet.

Stack

ASP.NET Core 9. Single binary, runs on Kestrel standalone, IIS, behind nginx, or in Docker. Your call.

Storage

EF Core with provider-of-your-choice. SQLite for zero-config / single-host setups, SQL Server / PostgreSQL / MySQL for production. Same schema, same migrations, no code changes.

Endpoints

• GET/POST /api/{tenant}/tareas — task management
• GET /api/{tenant}/tareas/pendientes — polled by the agent
• GET/POST /api/clientes — clients (heartbeat, tags, bulk-task)
• GET/POST /api/{tenant}/configuracion — config snapshots, diff
• GET/POST /api/alertas — alerts CRUD, stats, daily summary
• GET/POST /api/playbooks — playbook management
• POST /api/chat — interactive AI chat

Per-client scoping

Every endpoint is scoped by a client ID (in PWA's reference deployment that's the RNC, but the field is just an opaque string for white-label use). Data is logically separated by client — tasks, snapshots, alerts, and metrics all carry the client foreign key. The server enforces rate limits and security headers globally via middleware.

Dashboard hosting

The server also serves the web dashboard from wwwroot/. Auth via PIN middleware for operators; agent endpoints whitelisted via API key.

Fleet at a glance

One view of every host. Online/offline status, last-seen timestamp, agent version, surface vitals (CPU/RAM/disk), pending tasks, recent alerts. Sort, filter, group by tag.

Dispatch tasks in two clicks

Pick a host (or many), pick a tool, fill in parameters, hit go. Track progress in real time. Drill into results with structured viewers — log files in a code reader, processes in a sortable table, registry trees in a navigator.

Config snapshot viewer

For any host, see its config across time: pick two snapshots and the diff tool highlights every change — new processes, removed software, version bumps, disk-space deltas. Catches drift instantly.

Alerts and daily summary

Threshold + change-based alerts. Acknowledge, snooze, or escalate. Daily summary email rolls up the day's signals so you don't have to live in the dashboard.

Operator-friendly

Command palette (Ctrl+Shift+K) for fast actions. Mobile-friendly responsive design. Real-time updates without polling — the dashboard subscribes to heartbeat events server-side.

18 commands

Everything the dashboard does, from your terminal. Perfect for scripting, CI/CD pipelines, ad-hoc ops:

• pwa create <type> --rnc XXX --params '{...}' — dispatch a task
• pwa list / view / cancel — task lifecycle
• pwa schedule "0 6 * * *" --tipo SystemInfo --rnc XXX — cron-recurring
• pwa bulk --tag prod --tipo DiskSpace — fleet-wide
• pwa playbook morning-check --rnc XXX — run a sequence
• pwa chat --rnc XXX — interactive AI session
• pwa diff <snap1> <snap2> — compare snapshots
• pwa alerts / summary / clients / tag

Example session

$ pwa create DiskSpace --rnc CLIENT-001 --priority Alta
Task #1834 queued. ETA: 30s.

$ pwa view 1834
Status: completed
Result: C: 412 GB / 500 GB (82%) — warning threshold 85%

$ pwa schedule "0 */6 * * *" --tipo ConfigSnapshot --rnc CLIENT-001
Scheduled: every 6h. Next run: 2026-05-30 00:00:00.

Pipeable

Output is structured (JSON or table). Pipe into jq, ship to CI, render to whatever. The CLI is a thin client over the REST API — no special privileges, just an API key.

What is MCP?

The Model Context Protocol is Anthropic's open standard for connecting AI assistants to external systems. With PWA's MCP Server, Claude Desktop (or any MCP-compatible client) can read your fleet state and execute operations.

40+ PWA tools exposed

The most-used PWA capabilities are wrapped as MCP tools spread across nine modules (Tareas, Alertas, Clientes, Diagnostico, Playbooks, RemoteControl, Database, FTP, Chat). Each tool is typed with JSON Schema so the LLM knows exactly what it can do.

Dual transport

• STDIO — for Claude Desktop. Launches as a child process via the desktop's claude_desktop_config.json.
• HTTP — for web clients and remote integrations. Same tools, exposed over /mcp.

Auto-discovery

Tools are registered with the [McpServerTool] attribute and discovered automatically via .WithToolsFromAssembly(). Add a new tool by adding a method — no config to touch.

Sample config (Claude Desktop)

{
  "mcpServers": {
    "peopleworks-agent": {
      "command": "PeopleWorksAgent.MCP.exe",
      "args": ["--stdio"],
      "env": {
        "PWA_SERVER": "https://agent.acme.com",
        "PWA_API_KEY": "..."
      }
    }
  }
}

Full cron expressions

Powered by NCrontab. The same 5-field syntax you already know: minute hour day month weekday. Schedule any tool to run on any host, on any cadence.

Examples

# Daily system snapshot at 6am
0 6 * * *  → SystemInfo  → CLIENT-001

# Every 15 minutes, disk check on prod tag
*/15 * * * *  → DiskSpace  → tag:prod

# Weekly playbook every Monday at 5am
0 5 * * 1  → playbook:weekly-audit  → all

Visible and editable

Every recurring task shows up in the dashboard with its next-run timestamp, history, and pass/fail rate. Edit the cron expression or pause the schedule without redeploying anything.

Catch-up vs skip

If the agent was offline when a job was due, the server can either replay it on reconnect or skip the missed window — configurable per schedule.

Built on the same plumbing

A recurring task is just a regular task on a timer. Same execution path, same logs, same audit. Nothing exotic to debug.

What's running today

PWA ships with a set of background watchdog services that continuously evaluate fleet state and fire alerts (and, where safe, remediations) without operator intervention:

• OfflineMonitor — flags agents that miss their heartbeat window and fires an alert with last-seen context
• IncidentCorrelator — groups related alerts arriving close together so operators see one incident instead of N notifications
• Snooze gating — alerts that arrive during a planned snooze window persist auto-resolved with explanatory notes, no noise to operators
• Per-client cooldowns — alert dedup by (host, rule) so a flapping condition fires once, not a thousand times

Domain-specific watchdogs

Specific monitoring services target known patterns we operate against in production — for example, an NCF Sequencer watchdog tracks ranges of electronic invoice number sequences across the ERP fleet and alerts when a client is approaching exhaustion.

Remediation today

The agent's tools can be invoked directly from alerts (or from chat, or from playbooks) — TempCleaner, MemoryOptimizer, ErpGuardian, restart-service via PowerShell — so the "fix-on-trigger" pattern is feasible by chaining alert → playbook. Full configurable threshold→action rules are on the roadmap.

Audit trail

Every mutating action — taken by an operator, by chat AI, or by a service — is logged with the trigger, the action, the result, and the actor. Forensics are first-class, not bolted on.

Chains of tools

A playbook is an ordered sequence of tool invocations. Each step can pass data to the next, branch on the previous result, or short-circuit on failure. Think CI pipeline, but for ops on Windows hosts.

Built-in playbooks

• Morning health check — system_info → disk_space → top_processes → event_log → summary
• Pre-update audit — snapshot config → list running services → ensure backups exist
• Incident snapshot — collect logs + processes + memory + recent event log in one ZIP
• Disk emergency — disk_space → temp_cleaner → recheck → alert if still high

Bring your own

Playbooks are JSON. Author them in the dashboard's visual editor or check them into your repo and POST them via the API. Either way, they live with the rest of your tenant config.

Run anywhere

Same playbook works from the dashboard ("Run on this host"), the CLI (pwa playbook morning-check --rnc XXX), the watchdog (as a remediation), or the AI chat ("run morning check on prod").

What gets captured

A snapshot is a structured JSON document with everything that matters about the host's state:

• OS version, install date, last boot
• CPU model, core count, RAM total/free, disk layout
• Installed software with versions (filtered to what you care about)
• Running services and their status
• ODBC drivers and DSNs (32/64-bit)
• Selected registry keys
• Critical app versions (e.g., the ERP binary's FileVersion)
• Local DB connections + health

When it runs

• Scheduled — every 6h by default (configurable)
• On change — FileSystemWatcher on critical binaries triggers an immediate snapshot when they're swapped
• On demand — "Refresh config now" button in the dashboard, or pwa create RefreshConfigSnapshot

Diff viewer

Pick any two snapshots — from one host across time, or from two hosts at the same time — and see structured differences highlighted. New software in green, removed in red, version bumps in amber. Spot a misconfigured workstation in seconds.

Use cases

• Post-deploy verification: did the update actually land on all hosts?
• Drift detection: which workstation is behind the fleet?
• Incident forensics: what changed before the issue started?

OpenAI-compatible chat backend

The dashboard's chat uses an OpenAI-compatible chat-completions endpoint configured at the server level (model + base URL + auth token, all in appsettings.json). Swap providers by changing the config — the rest of the pipeline doesn't care whether you're pointed at OpenAI, Azure OpenAI, an internal endpoint, or a self-hosted model.

Per-client context, auto-injected

When you start a chat scoped to a host, the AI receives the host's recent snapshot, recent alerts, recent task results, and tags as system context. You don't have to paste anything — the AI already knows the situation.

Tool-using mid-conversation

The AI doesn't just chat. It can dispatch tools live. Ask "why is CLIENT-23 slow this morning?" and it'll pull CPU, memory, top processes, then reason over fresh data. Mutating tools (create task, resolve alerts, rename client) are audited in a dedicated table so every action the model takes leaves a trace.

Two surfaces

• CLI — pwa chat --rnc CLIENT-001, full-terminal session, scriptable
• Dashboard — drawer-style chat panel on every host page

Conversation persistence

Chats are persisted server-side. Pick up where you left off, share threads with teammates, or audit what was discussed and what tools were invoked via the ChatAuditoria table.

Multi-tag per host

Each host can carry any number of tags. Tag by environment (prod, staging, dev), by customer (acme-corp), by region (dr-north), by role (file-server, terminal), or by anything custom you care about.

Computed status (alongside manual tags)

In addition to the tags you assign, every client surfaces computed state derived from its latest heartbeat — online / offline, last-seen, agent version, snooze status. The dashboard combines manual tags and computed state in the same filtering UI.

Bulk dispatch

Once your fleet is tagged, you stop thinking host-by-host. Run pwa bulk --tag prod --tipo SqlServerHealth and the task fans out across all prod hosts. Track per-host progress in real time.

Tag-level analytics

The dashboard rolls up metrics by tag: "how many prod hosts are below 90% healthy", "alert rate by region", "version distribution by customer". You get fleet-level insight without leaving the operator UI.

Four supported backends

• SQLite — zero-config, single-file. Perfect for getting started, demos, or single-tenant production. No service to install.
• SQL Server — Express, Standard, Enterprise, or Azure SQL. Plays nice with existing Microsoft shops.
• PostgreSQL — 12+. Open source, scales horizontally if you need it.
• MySQL — 8.0+. Same.

Same schema across all four

EF Core abstracts the differences. The migrations apply automatically on startup. Switching backends is a connection-string change.

Why this matters

White-label customers and on-prem deployments rarely look like one another. Letting them pick the DB they already operate removes a procurement battle. PWA shows up, fits in.

Connection string examples

# SQLite (default)
"Data Source=pwa.db"

# SQL Server
"Server=.;Database=PWA;Trusted_Connection=True;TrustServerCertificate=True"

# PostgreSQL
"Host=db.local;Database=pwa;Username=pwa;Password=..."

# MySQL
"Server=db.local;Database=pwa;Uid=pwa;Pwd=..."

What's brandable today

• Logo and favicon — replace the SVG assets, no rebuild required
• Product name and tagline — text edits in the dashboard template
• Color palette — primary, accent, and dark gradient applied via CSS variables
• Footer text and legal links — yours to control
• Custom domain — point your DNS at your server instance; SSL is your hosting decision
• Tray app banner — what shows up in the notification area on the end customer's machine

Custom tools via the plugin pattern

Need a domain-specific tool to ship with your build? Implement IAgentTool in a class library, register it in DI, and it shows up everywhere — dashboard, CLI, MCP. No fork required, no protocol to learn.

Deployment model

White-label customers typically run their own PWA Server instance — on-prem, in their cloud account, or in a managed environment. That means each operator gets their own database, their own SMTP endpoint, their own Telegram bot, their own AI provider configuration. Full data path control without per-tenant gymnastics in the product.

What's not in scope today

A few things often associated with "white-label" are not built into PWA itself: per-brand email templates with localized strings, programmatic theme switching at runtime, and operator-vs-end-customer surface separation within the same instance. White-label deployments handle these by running their own server, not by configuration toggles.

Three targeting modes

• By tag — --tag prod hits every host carrying that tag
• Specific hosts — --rnc CLIENT-001,CLIENT-007 picks an explicit list
• Fleet-wide — --all dispatches to every connected agent

Real-time progress, per host

The dashboard shows a live grid: each host as a tile, each tile lighting up as the task starts, runs, and completes. Click any tile to drill into its result without leaving the bulk view.

Failure handling

One host failing doesn't block the rest. The grid surfaces failures with the error message, and you can retry just the failed ones with one click — no need to re-dispatch the whole batch.

Common use cases

• Fleet-wide audits (SqlServerHealth, InstalledSoftware)
• Rolling cleanups (TempCleaner across all workstations)
• Mass version checks before a rollout
• Pushing a config file to every host in a region
• Incident sweeps: "collect logs from every prod host right now"

CLI example

# Disk-space check across all production hosts
pwa bulk --tag prod --tipo DiskSpace

# Refresh config snapshot on a specific customer's hosts
pwa bulk --tag customer:acme --tipo RefreshConfigSnapshot

# Emergency cleanup, fleet-wide
pwa bulk --all --tipo TempCleaner --priority Alta

Three trigger types

• Threshold — disk > 90%, CPU > 85% sustained 5m, free RAM < 500 MB
• Change-based — config snapshot diff detected, software version regression, service removed
• Pattern — log line matched, event log code N times in window

Delivery channels

• Email — direct + daily digest rollup
• Telegram — per-tenant bot, with inline action buttons
• Webhook — POST JSON to your own endpoint (Slack, Teams, PagerDuty, your own incident system)
• Dashboard — always, with operator acknowledgment

Per-tenant cooldowns

Every (host, rule) pair has a cooldown window. A flapping disk-usage condition won't dump 200 alerts in your inbox overnight — it fires once, then stays quiet until the cooldown clears.

Daily summary

One email per day per operator with everything that fired in the last 24h, grouped by severity and by host. Skip the noise during the day, get the full picture at 8am.

Operator workflow

Alerts have lifecycle: fired → acknowledged → resolved. Snooze for N hours, escalate to another operator, or attach a remediation note. Full audit trail per alert.

The problem with fixed polling

A 30-second poll feels snappy for the operator, but it's wasteful when nothing's happening. A 5-minute poll saves bandwidth but feels sluggish when you actually want a task to run. You shouldn't have to pick.

The cadence ladder

The agent starts at 30 seconds. After each empty poll (no pending tasks), it steps down the ladder:

active       →   30s
quiet 1 min  →   60s
quiet 5 min  →    2m
quiet 15 min →    5m
quiet 1 hour →   10m

Any incoming task — dispatched manually, by playbook, or by watchdog — wakes the agent back up to 30s instantly.

Bandwidth math

An idle host on fixed 30s polling sends ~120 empty pings per hour. On adaptive polling, the same host sends ~6. For a fleet of 1000 hosts, that's the difference between ~50 MB/hour and ~2 MB/hour of backend traffic.

Per-tenant tuning

The default cadence is sensible, but every step is configurable per tenant. Some customers want 15s/30s/60s for super-responsive ops; others want 60s/5m/30m for low-bandwidth sites.

How it works

Every heartbeat carries the agent's version. The server compares it against latest.json. If a newer build is available and the host's tags match the rollout policy, the agent pulls the new binary, swaps itself out, and restarts.

Staged rollout

You don't have to update everyone at once. Tag a few canary hosts as canary, point the rollout policy at that tag, watch it bake for 24h. If nothing breaks, widen to prod. Standard blue/green logic — but for agents.

Self-rollback on startup failure

Before swapping, the agent keeps a copy of the previous binary. If the new one fails to start within N seconds, it rolls back automatically. The dashboard surfaces failed updates so you can investigate without losing the host.

The publish flow

1. Build a new single-file agent with publish-all.cmd
2. Drop the EXE into the server's updates/ folder
3. Bump version in latest.json
4. Optionally set tag-based gating
5. Agents update on their next heartbeat

No agent left behind

The dashboard shows version distribution across the fleet at a glance. Stragglers (offline at rollout time) update the moment they reconnect — no manual chasing.

What the heartbeat carries

A small JSON payload every 60 seconds:

• Agent version + uptime
• OS, machine GUID, local IP
• Surface vitals (CPU%, free RAM, free disk)
• Active RDP sessions (count + usernames)
• Pending task count (so the server can wake polling if needed)

Online / offline detection

The server flags a host offline after 3 missed heartbeats (~3 min by default). Dashboard turns the indicator red, watchdog can fire an alert, recovery is automatic when the heartbeat resumes.

Server-side event triggers

Heartbeats aren't just data — they're triggers. The server can use them to fire alerts on "host came online unexpectedly", "version regression detected", "vitals crossed threshold", or anything you can express as a rule against the heartbeat stream.

Why not just polling?

Polling tells you "the agent is alive enough to ask for work". Heartbeats tell you "and here's what's happening on the host right now" — without the operator needing to dispatch a task. Two different signals, both cheap.

On-demand, no preinstall

You don't pre-install VNC on every host. The first time you need to see what's happening on a workstation, click "Start Remote View" in the dashboard. The agent fetches a portable TightVNC build, starts it on a randomized port, and the server tunnels you in. When you close, it stops and uninstalls — no leftover surface.

Time-limited sessions

Every session has a configurable lifetime (default 30 minutes). When it expires, the VNC server stops, the port closes, the dashboard logs the session end. No "I'll just leave this open" risk.

Auditable

Every VNC session is logged with operator identity, host, start time, end time, and reason (optional free-text). If your compliance regime asks "who looked at CLIENT-007's screen on Tuesday?", the answer is in the audit log.

Built for support, not surveillance

The end user on the host sees a clear notification when a session starts, with the operator's name. There's no covert viewing — this is meant for support engagements, not for watching people work.

Alternative for read-only

If you just need a screenshot, not a live session, use the capture_screen tool. It returns a PNG of the current desktop without opening a remote channel — much lighter touch.

Per-client settings on every host

• Identification — display name, hostname, OS version, agent version, host GUID
• Tags — comma-separated, used for grouping and bulk dispatch
• Email destination — for the per-client daily digest (separate from operator-level alerts)
• Location — latitude/longitude + city, populated automatically via GeoIP and overridable manually for the map view
• Snooze window — until-timestamp + reason for scheduled maintenance, so alerts during a planned backup don't reach operators
• Support flag — marks internal consultant laptops so they can be filtered out of customer-facing metrics
• Linked-to host — explicit operator-declared link between two clients that share a physical machine, so an orphan client inherits the parent's vitals
• VNC session credentials — short-lived password + port + IPs, rotated automatically with every remote-view session

How auth actually works

Each agent authenticates to the server with its client key (the RNC in PWA's reference deployment). The server validates the key against the registered clients table on every request — keys are scoped per-client, leaking one doesn't open the rest of the fleet.

Operator vs agent surfaces

Two layers of access: agents authenticate by client key on the public API, operators authenticate to the dashboard via PIN behind a middleware that whitelists agent endpoints.

Shared services (server-level)

Things like the SMTP server, the Telegram bot, and the AI Copilot endpoint are configured once at the server level and shared across the fleet. White-label deployments typically run their own server instance, so each operator gets their own set of these regardless.