Checkpoint Docs

Quick Start

Get Checkpoint running in 5 minutes

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/agentshield-nextjs

2. Create middleware

Create middleware.ts in your project root:

import { withAgentShield } from '@kya-os/agentshield-nextjs/api-middleware';

export default withAgentShield({
  apiKey: process.env.AGENTSHIELD_API_KEY,
});

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

3. Add environment variables

# .env.local
AGENTSHIELD_API_KEY=your_api_key_here

Find your API Key in the Checkpoint Dashboard under the Deployment tab.

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/agentshield-express

2. Add middleware

import express from 'express';
import { createEnhancedAgentShieldMiddleware } from '@kya-os/agentshield-express';

const app = express();

app.use(createEnhancedAgentShieldMiddleware({
  projectId: process.env.CHECKPOINT_PROJECT_ID!,
  apiKey: process.env.CHECKPOINT_API_KEY!,
}));

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.

JavaScript Beacon Quick Start

1. Install the package

npm install @kya-os/agentshield-beacon

2. Initialize the beacon

import { AgentShieldBeacon } from '@kya-os/agentshield-beacon';

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

// Start detection
await beacon.start();

3. Listen for detection results (optional)

beacon.on('detection', (result) => {
  console.log(`Detected: ${result.detectionClass} (${result.confidence}%)`);
});

4. Track custom events (optional)

beacon.track({
  type: 'form_submit',
  metadata: {
    form_id: 'signup',
    page: window.location.pathname,
  },
});

The beacon is now detecting AI agents with WebWorker offloading for zero UI impact.

Google Tag Manager Quick Start

1. Import the template

  1. In GTM, go to Templates → Tag Templates
  2. Click Search Gallery
  3. Search for "Checkpoint" (or "AgentShield")
  4. Click Add to Workspace

2. Create a new tag

  1. Go to Tags → New
  2. Choose the Checkpoint Pixel template
  3. Configure:
    • Project ID: Your Project ID from the dashboard

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. Go to the Monitor tab
  4. You should see detections appearing in 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
AGENTSHIELD_API_KEY=your_api_key_here       # Server-side only
CHECKPOINT_PROJECT_ID=your_project_id_here  # Client-side pixel only

Keep your API Key secret. Never expose it in client-side code. The Project ID is safe to use in client-side integrations (Pixel, Beacon).

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 (MCP-I) — 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?

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

Choose Your Integration

Pick the right Checkpoint integration for your stack — Detect traffic, Enforce policies, or Govern AI agent access

On this page

5-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 serverJavaScript Beacon Quick Start1. Install the package2. Initialize the beacon3. Listen for detection results (optional)4. Track custom events (optional)Google Tag Manager Quick Start1. Import 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