byVouched
Sign inGet started
Checkpoint Docs

Quick Start

Get Checkpoint running in 5 minutes

Prerequisites

  • A Checkpoint project, with its Project ID and API key to hand — see Credentials for where to find both.
  • A running app on one of the stacks below (Next.js, Express, ASP.NET Core, or any site you can add a script tag to).
  • Not sure which one to pick? Choose your integration compares them.

5-Minute Setup

Choose your preferred integration method and follow the steps below.

Next.js Quick Start

1. Install the package

npm install @kya-os/checkpoint-nextjs

2. Create middleware

Create middleware.ts in your project root:

Next.js 16: middleware.ts → proxy.ts

In Next.js 16 this file convention was renamed. Name the file proxy.ts and export a proxy function (a default export also works); middleware.ts exporting middleware still works but is deprecated. The Checkpoint setup below is identical either way — only the file name and export name change. One caveat: proxy.ts runs on the Node.js runtime only, so if you want Checkpoint on the Edge runtime (lowest latency), keep the file as middleware.ts. On Next.js 15 and earlier, use middleware.ts.
import { withCheckpointApi } from '@kya-os/checkpoint-nextjs/api-middleware';

export default withCheckpointApi({
  apiKey: process.env.CHECKPOINT_API_KEY,
});

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)'],
};

3. Add environment variables

# .env.local
CHECKPOINT_API_KEY=your_api_key_here

See Credentials for how to find your API Key and Project ID in the dashboard.

4. Deploy

npm run build && npm run start

Checkpoint is now detecting AI agents on your Next.js application. View results in the dashboard.

Express Quick Start

1. Install the package

npm install @kya-os/checkpoint-express

2. Add middleware

import express from 'express';
import { withCheckpoint } from '@kya-os/checkpoint-express';

const app = express();
app.use(express.json()); // body-parser — required for KYA-OS proof-envelope parsing

app.use(
  withCheckpoint({
    tenantHost: 'your.tenant.example',
    apiKey: process.env.CHECKPOINT_API_KEY, // enables dashboard reporting
    projectId: process.env.CHECKPOINT_PROJECT_ID, // enforces your deployed Cedar policy
  })
);

app.get('/', (req, res) => {
  res.send('Protected by Checkpoint!');
});

app.listen(3000);

3. Add environment variables

# .env
CHECKPOINT_PROJECT_ID=your_project_id_here
CHECKPOINT_API_KEY=your_api_key_here

4. Run your server

node app.js

Your Express application is now protected. withCheckpoint defaults to enforce mode — for a first rollout, set enforcementMode: 'observe' to log verdicts without blocking anything, review them in the dashboard, then switch to enforce. See Enforce vs. observe.

ASP.NET Core Quick Start

1. Install the package

dotnet add package KyaOs.Checkpoint

KyaOs.Checkpoint is a metapackage that ships no code of its own — NuGet resolves the right adapter for your target framework and pulls Checkpoint.Core in transitively: Checkpoint.AspNetCore on modern .NET (net8.0+), or Checkpoint.AspNet on .NET Framework 4.6.2+ (System.Web / IIS). See the .NET integration guide if you'd rather reference the adapter packages directly.

2. Add middleware

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCheckpoint(options =>
{
    options.ProjectId = builder.Configuration["Checkpoint:ProjectId"]!;
    options.ApiKey = builder.Configuration["Checkpoint:ApiKey"]!;
    options.OnAgentDetected = DetectedAction.Block;
});

var app = builder.Build();

app.UseCheckpoint();

app.UseRouting();
app.MapControllers();

app.Run();

DetectedAction.Block blocks detected agents outright. The option defaults to DetectedAction.Log, which records detections without blocking — start there, review what's detected in the dashboard, then switch to Block. See Enforce vs. observe.

3. Add configuration

// appsettings.json
{
  "Checkpoint": {
    "ProjectId": "your_project_id",
    "ApiKey": "your_api_key_here"
  }
}

4. Run your application

dotnet run

Your ASP.NET Core application is now protected. See the full .NET integration guide for signature verification, KYA-OS instruct mode, and more.

JavaScript Beacon Quick Start

1. Install the package

npm install @kya-os/checkpoint-beacon

2. Initialize the beacon

import { CheckpointBeacon } from '@kya-os/checkpoint-beacon';

const beacon = new CheckpointBeacon({
  projectId: 'YOUR_PROJECT_ID',
});

// Record a page view (a periodic heartbeat also runs automatically)
beacon.collect('pageview');

Constructing the beacon starts periodic collection automatically — there is no start() method to call.

3. Track custom events (optional)

await beacon.trackEvent('form_submit', {
  form_id: 'signup',
  page: window.location.pathname,
});

4. Track page unload (optional)

window.addEventListener('pagehide', () => beacon.trackPageUnload());

The Beacon collects signals and sends them to Checkpoint — classification happens server-side, so there is no .on('detection') callback or client-side result. View classifications in the dashboard, and see the Beacon guide for the full API and Web Worker offloading details.

Google Tag Manager Quick Start

1. Install the template

Open the Checkpoint Pixel template in the Community Template Gallery (publisher: Know-That-Ai), or in GTM go to Templates → Tag Templates → Search Gallery and search for Checkpoint (older gallery listings may still show the AgentShield name until Google syncs the renamed template).

Click Add to Workspace and accept the permissions prompt.

One-time install per GTM container. See GTM + Next.js integration for the full walkthrough including user identification.

2. Create a new tag

  1. Go to Tags → New → Tag Configuration → Custom
  2. Select Checkpoint Pixel
  3. Configure:

3. Set up triggers

  1. Add trigger: All Pages for basic protection
  2. Optional: Add History Change trigger for SPAs

4. Publish

  1. Click Submit in the top right
  2. Add version description
  3. Click Publish

Detections will appear in your Checkpoint dashboard within seconds.

Verify Installation

After installation, verify Checkpoint is working:

Check the Dashboard

  1. Open the Checkpoint Dashboard
  2. Navigate to your project
  3. Open the Activity feed
  4. You should see detections appearing in near real time

Check Network Requests

  1. Open your browser's Developer Tools
  2. Go to the Network tab
  3. Look for requests to kya.vouched.id
  4. Successful requests return a 200 status

Enable debug: true in your configuration (Beacon) or set data-debug="true" (Pixel) to see detailed console output during development.

Environment Variables

We recommend using environment variables for configuration:

# .env or .env.local
CHECKPOINT_API_KEY=your_api_key_here        # Server-side only — never expose to the browser
CHECKPOINT_PROJECT_ID=your_project_id_here  # Not secret; used server-side and client-side

Keep your API Key secret. Never expose it in client-side code. The Project ID is not a secret — server integrations read it (the Express example above passes it as projectId), and it is also safe to expose to the browser for the Pixel and Beacon. For client-side use in Next.js, prefix it so the bundler inlines it: NEXT_PUBLIC_CHECKPOINT_PROJECT_ID.

The SDKs read a few more environment variables directly — CHECKPOINT_API_URL, CHECKPOINT_USE_EDGE, CHECKPOINT_DEBUG, and CHECKPOINT_SECRET. See Credentials for the full table.

Next Steps

Now that Checkpoint is running:

  1. Dashboard Analytics — View detection data and trends
  2. Detection Methods — Understand detection approaches
  3. Enforcement — Set up active enforcement policies
  4. Govern (KYA-OS) — Control AI agent access with identity
  5. Choose Your Integration — Compare all integration options

Troubleshooting

Not detecting agents?

  • Verify your Project ID is correct
  • Check network requests in browser DevTools for errors
  • Ensure middleware is in the project root (Next.js)
  • Enable debug mode for detailed logs

Too many false positives?

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

Performance issues?

  • Enable WebWorker mode (Beacon — default)
  • Use the Gateway for edge enforcement
  • Review the Middleware docs for caching options

Get Help

Getting Started

Learn how to integrate Checkpoint into your application

Credentials

Where to find your Project ID and API key, and which env var each Checkpoint plane reads

On this page

Prerequisites5-Minute SetupNext.js Quick Start1. Install the package2. Create middleware3. Add environment variables4. DeployExpress Quick Start1. Install the package2. Add middleware3. Add environment variables4. Run your serverASP.NET Core Quick Start1. Install the package2. Add middleware3. Add configuration4. Run your applicationJavaScript Beacon Quick Start1. Install the package2. Initialize the beacon3. Track custom events (optional)4. Track page unload (optional)Google Tag Manager Quick Start1. Install the template2. Create a new tag3. Set up triggers4. PublishVerify InstallationCheck the DashboardCheck Network RequestsEnvironment VariablesNext StepsTroubleshootingNot detecting agents?Too many false positives?Performance issues?Get Help