---
name: checkpoint
description: Set up and run Checkpoint, Vouched's AI-agent detection and enforcement, in this repository with the kya-os CLI. Use when asked to add Checkpoint or to detect or block AI agents and bots, when .kya-os/project.json exists, when a kya-os command fails, or when a task mentions CHECKPOINT_API_KEY.
---

# checkpoint: set up Checkpoint with kya-os

Checkpoint classifies every visitor to a web app (human, AI agent, bot) and
applies the project's policy to them. The `kya-os` CLI signs a person in,
links the repository to a Checkpoint project, and adds Detect to the code.
This file is the decision tree: trigger → command → what to hand the human.

Two things are never yours to do:

- **Sign in.** `kya-os setup` and `kya-os login` open a browser (or print a
  device code) that the human approves. Print the command and let them run it.
- **Handle an API key.** Never ask for, print, log, or commit one. The human
  either lets `kya-os detect install --surface sdk` mint one into a gitignored
  env file, or enters one with `kya-os checkpoint key set`, which prompts with
  hidden input.

## When to invoke this skill

| Trigger                                                          | Section   |
| ---------------------------------------------------------------- | --------- |
| Asked to add Checkpoint, AI-agent detection, or bot protection   | 1, then 2 |
| `.kya-os/project.json` exists and you're unsure what's installed | 1         |
| Choosing between the pixel, the beacon, and the server SDK       | 3         |
| Asked to block or restrict agents, not only see them             | 4         |
| Asked to see or govern what a coding agent does here             | 6         |
| A `kya-os` command failed                                        | 5         |

Outside these triggers, do nothing.

## 1. Check state

```bash
command -v kya-os && kya-os --version
cat .kya-os/project.json        # the linked project: no secret, safe to read and commit
kya-os whoami                   # exits non-zero when nobody is signed in on this machine
```

- `kya-os` not found → section 2. If `~/.kya-os/bin/kya-os` exists, it's
  installed and only this shell's PATH lacks it: run section 2's `export`.
- No `.kya-os/project.json` → the repository isn't linked → section 2.
- Linked, but `whoami` fails → print `kya-os login` for the human.
- Linked and signed in → `kya-os detect install --dry-run` shows what's in
  place and what isn't.

## 2. Setup

Installing the CLI is safe to run yourself: it writes `~/.kya-os/bin/kya-os`
and puts it on PATH for new shells, nothing else.

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

A shell that was already open, yours included, may not see the new PATH.
Keep that `export` in front of later `kya-os` commands, or call
`~/.kya-os/bin/kya-os` directly.

Then hand the human the one command that needs them, run from the app's
directory:

```bash
kya-os setup                 # browser sign-in, project choice, then the Detect install
kya-os setup --device        # the same, approved from another device (SSH, containers)
```

A terminal they opened before the install needs the same `export` first.

`setup` prints its plan and asks before changing anything. With several
projects it asks which one; name it up front with `--project <id or name>`.
A name no project has yet is offered for creation when the human signs in.

What `setup` writes:

- `.kya-os/project.json`, the link. Commit it.
- The Detect install for the stack (section 3). Existing files only gain one
  block, marked `Checkpoint Detect`, and a rerun changes nothing.
- Nothing secret, anywhere in the repository.

## 3. Choosing a surface

`kya-os detect install --surface <pixel|beacon|sdk>` adds a surface to a
linked repository. The pixel is the default.

| Stack                            | Default                                  | For full coverage                                                        |
| -------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------ |
| Next.js                          | pixel `<Script>` in the root layout      | `sdk`: `proxy.ts` (Next.js 16+) or `middleware.ts`                       |
| Express 4                        | pixel, added by hand to your HTML        | `sdk`: the package, plus a mount line to add by hand                     |
| Express 5                        | pixel, added by hand                     | none yet: the SDK supports Express 4 only                                |
| ASP.NET Core (net8.0+)           | pixel, added by hand to `_Layout.cshtml` | `sdk`: the package, plus `Program.cs` lines to add by hand               |
| .NET Framework 4.6.2 to 4.8.1    | pixel, added by hand to `_Layout.cshtml` | `sdk`: the package, plus `Web.config` settings and module to add by hand |
| Java 21+                         | pixel, added by hand to your template    | `sdk`: a Maven or Gradle line to add by hand                             |
| Static site, Vite SPA, SvelteKit | pixel before `</head>`                   | `beacon` for richer browser signals                                      |

The pixel and the beacon take only the project ID, which is public. The
server SDK sees every request, including agents that never run JavaScript,
and needs the project's runtime key in the app's environment. When the human
is signed in, `kya-os detect install --surface sdk` asks, then mints the key
into a gitignored `.env.local` (Next.js) or `.env` (Express). Minting a
credential is the human's call, so print the command rather than adding
`--yes` yourself. For other stacks, or a key the human already has, print
`kya-os checkpoint key set`.

Lines the CLI prints to add "by hand" are ordinary code edits: make them, and
show the diff.

## 4. Enforcement

A new project observes: it records a verdict for every visitor and blocks
nothing until someone publishes a policy in the dashboard. Don't write
blocking logic into the app. Point the human at their project's policy page
and https://kya.vouched.id/docs/enforce/policies.

## 5. When a command fails

| Output contains                                        | What to do                                                                                                                                                                                                                      |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Not signed in`, or `ended the management session`     | Print `kya-os login` for the human                                                                                                                                                                                              |
| `covers N projects. Choose one with --project`         | Rerun with `--project` and one of the listed IDs, or with a new name, which the human creates when signing in                                                                                                                   |
| `is not one of the projects this sign-in was granted`  | Print `kya-os login --project <id or name>`; the human grants it on the consent page, or creates it there                                                                                                                       |
| `was granted no projects`                              | Print `kya-os setup`; the human creates or chooses a project on the consent page                                                                                                                                                |
| `Ignoring .kya-os/project.json: it links a project on` | The link targets another Checkpoint. Set `CHECKPOINT_API_URL` to that origin, or have the human relink with `kya-os projects use <id>`                                                                                          |
| `credential store is locked or inaccessible`           | macOS: the human unlocks the Keychain and allows access. A Linux server without a keyring: the human signs in on a workstation; on the server, `kya-os detect install --project <id>` needs no sign-in for the pixel and beacon |
| `not applied without a terminal; re-run with --yes`    | Show the human the printed plan; rerun with `--yes` once they approve it                                                                                                                                                        |
| `needs this project's runtime key`                     | Print `kya-os login` for the human (the CLI then mints the key), or `kya-os checkpoint key set`                                                                                                                                 |
| `API key limit is reached`                             | The human revokes an unused key in the dashboard, or stores an existing one with `kya-os checkpoint key set`                                                                                                                    |
| `ERESOLVE`, or `Express 5`                             | Keep the pixel; the server SDK supports Express 4 only                                                                                                                                                                          |
| `could not run npm` (or pnpm, yarn, bun, dotnet)       | That tool isn't on PATH. Install it, or run the printed command yourself                                                                                                                                                        |
| `FAILED:` on an install step                           | Nothing after that step ran. Fix the error shown, then rerun `kya-os detect install`                                                                                                                                            |

Never delete `.kya-os/project.json` or edit `~/.mcpi/checkpoint.json` to get
past an error.

## 6. Governing a coding agent

`kya-os govern install --agent claude` adds a Claude Code hook that reports
every tool call in this repository to the project's Activity feed: the tool's
name and the session, never its input or output, observe only. It edits the
human's Claude Code settings (`.claude/settings.local.json` by default), so
print the command for them rather than running it. `kya-os govern uninstall`
removes it.

Reference: https://kya.vouched.id/docs/cli-reference ·
https://kya.vouched.id/docs/troubleshooting