# Checkly Private Locations

**Source**: https://www.checklyhq.com/product/private-locations/

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

## A private location is a construct

- **Monitor behind your firewall**: a private location puts a Checkly Agent next to the services that are unreachable from the outside, 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 Checkly IPs, no reverse tunnel. Corporate proxies (HTTPS_PROXY, HTTP_PROXY) and internal CA certificates (NODE_EXTRA_CA_CERTS) are supported.
- **One platform, inside and out**: the same check types, dashboards, alert channels, and status pages you use for public endpoints, pointed at the intranet, the staging cluster, or the database behind the VPN.
- **Defined in code**: `PrivateLocation` is a construct in the Checkly CLI. Assign it to a check or a whole group via `privateLocations`, review it in a pull request, and deploy it from CI. Full parity in the web app.
- **Stateless agents, sized for your workload**: run two or more containers for redundancy, set `JOB_CONCURRENCY` (1 to 10) from the memory you gave each one, and add containers as the check count grows. Official Helm chart and KEDA autoscaling recipe for Kubernetes.

## How a check runs inside your network

1. **The agent polls for jobs**: every agent opens an outbound connection to agent.checklyhq.com and asks for scheduled check runs. Run it with Docker, Podman, or Helm.
2. **The check runs inside your network**: the agent executes the Playwright script, API request, or TCP handshake where it lives, so internal hostnames resolve.
3. **Results report back to Checkly**: timings, assertions, screenshots, traces, and logs land in the same account as your public checks, and alerts fire through the same channels.

## Key facts

- Requirements: a container runtime, outbound HTTPS to `agent.checklyhq.com`, and Owner or Admin permissions to create a location.
- Supported on API, Browser, Multistep, Playwright Check Suites, and URL, TCP, DNS, and ICMP monitors, plus check groups. Heartbeat monitors are push-based and do not use locations.
- Playwright Check Suites need agent **6.0.3 or later** on a container with **2 CPU cores and 4 GB of RAM**. Roughly 1.5 GB of RAM per concurrent browser check and 150 MB per API check.
- If a location has no agent connected for 10 to 20 minutes, Checkly marks it unavailable, emails owners and admins, and pauses scheduling until an agent reconnects. Pending checks wait up to 6 minutes for a free agent; in-flight checks rerun after a 300-second timeout if an agent dies.
- Available on the **Team and Enterprise** plans.

## Frequently Asked Questions

### What is a Checkly private location?
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.

### Do I need to open a firewall port or allowlist Checkly IP addresses?
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.

### Which check types can run on a private location?
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.

### How many agents should I run, and what happens if one fails?
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.

### Will I know if my agents go down?
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.

### Can I manage private locations as code?
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.

### Which plans include private locations?
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.

## Related

- [Private Locations (full page)](https://www.checklyhq.com/product/private-locations/)
- [Private locations docs](https://www.checklyhq.com/docs/platform/private-locations/overview/)
- [PrivateLocation construct reference](https://www.checklyhq.com/docs/constructs/private-location/)
- [TCP Monitoring](https://www.checklyhq.com/product/tcp-monitoring/)
- [Monitoring as Code](https://www.checklyhq.com/product/monitoring-as-code/)
- [Pricing](https://www.checklyhq.com/pricing/)
- [Start for free](https://app.checklyhq.com/signup/)