openstatus logoDashboard
docs | reference

Private Location Reference

A private location in openstatus lets you deploy monitoring probes within your own infrastructure or private networks. This is essential for monitoring internal services, APIs, or systems that are not publicly accessible from the internet, such as those behind firewalls or within a Virtual Private Cloud (VPC).

Key benefits:

  • Internal monitoring — monitor services running on private networks.
  • Security — keep sensitive internal endpoints protected from public exposure.
  • Compliance — meet specific regulatory or security compliance requirements by controlling data paths.
  • Reduced latency — conduct checks closer to your services for more accurate performance metrics.
  • Full feature parity — automatic incident creation, notifications, and status page display work the same as public locations.

How it works

When a private location is configured, openstatus provides a container image you deploy within your private environment. This deployed component acts as a local monitoring probe, executing checks on behalf of your openstatus account.

  1. Deployment — you deploy the openstatus private probe within your chosen infrastructure (e.g., a Docker container on a server, a Kubernetes pod).
  2. Secure connection — the private probe establishes a secure, outbound-only connection to the openstatus platform, eliminating the need for inbound firewall rules.
  3. Check execution — openstatus dispatches monitoring tasks to your private probe via this secure connection. The probe then executes the configured checks against your internal services.
  4. Result reporting — the private probe securely sends the monitoring results (e.g., status, latency, response data) back to the openstatus platform for processing, alerting, and visualisation.

Configuration

Detailed steps for setting up a private location involve:

  1. Probe deployment — provisioning a server or container environment within your private network.
  2. Agent installation — deploying the openstatus private probe agent (e.g., Docker image) onto your infrastructure.
  3. Authentication — configuring the probe with necessary API keys or tokens to securely authenticate with your openstatus workspace.
  4. Network access — ensuring the deployed probe has network access to the internal services it needs to monitor, as well as outbound access to the openstatus platform.

Current API surface

Private locations can currently be created, listed, updated, and deleted from the authenticated dashboard API. The supported private location fields are:

  • name — the display name shown in the dashboard.
  • token — the probe authentication token. Generated by the server on creation. Returned by create, get, and update endpoints; list responses omit it for security.
  • status — read-only probe health, active or error, derived from the agent heartbeat.
  • metadata — up to 20 user-defined key/value labels (keys 1–64 characters, values up to 256 characters), for example {"city": "Frankfurt", "provider": "Hetzner"}.
  • monitors — the IDs of monitors attached to the private location.
  • lastSeenAt — the last time the private location probe connected.

Example use cases:

  • Monitoring an internal REST API that is only accessible from within your corporate network.
  • Checking the health of a database server running on a private subnet.
  • Performing synthetic transactions on an internal web application before it's exposed publicly.
Edit this page on GitHub
PreviousLocation ReferenceNextStatus Page Reference