How to Install a Private Worker and Monitor Internal Services

Cloud uptime monitors are excellent for public websites and APIs — but they have one hard limitation: they cannot reach anything behind a firewall. Your internal staging environment, the Raspberry Pi running Home Assistant, the NAS at the branch office, the Kubernetes cluster on a private subnet — none of these are reachable from a data-center-based checker.

Monitorion Private Workers solve this. A private worker is a lightweight agent you run inside your own network. It receives monitoring instructions from Monitorion, performs the checks locally against your private targets, and reports results back over outbound HTTPS. You get the same dashboard, the same alert channels, and the same history charts — with checks originating from inside your network.

What Private Workers Can Monitor

Once installed, you can assign any compatible monitor type to your worker:

• HTTP/HTTPS — Internal web apps, admin dashboards, staging environments, local APIs, home automation interfaces
• Ping (ICMP) — Servers, routers, IoT devices, NAS boxes, printers, access points
• Port checks — Databases (MySQL 3306, Postgres 5432), MQTT brokers (1883), SSH (22), Redis (6379), custom services
• SSL certificates — Internal TLS endpoints with self-signed or private CA certificates
• DNS — Internal resolvers not exposed publicly
• FTP / IMAP — File servers and mail servers on private networks

Common use cases: home lab monitoring (Home Assistant, Frigate NVR, routers, NAS), staging and development environments, enterprise internal services, branch office connectivity checks, and monitoring Kubernetes services from within the cluster.

How It Works — No Inbound Ports Needed

The architecture is outbound-only. The worker polls Monitorion for pending jobs, runs the checks, and posts results back — all over HTTPS. Your firewall does not need to change. If the machine can make HTTPS requests to the internet, the worker can operate.

1. Monitorion's scheduler queues a check for a monitor assigned to your worker.
2. Your worker polls the queue, picks up the job, and performs the check against the internal target.
3. The worker posts the result back to Monitorion over HTTPS.
4. The result appears in your dashboard and triggers alerts if the target is down.

Prerequisites

• A machine on your target network (Linux, macOS, or Windows with WSL2)
• Docker installed — or Node.js 20+ for native installation
• Outbound HTTPS access (port 443) from that machine to app.monitorion.com
• A Monitorion account — private workers are available on all plans including free

Step 1 — Register the Worker in Monitorion

Go to Settings → Private Workers and click Add Worker. Give it a descriptive name: home-lab, office-network, staging, or whatever matches the network it will live on. Click Register.

Monitorion displays a one-time API key in a green banner. Copy it immediately — it is shown only once and stored only as a hash. If you lose it, delete the worker and register a new one. The key looks like this:

wkr_a3f9e2c8b7d4f1e6a9c2b5d8f3e7a0b4c1d6e9f2a5b8c3d7e0f4a7b1c5d9e2f6

Step 2 — Install with Docker (Recommended)

On the machine inside your network, run:

docker run -d   --name monitorion-worker   --restart unless-stopped   -e MONITORION_PLATFORM_URL=https://app.monitorion.com   -e MONITORION_API_KEY=wkr_your_api_key_here   -e WORKER_NAME=home-lab   monitorion/worker:latest

The --restart unless-stopped flag keeps the worker running through reboots and crashes. The container is under 100 MB and uses negligible CPU at idle. Verify it started correctly:

docker logs monitorion-worker

You should see "Worker connected — polling for jobs" within seconds.

Step 3 — Confirm the Worker Is Online

Back in Settings → Private Workers, the worker's status changes from Pending to Active (green badge) within 30 seconds of the container starting. You will also see the version and last-seen timestamp update in real time. Click the worker card to expand it and see connection details.

If the status stays Pending after a minute, check:

• The API key starts with wkr_ and was not truncated
• The machine can reach the internet: curl -s https://app.monitorion.com/api/health
• Docker logs show no auth errors: docker logs monitorion-worker --tail 20

Step 4 — Create a Monitor Assigned to Your Worker

Click Add Monitor from the main dashboard and select any supported type (HTTP, Ping, Port, DNS, SSL, FTP, IMAP). Enter the private IP address or internal hostname as the target — values that would be unreachable from the cloud:

• HTTP: http://192.168.1.100:8123 (Home Assistant)
• Ping: 192.168.1.1 (router)
• Port: 192.168.1.200:3306 (MySQL)

Scroll to the Where to run section. Three options appear:

• ☁ Cloud — single region: Monitorion's global cloud checkers (default)
• 🌍 Cloud — multi-region: Simultaneous checks from multiple cloud locations (Pro+)
• 🔒 Private worker: Your registered worker inside your network

Select Private worker, choose your worker from the dropdown, and save. The check runs from inside your network on the next scheduled interval.

Step 5 — Reassign Existing Monitors

You can also move existing monitors to a private worker. Open any monitor, click Edit, find the Where to run section, select your worker, and save. The change takes effect on the next check cycle.

Note: private worker and multi-region are mutually exclusive. A private worker monitor uses only that worker's network location. For redundancy across multiple private locations, register additional workers and create separate monitors per location.

Finding Your Private Worker Monitors

Back on the main monitors dashboard, every monitor running via a private worker shows a purple PW badge next to its name — making internal checks instantly distinguishable from cloud checks. The monitor detail page shows full uptime history, response time charts, and incident logs, identical to any other monitor.

Alert channels (email, Slack, Discord, SMS, PagerDuty, Telegram) work exactly the same. You receive an alert the moment the worker reports a target is down, and a recovery notification when it comes back up.

Running Multiple Workers

Register as many workers as you need — one per office location, per network segment, per Kubernetes namespace. Each gets its own API key and appears separately in Settings → Private Workers. When creating or editing a monitor, you choose exactly which worker handles it.

This lets you build complete internal monitoring: verify branch office A can reach HQ's database, staging can reach its Redis instance, and every router on every subnet responds to ping — all from the network segments that actually matter.

Native Installation Without Docker

If Docker is not available, run the worker natively with Node.js 20+:

npm install -g @monitorion/worker

MONITORION_PLATFORM_URL=https://app.monitorion.com MONITORION_API_KEY=wkr_your_api_key_here WORKER_NAME=home-lab monitorion-worker

For production without Docker, manage it with PM2:

npm install -g pm2
pm2 start monitorion-worker   --name monitorion-worker   -e MONITORION_PLATFORM_URL=https://app.monitorion.com   -e MONITORION_API_KEY=wkr_your_api_key_here   -e WORKER_NAME=home-lab
pm2 save && pm2 startup

Security Design

• Outbound-only — The worker listens on no ports. No firewall rules needed.
• API key isolation — Each worker has a unique key. Revoking it in Settings immediately blocks further results from that worker.
• Result scoping — Workers can only submit results for monitors explicitly assigned to them. A worker cannot read or affect any other user's data.
• One-time key display — The key is shown once and stored only as a SHA-256 hash. Nobody at Monitorion can retrieve it.

Troubleshooting

Worker stays Pending after 60 seconds — Verify the API key is complete (starts with wkr_, ~100 chars) and the machine can reach app.monitorion.com on port 443.

Monitor shows "down" for a host you can reach — Confirm the worker machine itself can reach the target. Run docker exec monitorion-worker curl http://192.168.x.x or docker exec monitorion-worker ping 192.168.x.x to test reachability from within the container.

Worker goes inactive after running — A worker is marked inactive if it has not polled in 5 minutes. Check docker ps or pm2 status to confirm the process is still running.

Monitor count looks wrong — Click the worker card in Settings → Private Workers to see the exact list of assigned monitors. Monitors reassigned to cloud no longer count.

Quick Summary

1. Register the worker in Settings → Private Workers — copy the one-time API key.
2. Run the Docker command (or npm install) on your internal machine.
3. Confirm Active status in the dashboard within 30 seconds.
4. Create or edit monitors — target private IPs/hostnames, select your worker in "Where to run".
5. Done. Checks run on schedule, alerts fire like any other monitor, purple PW badge marks your internal checks.

Private workers bring Monitorion's full monitoring power inside your network in under five minutes — no VPN, no firewall changes, no exposed ports.