> ## Documentation Index
> Fetch the complete documentation index at: https://pulse-41cf5b0d.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy a Private Probe with Docker

> Run the PulseGuard probe as a Docker container in your network in under 5 minutes. Requires a probe token from your dashboard.

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.

<Warning>
  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.
</Warning>

<Steps>
  <Step title="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.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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`.

    ```bash theme={null}
    docker run -d \
      --name pulseguard-probe \
      -e PULSEGUARD_PROBE_TOKEN=your_probe_token \
      -e PULSEGUARD_API_URL=https://worker.pulseguard.io \
      -e PROBE_REGION=us-east-private \
      -e PROBE_POLL_INTERVAL=15 \
      -e PROBE_HEARTBEAT_INTERVAL=30 \
      --restart unless-stopped \
      pulseguard/probe:latest
    ```

    The `--restart unless-stopped` flag ensures the probe recovers automatically after a host reboot or unexpected crash.

    ### Environment variables

    <ParamField body="PULSEGUARD_PROBE_TOKEN" type="string" required>
      Your probe authentication token from the dashboard. The container exits immediately if this variable is not set.
    </ParamField>

    <ParamField body="PULSEGUARD_API_URL" type="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.
    </ParamField>

    <ParamField body="PROBE_REGION" type="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.
    </ParamField>

    <ParamField body="PROBE_POLL_INTERVAL" type="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`.
    </ParamField>

    <ParamField body="PROBE_HEARTBEAT_INTERVAL" type="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.
    </ParamField>

    <ParamField body="PROBE_CONCURRENCY" type="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.
    </ParamField>

    <Note>
      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.
    </Note>

    #### Docker Compose

    If you prefer to manage the probe alongside other services in a Compose file, use the following configuration:

    ```yaml docker-compose.yml theme={null}
    version: '3.8'
    services:
      pulseguard-probe:
        image: pulseguard/probe:latest
        restart: unless-stopped
        environment:
          PULSEGUARD_PROBE_TOKEN: your_probe_token
          PULSEGUARD_API_URL: https://worker.pulseguard.io
          PROBE_REGION: production-private
          PROBE_POLL_INTERVAL: "15"
          PROBE_HEARTBEAT_INTERVAL: "30"
    ```

    Start it with:

    ```bash theme={null}
    docker compose up -d pulseguard-probe
    ```
  </Step>

  <Step title="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.

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="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:

    ```bash theme={null}
    docker logs pulseguard-probe
    ```

    Common causes of a failed connection:

    | Symptom in logs                                           | Likely cause                                                                              |
    | --------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
    | `PULSEGUARD_PROBE_TOKEN environment variable is required` | The token variable was not passed to the container.                                       |
    | `fetch failed for … : ECONNREFUSED`                       | The host cannot reach `worker.pulseguard.io`. Check your firewall's outbound HTTPS rules. |
    | `failed: 401`                                             | The token is invalid or has been revoked. Generate a new one from the dashboard.          |
  </Step>
</Steps>

## 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