Stoker Documentation

Everything you need to go from installer to monitored fleet. Most installs take about five minutes end to end.

Quick start

1. Double-click Stoker-Hub-<version>-win-x64.msi on the machine that will run the dashboard. The wizard walks you through the install location and settings (port and firewall rule).
2. Open http://<that-machine>:5210 and create the admin password.
3. Go to Settings → Agent keys, click Generate, and copy the key (it is shown exactly once).
4. On each machine to monitor: double-click Stoker-Agent-<version>-win-x64.msi. The wizard asks for the hub URL, API key and a display name.
5. The machine appears on the dashboard within ~15 seconds. Click configure rules → on its card and pick the services to watch.

Installing the hub

The hub is a single self-contained Windows service with an embedded web dashboard and SQLite database, with nothing else to install. It ships as an MSI installer (double-click for the wizard, or push silently across a fleet) with a zipped scripted install for people who prefer PowerShell.

MSI installer (recommended)

Double-click Stoker-Hub-<version>-win-x64.msi and walk through the wizard: Welcome → Install location → Settings → Ready → Install. The Settings page picks the port (default 5210) and whether to open the firewall.

The installer creates the StokerHub Windows service with crash-restart recovery and stores data in C:\ProgramData\Stoker, so upgrades and reinstalls never touch it. Upgrading: run the newer MSI over the old one; the database, your settings and any HTTPS configuration all carry over untouched.

Silent and fleet install

For GPO, Intune, SCCM or an RMM tool, every setting is an MSI property so one command line configures and starts the service:

# Default install (port 5210, adds the firewall rule)
msiexec /i Stoker-Hub.msi /qn

# Custom port and data directory
msiexec /i Stoker-Hub.msi /qn PORT=8080 DATADIR="D:\StokerData"

# HTTPS direct from a machine-store certificate (drops the plain-HTTP endpoint)
msiexec /i Stoker-Hub.msi /qn CERTSUBJECT=stoker.company.local

# Behind a reverse proxy: trust it, and skip the public firewall rule
msiexec /i Stoker-Hub.msi /qn REVERSEPROXY=true KNOWNPROXIES=127.0.0.1 ADDFIREWALLRULE=0

Full property list: PORT, DATADIR, CERTSUBJECT, REVERSEPROXY, KNOWNPROXIES, ADDFIREWALLRULE (1 or 0), OFFLINEAFTER, METRICRETENTION.

Scripted install (zip)

Prefer PowerShell? Grab the zip download instead of the MSI and run:

.\install-hub.ps1              # defaults: Program Files, port 5210
.\install-hub.ps1 -Port 8080   # custom port (the firewall prompt follows it)

Same end result: the StokerHub service, data in C:\ProgramData\Stoker, a prompt before adding the firewall rule (pass -NoFirewallRule to skip). Handy if you are already managing servers with PowerShell and want the config in a repo. To upgrade, unzip the new version and run the script again.

Lost admin password

Stoker.Hub.exe --reset-admin-password

Run on the hub server itself (console access is the trust boundary), then reload the dashboard and create a new password. Data is unaffected.

Installing agents

One agent per monitored machine, and a machine is any 64-bit Windows box: a server, a desktop, a laptop, a VM, a kiosk or a till. Agents connect outbound to the hub and pull their rules over that same connection, so monitored machines never open a port and the hub never initiates a connection to them.

MSI installer (recommended)

Double-click Stoker-Agent-<version>-win-x64.msi. The wizard asks for the hub URL, API key and a display name (defaults to the computer name), then installs and starts the agent service. The agent runs as LocalSystem so it can restart the services it watches. Upgrades preserve the agent's key, name and local rules; run the newer MSI over the old one.

Silent and fleet install

For GPO, Intune, SCCM or an RMM tool, every value is an MSI property so one command line configures and starts it:

msiexec /i Stoker-Agent.msi /qn HUBURL=https://hub.company.com APIKEY=stk_xxxx AGENTNAME="%COMPUTERNAME%"

Properties: HUBURL, APIKEY, AGENTNAME (blank uses the computer name), TRUSTCERT (set true only for self-signed labs).

Scripted install (zip)

Prefer PowerShell? Grab the zip and run:

.\install-agent.ps1 -HubUrl http://hub:5210 -ApiKey stk_... -AgentName "DC-01 (rack 3)"

Anything omitted is prompted for. Same end result as the MSI: the StokerAgent service, running as LocalSystem, configured with the values you passed.

Service rules

Rules are configured from the dashboard: open a machine's card → configure rules →. The service picker lists what is actually installed on that machine, so there are no name typos. Saved rules reach the agent within one report cycle (~15s), apply live, and are cached on the agent so they survive reboots even if the hub is down.

Hub-managed vs. local rules. The moment you save rules for a machine here, it becomes hub-managed and the dashboard is the source of truth for it. Until then, or after you click Stop managing from the hub, the agent runs whatever is set on the machine itself (the Agent:Services list in its appsettings.json), which is handy for air-gapped machines you configure by hand. Hub-managed rules always take priority while they are set, and the last set is cached on the agent so it keeps enforcing them even if the hub is unreachable.

Uptime checks

Settings → HTTP checks. Checks run from the hub on their own interval; changes apply within a second. Each check validates HTTP status (any 2xx, or an exact code you specify), optionally requires a keyword in the response body, records latency, and for HTTPS warns ahead of TLS certificate expiry.

Alerts

Settings → Alerts. Choose a minimum severity (Info / Warning / Critical) and one or both channels:

• Webhook: POSTs JSON per alert, including a text field that renders out of the box in Slack/Discord-compatible receivers.
• Email (SMTP): standard SMTP with optional auth and SSL.

Resolution notifications are on by default: when a check recovers or an agent comes back online after a down/offline alert, Stoker sends a paired follow-up so on-call knows to stand down instead of hunting a problem that self-healed. Untick Send a resolution notification when a check or agent recovers on the Alerts tab to keep recoveries silent.

The Send test alert button verifies your channel without waiting for a real incident.

Maintenance windows

Settings → Maintenance. A window is a period when a set of machines is expected to be disrupted. While one is open Stoker holds those machines' notifications and, if you leave the box ticked, tells their agents to stop auto-restarting services — so a patch run that deliberately stops something is not fought by the agent. Nothing stops being recorded: the event log fills in as usual, and the results page below is built from it.

Scope

• All machines — for hub upgrades or work that touches everything.
• One machine — also what the pause monitoring link on a machine's card creates, so an ad-hoc pause shows up in the same list as anything scheduled.
• A tag — every machine carrying a label such as client:northgate, site:hq or role:sql. Set tags on a machine's card, in bulk, or ship them in the agent's own appsettings.json under Agent:Tags so a per-client installer arrives already grouped. Tags from an agent are merged, never removed, so an agent can't drop a tag a window depends on.

Schedule

One time, daily, weekly on chosen days, monthly on a date, or monthly on a weekday. The last one takes a "plus N days" offset, which is how you express the day after Patch Tuesday (2nd Tuesday + 1). Each window carries its own time zone and occurrences resolve in it, so 03:00 stays 03:00 across daylight-saving changes. The editor shows the schedule back to you in plain English before you save, and the list shows the next run.

An open window can be extended from the dashboard banner (+30 min). Windows never extend themselves: one that did would never close.

What stays noisy

Disk alerts keep firing through a window unless you tick Mute disk alerts too — a volume filling up during a patch run is exactly when you want to know. HTTP checks are defined by a URL, so the hub can't tell which machine a URL lives on: set Served by on the check and it goes quiet with that machine. Left unset, a check keeps alerting through every window.

Checking the machines came back

This is the part that matters. When a window opens, Stoker records every service running on each covered machine — anything it monitors, plus anything set to Automatic start. When the window closes, and after a short grace period for boot (10 minutes by default), it checks them all again and raises one Critical alert per machine naming whatever did not come back.

Delayed-auto-start services are deliberately left out of that check: Windows starts a good number of those on demand and stops them again, and a check that cries wolf is one you switch off. If something on your estate legitimately stops itself after a reboot, add it to Never flag these services on the same tab.

The Maintenance page (top nav) shows each window's results: which machines went down, when, for how long, what returned and what didn't, with CSV export and a printable view.

Triggering a window from your patching tool

Patch runs slip, so the agent takes local commands intended as the pre- and post-flight steps of whatever tool you already run:

& "C:\Program Files\Stoker Agent\Stoker.Agent.exe" maintenance start --minutes 120
& "C:\Program Files\Stoker Agent\Stoker.Agent.exe" maintenance stop

These work with the hub unreachable, which during a site-wide patch run it often is. The agent also keeps its window across a reboot, so a machine that restarts mid-window comes back already paused rather than restarting services for the first minute. The hub mirrors a locally-declared window so alerts are muted centrally as well.

Give the hub its own window too, staggered from the rest, or it will be offline for the run it is supposed to be watching.

Events

Everything notable (restarts, breaches, breaker trips, agents going offline, checks going down, config changes) lands in the event history (Events in the header): filter by severity, search text, page through history, export CSV. Retention is configurable (Settings → General, default 90 days).

Licensing

Every install starts a 30-day full-featured trial. Afterwards the hub falls back to the free tier (1 machine) unless a license key is activated under Settings → License.

Keys are cryptographically signed and verified offline: no phone-home, air-gapped friendly. If a license expires, monitoring never stops: existing machines keep being watched and alerted on; only registering new machines beyond your tier is blocked.

Tiers and prices are on the pricing section.

Security

• The dashboard and API require signing in with the admin password you set on first launch.
• Agent keys are stored hashed and can be revoked instantly from the dashboard.
• Agents connect outbound-only and pull their configuration over that connection; monitored machines open no ports and the hub never connects to them. The hub machine itself opens one inbound port (the installer asks first).
• For any non-trusted network, put the hub on HTTPS; see HTTPS / TLS below for both ways to do it. Agents accept https:// hub URLs; TrustAnyCertificate exists for self-signed lab setups only.
• No telemetry. The only outbound call the hub can make is the optional update check (off by default); leave it off and nothing leaves your network.

HTTPS / TLS

Hub traffic is plain HTTP until you add TLS. The setup worth doing is a certificate from a CA your servers already trust, so agents validate the full chain; never ship self-signed plus TrustAnyCertificate outside a lab, because that turns certificate validation off. There are two supported ways.

Direct: the hub serves HTTPS itself

Best for an internal hub. Import your certificate into the machine store (certlm.msc → Personal → Import), then install with:

.\install-hub.ps1 -CertSubject stoker.company.local

To configure it by hand, remove the "Urls" line from appsettings.json and add:

"Kestrel": {
  "Endpoints": {
    "Https": {
      "Url": "https://*:5210",
      "Certificate": { "Subject": "stoker.company.local", "Store": "My", "Location": "LocalMachine", "AllowInvalid": false }
    }
  }
}

The StokerHub service account needs read access to the certificate's private key: certlm.msc → the cert → All Tasks → Manage Private Keys.

If your certificate is a .pfx file instead (a purchased wildcard, say), point Kestrel at it directly:

"Kestrel": {
  "Endpoints": {
    "Https": {
      "Url": "https://*:5210",
      "Certificate": { "Path": "C:\\ProgramData\\Stoker\\your-cert.pfx", "Password": "..." }
    }
  }
}

Reverse proxy: a public hostname with auto-renewing certificates

Best when you want a proper name like stoker.company.com and a certificate that renews itself. The idea is the same whichever proxy you pick: the proxy holds the certificate and answers HTTPS on the public side, and forwards each request to the hub, which stays on plain HTTP on localhost:5210 behind it. The hub keeps running as its own Windows service. The proxy never hosts it; it only passes traffic through.

One setting on the hub side applies to both options. Tell the hub to trust the proxy's forwarded headers, so it knows the request really arrived over HTTPS and can see the visitor's real IP address for the login lockout. In appsettings.json:

"Hub": {
  "ReverseProxy": { "Enabled": true, "KnownProxies": [ "127.0.0.1" ] }
}

KnownProxies lists the proxy's own address. Use 127.0.0.1 when the proxy runs on the same machine as the hub, which is the usual case. Leave Enabled set to false when nothing sits in front of the hub, otherwise a visitor could fake those headers. Restart the StokerHub service after editing the file.

Option A: Caddy (the simplest path)

Caddy is a single small program that gets and renews its certificate for you, with no ceremony. Point your hostname's DNS at the hub machine, download Caddy, and create a file called Caddyfile next to it with just these lines:

stoker.company.com {
    reverse_proxy localhost:5210
}

Run caddy run to try it, or caddy start to leave it running (Caddy can also install itself as a Windows service). It fetches a free Let's Encrypt certificate the first time and renews it automatically forever after. Allow ports 80 and 443 inbound on the hub machine, and there's nothing else to configure.

Option B: IIS, step by step

Use this if IIS is already your standard. IIS does not run the hub; it forwards HTTPS traffic to the hub service on port 5210. You need two free Microsoft add-ons for IIS, URL Rewrite and Application Request Routing (ARR), then these steps once:

1. Install the two modules. Download and run the installers for URL Rewrite and Application Request Routing from Microsoft, then close and reopen IIS Manager.
2. Turn proxying on. In IIS Manager, click the top server node in the left tree, open Application Request Routing Cache, click Server Proxy Settings… on the right, tick Enable proxy, and click Apply. (This is the step everyone forgets; without it you get a blank "page can't be displayed".)
3. Create the site. Right-click Sites → Add Website. Give it any name; set Physical path to a new empty folder (IIS serves no files here, it only forwards); set Host name to your public name, e.g. stoker.company.com; leave it on HTTP port 80 for now. Make sure that hostname's DNS points at this machine.
4. Get the certificate. Download and run win-acme (wacs.exe). Choose N for a new certificate, pick your site from the list, and it validates the domain, installs a free Let's Encrypt certificate, adds the HTTPS (port 443) binding to the site, and schedules automatic renewal.
5. Add the forwarding rule. Select the site, open URL Rewrite, and either add a blank inbound rule (match (.*), action Rewrite to http://localhost:5210/{R:1}, append query string), or simply drop this web.config into the site folder:

   <configuration>
     <system.webServer>
       <rewrite>
         <rules>
           <rule name="Stoker hub" stopProcessing="true">
             <match url="(.*)" />
             <action type="Rewrite" url="http://localhost:5210/{R:1}" />
           </rule>
         </rules>
       </rewrite>
     </system.webServer>
   </configuration>

6. Trust the proxy. Apply the ReverseProxy setting shown above and restart the StokerHub service.
7. Open the firewall for ports 80 and 443 inbound, then browse to https://stoker.company.com. You can now close port 5210 to the outside world.

Pointing agents at an HTTPS hub

Set each agent's Agent:HubUrl to the same https://… name your certificate covers, for example https://stoker.company.com (no :5210 when the proxy answers on the standard 443). With a wildcard certificate for *.example.com, agents must use a name under it like https://something.example.com, not an IP or bare machine name. As long as the certificate chains to a CA the machines already trust (a public CA, or your internal CA via Group Policy), that's the only change needed and TrustAnyCertificate stays off.

Troubleshooting

A machine never appears on the dashboard

• Check the agent service is running: Get-Service StokerAgent.
• Verify HubUrl is reachable from that machine (curl http://hub:5210/api/auth/status).
• Confirm the API key wasn't revoked (Settings → Agent keys); a rejected agent logs "Hub rejected snapshot: Unauthorized".
• Free tier / expired license? New machines beyond your tier are declined (an event on the hub says so).

"Failed to restart … permission" events

The agent needs rights to control the services it watches; the installer's LocalSystem default has them. If you changed the service account, use one with service-control rights.

A service shows "Tripped"

The circuit breaker engaged: too many restarts within an hour. Investigate the service (its own logs, Windows Event Viewer); automation resumes when the hour window clears.

"install-hub.ps1 is not digitally signed"

Files downloaded from the internet carry a Windows "Mark of the Web", and execution policies like RemoteSigned then refuse to run the scripts inside the zip. Fix it one of three ways:

• Before extracting: right-click the downloaded zip → Properties → tick Unblock → OK, then extract. This unblocks everything inside at once.
• Already extracted: in the folder, run Get-ChildItem -Recurse | Unblock-File from PowerShell.
• Single file: right-click the script → Properties → Unblock.

Dashboard looks broken after an upgrade

Hard-refresh once (Ctrl+F5); your browser cached the previous stylesheet.