byVouched
API ReferenceBlogSign inGet started
GuidesDetectEnforceGovern

Quickstart

Install the CLI, connect your app with browser and server detection, and see your first result in Activity.

This walkthrough uses kya-os, the Checkpoint CLI, to add the Pixel and server SDK. You'll finish by finding your own browser visit and a sample agent request in Activity. For manual setup, see Installation.

Watch the quickstart

Next.js · Pixel + SDK
FROM SETUP TO ACTIVITY

See your first detection.

Edited setup replay with recorded Activity. Installation waits are shortened.

You need a Checkpoint account and an app you can run locally or deploy. Start in your app's directory. The CLI supports macOS, Linux, and Windows through WSL; Installation covers platforms and supported stacks.

Install the CLI

curl -fsSL https://kya.vouched.id/install | sh
export PATH="$HOME/.kya-os/bin:$PATH"
Install the CLI

Install the CLI and add it to your PATH.

Edited setup replay. Installation waits are shortened.

With the curl installer, the export line makes kya-os available in this terminal immediately. Installation covers installer options.

Connect your app

Use the Pixel and server SDK together for broader coverage. The Pixel sees browser visits that run JavaScript. The SDK also detects requests on your server's configured routes, including agents that never execute JavaScript.

Connect your app

Authorize your project, then add the Pixel and SDK.

Edited setup replay. Installation waits are shortened.

First, run setup from your app's directory:

kya-os setup

The wizard opens your browser to sign in, selects or creates a project, and previews the Pixel changes before applying them. The Pixel needs only your public project ID.

Add server-side detection

For a supported server app, continue in the same directory. If your site has no supported server integration, keep the Pixel and skip to verifying the browser visit below.

kya-os detect install --surface sdk

For Next.js and Express 4, the CLI offers to create a missing CHECKPOINT_API_KEY and writes it to a gitignored environment file. On Next.js, it installs the package and creates proxy.ts (Next.js 16+) or middleware.ts. If you already have middleware, follow the printed instructions to combine them. On Express 4, ASP.NET, and Java, finish the wiring the CLI prints before continuing.

Start or restart your app to load the changes. If you're testing a deployed app, deploy the code and configure its runtime credentials first. For an initial rollout, review your SDK and policy settings and choose observe mode where supported; defaults differ by integration.

See your first detection

See your first detection

Send a sample request and find it in Activity.

Edited setup replay with recorded Activity. Installation waits are shortened.

Visit your app in a browser, then open the same project's Activity feed in the dashboard. Allow up to a minute and look for a fresh entry matching the page you loaded. Your own visit can appear as human; you don't need to wait for an agent to confirm that reporting works.

If you installed the server SDK, test it by sending a sample request to a route it covers. Replace the URL below with your running app's local or deployed address:

curl -sS -A 'ChatGPT-User/1.0' -o /dev/null -w 'HTTP %{http_code}\n' https://your-app.example/

The Java server SDK sends the first verdict immediately and batches later ones: they are held until telemetryBatchSize (default 50) is reached, you call Checkpoint.flush(), or the app closes the Checkpoint. In a test app, call flush() after the sample request.

Find the new entry by its timestamp and request path, then inspect its classification and agent label. This User-Agent is recognized as ai_agent, with ChatGPT as the agent. This tests recognition of the declared agent name; it does not prove the request came from ChatGPT. A crawler such as GPTBot is classified as a bot rather than an agent.

Open the browser visit's Source details and check its method for Pixel. For the SDK, the fresh sample request matching your test time, path, and ChatGPT label confirms that a request without JavaScript reached Activity. The command's HTTP status alone does not confirm reporting. Source metadata and policy details vary by SDK version.

If the feed stays empty, see Not detecting agents? below.

Next steps

Core Concepts

Detections versus verdicts, the trust ladder, observe-first rollout, and where identity comes in.

Govern your coding agent

kya-os govern install --agent claude: every Claude Code tool call in this repository shows up in Activity.

Set up browser posture

Add the beacon, serve it from your own domain, and verify a signed token on your server.

Enforce

Turn verdicts into blocks, redirects, and challenges with a policy.

Let your agent set it up

Give Claude Code, Cursor, or any coding agent the Checkpoint skill, and it runs this page for you.

Troubleshooting

Fixes for the problems people most often hit during setup.

Frequently asked questions

How long does it take to set up Checkpoint?

There are three milestones: install the CLI, connect your app, and see your first detection. A supported app with no existing middleware can take about five minutes; allow extra time for manual wiring or deployment.

Do I need an API key?

Not for the Pixel or Beacon: they take only the public project ID. The server SDK needs the project's runtime key in your app's environment. For Next.js and Express, the CLI offers to create a missing key when you're signed in. The CLI itself never asks for an API key to sign you in. See Credentials.

What is the difference between kya-os setup and kya-os detect install?

setup signs you in, links the repository to a project, and then runs detect install. Run detect install on its own to add another surface (--surface beacon or --surface sdk) to a repository that's already linked.

Not detecting agents?

  • Run kya-os whoami and check that this repository is linked (*) to the project you're watching in the dashboard.
  • Check the Activity time range and clear filters that could hide your request, including a class filter that excludes human.
  • Check the page for the Pixel (kya.vouched.id/pixel.js) and your browser's Network tab for its reporting request to kya.vouched.id. A successful script download alone does not confirm that the visit was reported.
  • If the browser visit appears but the sample server request doesn't, check that you finished the SDK wiring and the test route passes through the middleware. Restart the app after setting CHECKPOINT_API_KEY, and check server logs for reporting errors. Express must load its .env file explicitly.
  • A sample request can appear with Unrecognized runtime or no policy verdict when its SDK version does not report those details. Match the fresh request's time, path, and agent label to verify reporting; missing metadata does not mean the request was lost.
  • On Next.js, proxy.ts or middleware.ts belongs at the project root, or in src/ when the app uses a src/ directory; never inside app/.
  • Pixel and Beacon: set data-debug="true" on the Pixel script, or debug: true with logLevel: 'debug' in the Beacon config, to log what's sent. For further checks, see Troubleshooting.

Too many false positives?

  • Review confidence scores in Analytics.
  • Adjust your policy rules.
  • Deploy your policy in observe mode before switching it to enforce.

Introduction

Checkpoint protects your applications from AI agents and automated bots

Installation

Every way to install the kya-os CLI, plus each Checkpoint SDK by hand if you'd rather not use it.

On this page

Install the CLIConnect your appAdd server-side detectionSee your first detectionNext stepsFrequently asked questionsHow long does it take to set up Checkpoint?Do I need an API key?What is the difference between kya-os setup and kya-os detect install?Not detecting agents?Too many false positives?