Skip to main content
Deploying a private probe takes four steps: generate a token, start the container, assign monitors to the probe, and verify the connection. The probe runs entirely inside your infrastructure and never requires an inbound firewall rule — it only makes outbound HTTPS connections to PulseGuard.
Your probe token is a sensitive credential. Treat it like an API key: store it in a secrets manager or environment file, never commit it to source control, and rotate it immediately if you suspect it has been exposed.
1

Get your probe token

Each probe you register is identified by a unique token that the container uses to authenticate with PulseGuard.
  1. Open your PulseGuard dashboard and navigate to Settings → Private Probes.
  2. Click New Probe and give the probe a descriptive name (for example, us-east-internal or on-prem-london).
  3. Copy the generated PULSEGUARD_PROBE_TOKEN value. You will not be able to view this value again after closing the dialog.
Private probes are available on the Pro plan (up to 3) and the Enterprise plan (unlimited). The option will not appear on the Free plan.
2

Run the Docker container

Pull and start the probe image with docker run. Paste the token you copied in the previous step as the value of PULSEGUARD_PROBE_TOKEN.
The --restart unless-stopped flag ensures the probe recovers automatically after a host reboot or unexpected crash.

​
Environment variables

​
string
required
Your probe authentication token from the dashboard. The container exits immediately if this variable is not set.
​
string
required
The PulseGuard worker endpoint the probe reports to. Set this to https://worker.pulseguard.io unless you are running a self-hosted PulseGuard instance.
​
string
default:"private"
A short label that identifies this probe’s location in your dashboard and in monitor region selectors. Use a name that reflects the physical or logical location — for example, us-east-private, on-prem-london, or staging-vpc. Avoid spaces; use hyphens instead.
​
number
default:"15"
How often the probe polls PulseGuard for new check jobs, in seconds. Lower values reduce check latency but increase outbound request frequency. The minimum recommended value is 10.
​
number
default:"30"
How often the probe sends a heartbeat to PulseGuard, in seconds. If PulseGuard does not receive a heartbeat within two intervals, the probe is marked as disconnected in your dashboard.
​
number
default:"5"
Maximum number of check jobs the probe runs in parallel within a single poll cycle. Increase this value if your probe handles a high volume of monitors and you want to reduce the time taken to complete each batch.
The probe makes only outbound HTTPS connections to worker.pulseguard.io. You do not need to open any inbound ports or configure NAT rules on your firewall.

​
Docker Compose

If you prefer to manage the probe alongside other services in a Compose file, use the following configuration:
docker-compose.yml
Start it with:
3

Assign monitors to the probe

Once the probe is running, tell PulseGuard which monitors should use it.
  1. In the dashboard, open an existing monitor or create a new one.
  2. Scroll to the Check Regions section.
  3. Select the region label that matches the PROBE_REGION value you set — for example, us-east-private.
  4. Save the monitor.
On the next poll interval, the probe will receive the check job and begin executing it. Results will appear in the monitor’s history alongside any checks from public edge regions you have enabled.
You can assign the same monitor to both a private probe region and one or more public edge regions simultaneously. This lets you compare internal vs. external reachability for the same service.
4

Verify the probe is running

Confirm the probe connected successfully before relying on it for production monitoring.
  1. Navigate to Dashboard → Settings → Private Probes.
  2. Find the probe you created. Its status should show as Connected with a Last Heartbeat timestamp within the last PROBE_HEARTBEAT_INTERVAL seconds.
If the probe shows as Disconnected, check the container logs for error messages:
Common causes of a failed connection:

​
Next steps

With the probe running and connected, you can:
  • Create monitors targeting internal hostnames and assign them to your private probe region
  • Set up alert rules so your team is notified when internal services degrade
  • Add your private probe’s region to a public status page to show internal-service health alongside public endpoints