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 Vouched KYA 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 Vouched KYA account and an app you can run locally or deploy. The CLI supports macOS, Linux, and Windows through WSL; Installation covers platforms and supported stacks.

Open a terminal in your app's folder

kya-os setup detects your stack from the files in the folder it runs in, and links that folder to a Vouched KYA project. Open a terminal and go to the folder that holds your app's manifest, such as package.json, a .csproj, pom.xml or build.gradle:

cd ~/code/my-app

Run the commands below from this folder.

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: run kya-os setup

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 folder:

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

The server SDK runs as middleware in your app. The CLI can add it to these backends:

BackendSupported versions
Next.jsApp Router and Pages Router
ExpressExpress 4 only
ASP.NETASP.NET Core on .NET 8 or later, and ASP.NET on .NET Framework 4.6.2 to 4.8.1
JavaJava 21 or later, built with Maven or Gradle, on a servlet container or the JDK HTTP server

Express 5, Vite SPAs, SvelteKit, and static sites have no server SDK. On those, keep the Pixel and skip to verifying the browser visit below, or put the Gateway in front of your site.

For a supported backend, run this in the same folder:

kya-os detect install --surface sdk

What the CLI does, and what's left for you, depends on your backend:

The CLI installs @kya-os/checkpoint-nextjs and creates proxy.ts (Next.js 16+) or middleware.ts at your project root, or in src/ when the app uses a src/ directory.

  • Existing middleware: the CLI never overwrites a proxy.ts or middleware.ts it didn't write. It prints the lines to combine into yours.
  • API key: when you're signed in, the CLI offers to create CHECKPOINT_API_KEY, adds .env.local to .gitignore, and writes the key there.
  • Mode: enforcement follows your dashboard policy. For a first rollout, deploy the policy in observe mode.

The Next.js tab in Installation shows the middleware file.

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.

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 200) 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

Frequently asked questions

How long does it take to set up Vouched KYA?

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, Express, and ASP.NET Core, 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.