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/checkpoint-nextjs2. Create middleware
Create middleware.ts in your project root:
import { withAgentShield } from '@kya-os/checkpoint-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_hereFind your API Key in the Checkpoint Dashboard under the Deployment tab.
4. Deploy
npm run build && npm run startCheckpoint 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-express2. 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.AGENTSHIELD_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
AGENTSHIELD_API_KEY=your_api_key_here4. Run your server
node app.jsYour Express application is now protected.
ASP.NET Core Quick Start
1. Install the packages
dotnet add package Checkpoint.AspNetCore
dotnet add package Checkpoint.Core2. 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();3. Add configuration
// appsettings.json
{
"Checkpoint": {
"ProjectId": "your_project_id",
"ApiKey": "your_api_key_here"
}
}4. Run your application
dotnet runYour ASP.NET Core application is now protected. See the full .NET integration guide for signature verification, MCP-I instruct mode, and more.
JavaScript Beacon Quick Start
1. Install the package
npm install @kya-os/checkpoint-beacon2. Initialize the beacon
import { CheckpointBeacon } from '@kya-os/checkpoint-beacon';
const beacon = new CheckpointBeacon({
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. Install the template
Open the AgentShield template in the Community Template Gallery (publisher: Know-That-Ai), or in GTM go to Templates → Tag Templates → Search Gallery and search for AgentShield.
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
- Go to Tags → New → Tag Configuration → Custom
- Select AgentShield Pixel
- Configure:
- Project ID: Your Project ID from the dashboard
3. Set up triggers
- Add trigger: All Pages for basic protection
- Optional: Add History Change trigger for SPAs
4. Publish
- Click Submit in the top right
- Add version description
- Click Publish
Detections will appear in your Checkpoint dashboard within seconds.
Verify Installation
After installation, verify Checkpoint is working:
Check the Dashboard
- Open the Checkpoint Dashboard
- Navigate to your project
- Go to the Monitor tab
- You should see detections appearing in real-time
Check Network Requests
- Open your browser's Developer Tools
- Go to the Network tab
- Look for requests to
kya.vouched.id - Successful requests return a
200status
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 onlyKeep 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:
- Dashboard Analytics — View detection data and trends
- Detection Methods — Understand detection approaches
- Enforcement — Set up active enforcement policies
- Govern (MCP-I) — Control AI agent access with identity
- 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 the Analyze tab
- Adjust your enforcement threshold
- Start in detect-only mode before enabling enforcement
Performance issues?
- Enable WebWorker mode (Beacon — default)
- Use the Gateway for edge enforcement
- Review the Middleware docs for caching options