Checkly Quickstart

Add synthetic monitoring to your existing project in minutes. Let your AI agent set up Checkly, or follow the steps yourself.

Add synthetic monitoring to a project you already have, in any language or framework, in minutes. You’ll end up with checks running around the clock from global locations, alerting you the moment your site or API breaks. The fastest path is to let your AI coding agent set it up: npx checkly init installs the Checkly CLI and agent skills, and from there your agent can generate, test, and deploy your monitoring as Monitoring as Code that lives alongside your application code.

The steps below explain each phase so you understand what the agent does, and you can run them yourself if you prefer.

The recommended flow, end to end. Each phase is explained below.

Get started with Monitoring as Code

Prerequisites

• Node.js 20.19+ or 22.12+, and npm
• A terminal
• (Optional) the URL of an app or API you want to monitor

Let your AI agent set it up (recommended)

Run npx checkly init and answer a few prompts to let your agent take over:

Terminal

npx checkly init

✔ Do you want your AI agent to set up Checkly? … yes
✔ Install the Checkly skill for your AI coding agent? … yes
✔ Which AI coding agent do you use? › Claude
✔ Run npm install to install them now? … yes

...

✔ Copy prompt to clipboard? … yes

You're ready to go!

checkly init installs the Checkly CLI and agent skills, creates a checkly.config.ts, installs dependencies, and copies a starter prompt tailored to your project to your clipboard. Paste it into your AI agent and follow the instructions.

From here, what the agent does depends on your project. It might:

• Scan your project and discover monitoring targets
• Create Checkly monitors in code
• Test them with npx checkly test
• Set up alert channels
• Reuse your existing Playwright tests
• Deploy your monitoring with npx checkly deploy after your confirmation

It asks for input along the way. Open your Checkly dashboard to see your monitoring live.

To see what each command does, or to run them yourself, follow the steps below.

Set it up yourself

The steps below use the Checkly CLI directly so you can build and deploy your monitoring by hand.

1. Bootstrap a Checkly project

   Run the init command in your project directory and decline the agent setup. It scaffolds a working example you can edit.

   Terminal

   npx checkly init
   
   ✔ Do you want your AI agent to set up Checkly? … no
   ✔ Run npm install to install them now? … yes
   ✔ Add some demo checks to get started? … yes
   ✔ Created __checks__/ with example checks
   
   ...
   
   All done!
   

   This scaffolds a checkly.config.ts file and a __checks__ folder containing a few starter checks:

   Project structure

   |- checkly.config.ts
   |__checks__
       |- api.check.ts
       |- heartbeat.check.ts
       |- homepage.spec.ts
       |- url.check.ts
   

   The checkly.config.ts file holds your project-wide settings, such as the default run frequency, locations, and which files contain your checks.

2. Log in to Checkly

   Log in to your Checkly account, or create a free one, right from the terminal.

   Terminal

   npx checkly login
   

   This opens your browser to authenticate. Once you’re logged in, you can run and deploy checks from your machine. Run npx checkly whoami at any time to confirm which account you’re connected to.

3. Write your first check

   Checks are code. The scaffolded __checks__/homepage.spec.ts is a Browser Check: a standard @playwright/test file that Checkly runs as a monitor. Edit it to load a page and assert on what matters:

   homepage.spec.ts

   TypeScript

   import { test, expect } from '@playwright/test'
   
   test('homepage loads', async ({ page }) => {
     const response = await page.goto('https://www.checklyhq.com')
     expect(response?.status()).toBeLessThan(400)
     await expect(page).toHaveTitle(/Checkly/)
     await page.screenshot({ path: 'homepage.jpg' })
   })
   

   const { test, expect } = require('@playwright/test')
   
   test('homepage loads', async ({ page }) => {
     const response = await page.goto('https://www.checklyhq.com')
     expect(response?.status()).toBeLessThan(400)
     await expect(page).toHaveTitle(/Checkly/)
     await page.screenshot({ path: 'homepage.jpg' })
   })
   

   Checkly turns every *.spec.ts file into a Browser Check through the browserChecks.testMatch pattern in your checkly.config.ts. To monitor an endpoint instead, edit __checks__/api.check.ts, which defines an API Check. For every construct and option, see the Constructs reference.

4. Run your checks locally

   Dry-run all your checks against Checkly’s global infrastructure before you deploy anything:

   Terminal

   npx checkly test
   

   You’ll see the results in your terminal:

   Running 2 checks in eu-west-1.
   
   __checks__/homepage.spec.ts
     ✔ homepage loads (24s)
   __checks__/api.check.ts
     ✔ Hello API (222ms)
   
   2 passed, 2 total
   

   Runs are recorded as test sessions by default, with full logs, traces, and videos you can review in the Checkly web app.

5. Deploy to production

   Deploy your checks and related resources to Checkly. From now on, they run around the clock from Checkly’s global locations:

   Terminal

   npx checkly deploy
   

   Open your Checkly dashboard and you’ll see your checks, ready to start monitoring.

6. Set up alerts

   Add an alert channel so you’re notified when a check fails. Define the channels you want in a new __checks__/alert-channels.ts file, then attach them to your checks through the alertChannels defaults in your config.

   Email

   alert-channels.ts

   import { EmailAlertChannel } from 'checkly/constructs'
   
   export const emailChannel = new EmailAlertChannel('email-alert-channel', {
     address: '[e-mail]',
   })
   

   Phone

   alert-channels.ts

   import { PhoneCallAlertChannel } from 'checkly/constructs'
   
   export const phoneChannel = new PhoneCallAlertChannel('phone-alert-channel', {
     name: 'On-call engineer',
     phoneNumber: '[phone]',
   })
   

   Import the channels you defined and set them as defaults in your checkly.config.ts so every check, including your Browser Check, uses them. This example assumes you defined both, so import only the channels you created:

   checkly.config.ts

   import { defineConfig } from 'checkly'
   import { emailChannel, phoneChannel } from './__checks__/alert-channels'
   
   export default defineConfig({
     projectName: 'My Project',
     logicalId: 'my-project',
     checks: {
       // ...your existing check defaults
       alertChannels: [emailChannel, phoneChannel],
     },
   })
   

   You can also attach alertChannels to an individual check or a check group for finer control. Run npx checkly deploy again to apply your alerting, and see the alert channels overview for every supported channel.

When you’re done experimenting, tear down everything this project created with npx checkly destroy.

Go deeper

Constructs reference

Every check, monitor, and alert channel you can define as code.

CLI reference

All npx checkly commands and options.

Browser Checks

Monitor realistic user flows with Playwright.

API Checks

Monitor your backend services and endpoints.

Alerts

Configure who gets notified, and how.

CI/CD integration

Run and deploy your checks from your pipeline.