Private Locations

Monitor the services your firewall keeps private

Run one container inside your network and Checkly runs API, browser, and Playwright checks from there. Internal APIs, staging, the database behind the VPN: same checks, same alerts, same dashboards as the public side. Nothing opens inbound.

Start for freeView docs

Trusted by teams whose most important services never touch the public internet

Vercel
Carhartt
CrowdStrike
Airbus
Fanatics
Mistral
ServiceNow
GoFundMe
Hopper
1Password
Fastly
Total Wine

From public cloud to private network, one signal

Half your system is unreachable from the outside: internal APIs, admin tools, the staging cluster, services that only answer on the VPN. A private location puts a Checkly Agent next to them, so the checks that watch your public edge also watch what sits behind it.

Nothing gets opened inbound

The agent is a container that polls Checkly for work over an outbound connection to agent.checklyhq.com. No inbound ports, no allowlisting our IPs, no reverse tunnel. Corporate proxies and internal CA certificates are supported.

outbound onlyHTTPS_PROXYNODE_EXTRA_CA_CERTS

One platform, inside and out

The same check types, dashboards, alert channels, and status pages you use for public endpoints, now pointed at the intranet, the staging cluster, or the database behind the VPN. One signal for the whole system.

APIBrowserPlaywrightTCP · DNS · ICMP · URL

Defined in code, like everything else

A private location is a PrivateLocation construct in your Checkly CLI project. Assign it to a check or a whole group, review it in a pull request, and deploy it from CI. Full parity in the web app.

PrivateLocationprivateLocations: [...]CheckGroup

A private location is a construct

Declare the location once, then hand it to any check or group with privateLocations. The check runs only from your network. Everything else about it, assertions, frequency, alert channels, stays identical to a public check.

  • PrivateLocation takes a name, a slugName, an optional icon, and an optional proxyUrl
  • Reference locations by construct, by slug, or by UUID with PrivateLocation.fromId()
  • Assign to a single check or to a CheckGroup so every member inherits it
  • Versioned in git, reviewed in a pull request, deployed with npx checkly deploy

Construct reference: PrivateLocation · ApiCheck · CheckGroup

private-locations.check.ts
1// private-locations.check.ts
2import { ApiCheck, AssertionBuilder, PrivateLocation } from 'checkly/constructs'
3
4// One construct per network you want to run checks from
5const vpcProdEu = new PrivateLocation('vpc-prod-eu', {
6 name: 'Production VPC (eu-central-1)',
7 slugName: 'vpc-prod-eu',
8 icon: 'server',
9})
10
11// Run this check from inside the VPC only
12new ApiCheck('payments-internal-health', {
13 name: 'Payments service · internal health',
14 privateLocations: [vpcProdEu],
15 frequency: 1,
16 request: {
17 method: 'GET',
18 url: 'https://payments.internal.acme.dev/health',
19 assertions: [
20 AssertionBuilder.statusCode().equals(200),
21 AssertionBuilder.jsonBody('$.db').equals('ok'),
22 ],
23 },
24})
staging.group.ts
1// staging.group.ts
2import { CheckGroupV2, PrivateLocation } from 'checkly/constructs'
3
4// Reference a location created in the web app by its slug,
5// or an existing one by UUID with PrivateLocation.fromId()
6export const stagingGroup = new CheckGroupV2('staging', {
7 name: 'Staging · behind VPN',
8 privateLocations: ['staging-k8s'],
9 tags: ['staging'],
10})
11
12// Every check in the group inherits the private location.
13// Pass the construct itself when the location lives in this project:
14// privateLocations: [vpcProdEu]

How a check runs inside your network

The Checkly Agent is a pull-based worker. It never listens for connections from Checkly, so your security team has nothing new to open and nothing new to allowlist.

01

The agent polls for jobs

Every agent in a private location opens an outbound connection to agent.checklyhq.com and asks for scheduled check runs. Checkly never connects in. Run it with Docker, Podman, or the official Helm chart on Kubernetes.

outbound · agent.checklyhq.com
02

The check runs inside your network

The agent executes the check where it lives: the Playwright script, the API request, the TCP handshake. Internal hostnames resolve because the agent sits on your network, not ours.

runs on your infra
03

Results report back to Checkly

Timings, assertions, screenshots, traces, and logs land in the same Checkly account as your public checks. Alerts fire through the same channels. If a location has no agent connected for 10 to 20 minutes, owners and admins get an email.

same dashboards · same alerts

Requirements: a container runtime and outbound HTTPS to agent.checklyhq.com. Proxies are supported. Owner or Admin permissions to create a location.

Agent configuration →

Stateless agents, sized for your workload

An agent holds no state, so capacity is a number you pick. Start with two containers for redundancy, set JOB_CONCURRENCY from the memory you gave each one, and add containers as the check count grows. Rolling upgrades and single-agent failures do not lose checks.

  • At least two agents per location; a failed agent’s in-flight checks rerun elsewhere after 300 seconds
  • JOB_CONCURRENCY from 1 to 10 per agent: about 1.5 GB RAM per browser check, 150 MB per API check
  • Official Helm chart for Kubernetes, plus a KEDA recipe that scales pods on queued check runs
  • Readiness and liveness probes on port 8081; two active API keys per location for zero-downtime rotation

Read more: Scaling and redundancy · Kubernetes · Autoscaling

run-agents.sh
1# run-agents.sh
2# Two agents per location is the recommended minimum.
3# Agents are stateless: add or remove them at any time.
4
5docker run -d --name agent-1 \
6 -e API_KEY="pl_...." \
7 -e JOB_CONCURRENCY=5 \
8 -e LOG_LEVEL=INFO \
9 checkly/agent:latest
10
11docker run -d --name agent-2 \
12 -e API_KEY="pl_...." \
13 -e JOB_CONCURRENCY=5 \
14 -e HTTPS_PROXY="https://user:password@proxy.internal:8080" \
15 checkly/agent:latest
16
17# Sizing rule of thumb from the docs:
18# browser checks ~1.5 GB RAM each → JOB_CONCURRENCY = memory_GB / 1.5
19# API checks ~150 MB RAM each → JOB_CONCURRENCY = memory_GB / 0.15
20# Health probes for your orchestrator on :8081
21# GET /-/readiness GET /-/liveness GET /health

Good to know before you deploy

Private locations are included on the Team and Enterprise plans. Pending checks wait up to 6 minutes for a free agent, so size capacity for your peak. Playwright Check Suites need agent 6.0.3 or later on a container with 2 CPU cores and 4 GB of RAM. Heartbeat monitors are push-based and do not use locations.

Team + Enterprise6 min queue2 CPU · 4 GB for Playwright

Frequently asked questions

Everything you need to know about private locations and the Checkly Agent.

A private location is a monitoring location you run yourself by deploying the Checkly Agent, a container, inside your own infrastructure. Checks assigned to that location execute from your network instead of from Checkly’s public data centers, so you can monitor internal APIs, staging environments, intranet tools, and anything else behind a firewall or VPN. Results, alerting, and dashboards work exactly as they do for public checks.

No. The agent only makes outbound connections to agent.checklyhq.com to pick up scheduled jobs and report results. Checkly never connects into your network. If your environment routes outbound traffic through a proxy, set HTTPS_PROXY or HTTP_PROXY on the agent container. Internal CA certificates can be trusted via NODE_EXTRA_CA_CERTS.

API checks, Browser checks, Multistep checks, Playwright Check Suites, and URL, TCP, DNS, and ICMP monitors all accept a privateLocations option. Check groups accept it too, so every check in the group inherits the location. Playwright Check Suites need agent 6.0.3 or later and a container with at least 2 CPU cores and 4 GB of RAM.

Run at least two agents per private location. Agents are stateless and scale horizontally, so add or remove containers at any time. If an agent dies mid-check, another agent in the same location reruns that check after a 300-second timeout. Pending checks stay queued for 6 minutes waiting for capacity. Size each agent with JOB_CONCURRENCY (1 to 10): roughly 1.5 GB of RAM per concurrent browser check and 150 MB per API check. For Kubernetes there is an official Helm chart and a KEDA-based autoscaling recipe.

Yes. If a private location has checks assigned but no agent has connected in the last 10 to 20 minutes, Checkly flags it as unavailable and emails account owners and admins. No checks are scheduled to a location while it is unavailable; scheduling resumes automatically when an agent reconnects. The agent also exposes readiness and liveness endpoints on port 8081 for your own orchestrator health checks.

Yes. PrivateLocation is a construct in the Checkly CLI with name, slugName, an optional icon, and an optional proxyUrl for outgoing API check traffic. Pass the construct, or the slug of a location created in the web app, to any check or group via privateLocations. Locations created outside the project can be referenced with PrivateLocation.fromId(). The API key the agent authenticates with is created per location in the web app and can be rotated with two active keys.

Private locations are available on the Team and Enterprise plans. Creating, editing, and deleting a private location requires Owner or Admin permissions on the account.

One container. Every service covered.

Create a private location, run the agent, and point your first check at an internal hostname. The rest of your monitoring already knows what to do with it.

Start for freeBook a demo