Using HTTP proxies

If you are operating our Checkly Agent behind an HTTP proxy, for example in an enterprise environment, you can use an outgoing proxy for all check traffic. We recommend using the following setup.

Note you can also define a proxy for management traffic from your private location to the Checkly API where we ingest your telemetry and management events. See the environment variables available to the Checkly Agent container

Setting an HTTP proxy for your Private Location

We recommend storing the URL of your proxy in a global environment variable so you can easily reuse it in your Private Location configuration and checks. In the example below we store it as PROXY_URL

private location proxy url

After this, you can reference this variable using {{PROXY_URL}} in the Private Location configuration.

private location proxy url

Using an HTTP proxy with API checks

With the setup complete, any API check which uses that Private Location will automatically inherit the proxy configuration for outgoing traffic.

Using an HTTP proxy with Browser checks

You can enable your proxy directly in your browser checks via a few extra lines of code, using the process.env.PROXY_URL notation. For Playwright, you can use the proxy option when launching a new browser instance. With Puppeteer, you can pass the URL as a CLI option, but you will have to supply the username and password separately if your proxy is authenticated.

const { chromium } = require('playwright')

;(async () => {
  const browser = await chromium.launch({
    proxy: {
      server: process.env.PROXY_URL // just reference the global evironment variable.
  const page = await browser.newPage()
  await page.goto('')
  await page.close()
  await browser.close()
const puppeteer = require('puppeteer')

;(async () => {
  const browser = await puppeteer.launch({
    args: ['--proxy-server=123.456.789:3128'] // provide the host and port name here
  const page = await browser.newPage()
  await page.authenticate({ // provide any authentication credentials here
    username: 'username',
    password: 'password',

This is all that is required for a browser check to proxy all outbound network connections via your designated HTTP proxy. Check out both the Playwright networking docs and the Chromium network settings docs for some more information.

You can contribute to this documentation by editing this page on Github