← Back to index

Private Location Service #

Manage private locations — self-hosted checker agents that run your monitors from inside your own network, instead of from OpenStatus' public regions. The Private Location Service provides 5 RPC methods.

Each private location owns an agent token, generated by the server on creation. The agent uses it to authenticate, so treat it as a secret: it is returned by createPrivateLocation and getPrivateLocation, and deliberately omitted from listPrivateLocations.

All examples assume you have created a client:

import { createOpenStatusClient } from "@openstatus/sdk-node";

const client = createOpenStatusClient({
  apiKey: process.env.OPENSTATUS_API_KEY,
});

Create Private Location #

const { privateLocation } = await client.privateLocation.v1
  .PrivateLocationService.createPrivateLocation({
    name: "eu-datacenter",
    monitorIds: ["123456"], // optional
    metadata: { env: "production", team: "platform" }, // optional
  });

console.log(`ID: ${privateLocation?.id}`);
console.log(`Token: ${privateLocation?.token}`); // store securely

Create Options #

Get Private Location #

Returns the full private location, including its agent token.

import { PrivateLocationStatus } from "@openstatus/sdk-node";

const { privateLocation } = await client.privateLocation.v1
  .PrivateLocationService.getPrivateLocation({ id: "pl_123" });

if (privateLocation) {
  console.log(`Name:      ${privateLocation.name}`);
  console.log(`Status:    ${PrivateLocationStatus[privateLocation.status]}`);
  console.log(`Monitors:  ${privateLocation.monitorIds.join(", ")}`);
  console.log(`Last seen: ${privateLocation.lastSeenAt || "never"}`);
}

status is computed from the agent heartbeat and is read-only: ACTIVE means the agent is reporting normally, ERROR means it has stopped reporting. See PrivateLocationStatus.

List Private Locations #

Returns PrivateLocationSummary values — the agent token is not included.

const { privateLocations, totalSize } = await client.privateLocation.v1
  .PrivateLocationService.listPrivateLocations({ limit: 10, offset: 0 });

console.log(`Found ${totalSize} private locations`);
for (const location of privateLocations) {
  console.log(
    `  ${location.name}: ${location.monitorCount} monitors, ` +
      `last seen ${location.lastSeenAt || "never"}`,
  );
}

Update Private Location #

const { privateLocation } = await client.privateLocation.v1
  .PrivateLocationService.updatePrivateLocation({
    id: "pl_123",
    name: "eu-datacenter-2",
    monitorIds: ["123456", "123457"],
    metadata: { env: "production" },
  });

Delete Private Location #

const { success } = await client.privateLocation.v1.PrivateLocationService
  .deletePrivateLocation({ id: "pl_123" });

Assigning Monitors #

Monitors are attached to a private location through monitorIds on createPrivateLocation / updatePrivateLocation. The relationship is also visible from the monitor side: HTTP, TCP, and DNS monitors expose a read-only privateLocationIds: string[].

const { httpMonitors } = await client.monitor.v1.MonitorService.listMonitors(
  {},
);

for (const monitor of httpMonitors) {
  if (monitor.privateLocationIds.length > 0) {
    console.log(`${monitor.name} → ${monitor.privateLocationIds.join(", ")}`);
  }
}