Probe agent documentation

Introduction

The Huntertech Probe is a lightweight Windows agent that runs HTTP checks from your network: office, home lab, customer site, or any host where you need the same vantage as users and apps. Results roll up to Huntertech Monitoring so you can chart latency, compare monitors, and backfill from edge storage when cloud gaps appear.

Policy lives in the cloud. The agent enrolls once, syncs which monitors it should run, executes checks locally, and uploads observations and health. It does not embed alert rules beyond the schedule intervals supplied in policy.

Requirements

• Plan: Pro, Enterprise, or VIP (probe agent access). Free and Standard do not include agents.
• Agent limits: Pro includes up to 2 active agents; Enterprise and VIP include up to 10. Revoked agents free a slot.
• Platform: Windows for production installs (per-user or all-users). Linux is supported for development via npm run probe:run.
• Network: Outbound HTTPS to Huntertech for enroll, policy sync, observations, health, logs, and updates.

Quick start

1. Download huntertech-probe-<version>-windows.zip from the probe overview or Account → Probes.
2. Extract the archive on the Windows host and run the installer (see Installation).
3. In Account → Probes, click Generate pairing code and enter it on the host before it expires.
4. Assign one or more HTTP monitors to that agent (Manage on the agent card).
5. Open Account → Monitoring to confirm rollups and probe-assigned checks.

Installation

The default install matches common SaaS agents (Slack, Teams, VS Code user setup): binaries and updates under the user profile, started by a logon scheduled task, with no Administrator prompt.

# Per-user (default): no Administrator required
.\install.ps1

# All users / Program Files: elevated PowerShell
.\install.ps1 -AllUsers

Secrets on disk

After enrollment, the agent stores its token in config.json beside the binary with restrictive permissions (mode 0600). Treat the install folder like any endpoint credential store.

Enrollment

Pairing codes are short-lived (about 15 minutes). Create them only while signed in to your Huntertech account. Each code is shown once; the server stores a hash. Successful enrollment returns an agent token (htp_live_*) used on all subsequent agent API calls.

# After install, enroll with a pairing code from Account → Probes
huntertech-probe enroll --code XXXX-XXXX

Monitors and policy

Only monitors explicitly assigned to an agent appear in that agent's policy document. Enable or disable checks in Monitoring; assignment is per agent under Account → Probes → Manage.

HTTP check types

Probes run the same HTTP request adapter as cloud checks: method, URL, headers, body, success criteria, and timeout from the monitor definition.

Connection profiles (Cold / Warm)

• Cold (standard): Measures a typical one-shot request (connection setup included in timing).
• Warm (steady): Reuses a connection pool where possible for warm-path latency on repeat intervals.

Use compare in Monitoring to overlay multiple HTTP monitors, including probes at different sites, on one chart with a shareable URL.

Telemetry and retention

Observations from the probe are tagged with source agent on the server. Rollups feed the same monitor detail charts as cloud-origin checks, with an indicator of which probe last ran the check.

When cloud hot data has a gap, use Sync history from probe on monitor detail to backfill from local telemetry.db (edge retention about 30 days).

Storage planning

Local telemetry.db holds rollup history for about 30 days on the probe PC. Growth is driven by how many HTTP monitors are assigned to the agent and how often each monitor runs (check interval). More monitors or shorter intervals mean more checks, more rollup rows, and faster disk use.

After a rollup uploads successfully, the agent strips per-check samples and keeps compact aggregates on disk for backfill. Planning numbers below use that steady-state edge encoding (~5s rollup flush windows). Pending upload backlog during ingest outages can temporarily inflate telemetry.db until the queue drains.

• Monitor count: each assigned monitor contributes its own rollup stream.
• Polling interval: 1s monitors fill every flush window; 60s monitors write about one rollup row per check.
• HTTP path context (cold/warm RTT, edge headers) adds a small amount per row when enabled.
• Health replay snapshots (when ingest is down) are capped separately from rollup history.
• Account → Probes shows telemetry.db size with linear per-minute, hour, day, month, and year estimates from recent heartbeats on enrolled agents.

Estimated telemetry.db growth (steady state)

Linear growth if monitor count and intervals stay constant. The ~30d cap column is the approximate disk footprint after edge retention fills (~30 days of rollup rows at the same rate; older windows are purged).

Auto-update and recovery

Enrolled agents poll the release endpoint about every 10 seconds, compare version and SHA-256, and download artifacts through the probe API (not static CDN paths that may be blocked). With immediate apply mode, the agent stages under the local updates folder, applies, and relaunches.

Rollback (1.0.19+)

• Before apply, the current install is copied to a rollback backup folder.
• The new build must stay up for about 60 seconds or post a successful health before the backup is deleted.
• If startup fails, run.cmd invokes recovery and retries once. Failed semver builds are blocked from reinstall until a newer release ships.

Account → Probes surfaces update state: available, downloading, applying, or staged. Full semver notes live on Release notes.

Health and alerts

About every 30 seconds the agent POSTs health: uptime, check success/failure counts, sync and upload timestamps, queue depth, assigned monitor backlog, and resource samples (memory, CPU, disk).

• Offline: No heartbeat for roughly 3 minutes triggers an offline alert path.
• Degraded: Heartbeat errors, sustained upload catch-up or backlog pressure, or clock skew of 300 seconds or more.
• Stale ingest: Monitor assigned to an online probe but no observation accepted for about 15 minutes.

Failed health posts while Huntertech is unreachable are buffered locally and replayed on the next success so playback charts preserve timestamps.

Performance and resources

The probe is a single long-running Node process on the host. It is designed for always-on office and lab PCs: modest baseline CPU, predictable memory, and health telemetry so you can see impact in Account → Probes without installing a separate APM agent.

What we report

About every 30 seconds the agent samples process metrics and POSTs them on /agents/me/health. The server stores throttled samples (~30 minutes) for sparklines and playback on each agent card.

Measured benchmarks (agent 1.0.60)

Recorded 2026-10-22 on Linux x64, 20 logical CPUs, 64 GB RAM. Production HTTP check adapter, loopback targets, 120s measure window (20s warmup) for policy-realistic rows. CPU avg is the mean over the full run; p95 uses ~1s samples (same normalization as health). Enrolled agents add telemetry.db and upload work; RSS on Windows is typically higher than this Linux harness.

Raw JSON and methodology: docs/performance/probe-resource-benchmark.json. Re-run locally with npm run benchmark:probe-resources.

Other load factors

Planning monitors on the host

• Interval: Shorter checkIntervalSec increases checks per minute linearly. Prefer 60s or higher for many URLs unless you need sub-minute LAN visibility.
• Warm vs cold: Warm profiles reuse TLS/TCP where safe; slightly higher steady RSS, lower per-check setup cost. Cold profiles suit one-shot latency that includes connection setup.
• Concurrency: The scheduler runs due monitors from policy; large assignments on one agent share one process. Split heavy sites across multiple agents if you need isolation.
• Disk: Edge telemetry retains about 30 days locally. High-frequency monitors on a small system drive are the main disk growth lever besides update staging.

When numbers look wrong

Host CPU topology (packages, physical cores, logical processors, model name) is included on health for context on the agent system card. Use playback charts to correlate spikes with update state, upload backlog fields, or check failure counts on the same timeline.

Standard user capabilities

The default per-user install uses normal HTTP/TLS, local disk, and scheduled tasks. No raw sockets are required for the capabilities below.

Path trace and elevation

Forward traceroute-style measurements require sending probes with increasing TTL and reading ICMP errors. A normal HTTP client cannot perform that work.

What elevated means

• Running install.ps1 -AllUsers from an Administrator PowerShell session, or
• Installing a future optional trace helper (Windows service or companion) for raw-socket work only.

• Standard install: slow ICMP-only path snapshots. If ICMP is blocked, rely on HTTP path context and egress.
• With elevated helper: ICMP, UDP, and TCP traces; hop list uploaded as forward path from this probe (not reverse path).
• Program Files (-AllUsers) does not by itself grant raw sockets. Privilege comes from how the trace process runs.

Feature matrix

When path trace ships, release notes and Account → Probes will label the active mode: user-icmp, helper-full, or disabled.

Troubleshooting

Related resources

• Probe overview (product summary and download)
• Release notes (semver changelog and update behavior)
• Account → Probes (enrollment, assignment, health)
• Account → Monitoring (charts, compare, sync from probe)
• Pricing (Pro+ probe access and limits)