Let your agent set it up
Paste one skill into Claude Code, Cursor, or any coding agent. It installs the CLI, previews the changes, and hands you the two steps only you can take.
Drop this skill into your AI coding agent and it learns how to set up and work with Checkpoint: how to tell whether a repository is already connected, which Detect surface fits the stack, which steps to hand you instead of doing itself (signing in, the API key), and what to do when a command fails. One file, one paste.
Prerequisites
- A Checkpoint account. Sign up if you don't have one; the agent hands you the browser sign-in during
kya-os setup. - A coding agent that can read a skill file and run shell commands in your repository: Claude Code, Cursor, or similar.
Prefer to run it yourself?
The skill below scripts all of this for your agent. To do it by hand, install the CLI, run setup, and add server-side detection with the project in observe mode first.
# install, and put it on this terminal's PATH too
curl -fsSL https://kya.vouched.id/install | sh
export PATH="$HOME/.kya-os/bin:$PATH"
# sign in, link this repository to a project, add Detect (the pixel)
kya-os setup
# see every request, not only browsers: the server SDK (it mints the app's key)
kya-os detect install --surface sdk
# check what's connected
kya-os whoamiThe Quickstart walks through each step.
What this skill sets up
Detect
The pixel, the beacon, or the server SDK for your stack, written into your code after you approve the plan.
Sign-in and project link
A browser sign-in kept in your OS keychain, and a committed .kya-os/project.json so teammates
get the same project.
Observe-first enforcement
Server-side verdicts that are recorded but block nothing until you publish a policy.
Dashboard
Every visit and verdict in your project's Activity feed.
How to use this skill
Copy the SKILL.md below with the copy button, or download it from
/skills/checkpoint/SKILL.md.
Save it to your agent's skills directory. For Claude Code: ~/.claude/skills/checkpoint/SKILL.md
for every project, or .claude/skills/checkpoint/SKILL.md to ship it with this repository.
mkdir -p ~/.claude/skills/checkpoint
curl -fsSL https://kya.vouched.id/skills/checkpoint/SKILL.md -o ~/.claude/skills/checkpoint/SKILL.mdAsk your agent: "set up Checkpoint in this repo". It loads the skill, checks what's already
there, installs the CLI, and prints the commands for you to run: kya-os setup to sign in and
approve the plan, and kya-os detect install --surface sdk if you want the server SDK, which
mints the app's key once you confirm. A sign-in and a credential belong to you, so the skill has
your agent hand those over rather than run them.
Agents without a skills directory can read it from their instructions file (AGENTS.md, .cursorrules, .windsurfrules):
Read https://kya.vouched.id/skills/checkpoint/SKILL.md and follow it for Checkpoint setup.SKILL.md
---
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/troubleshootingThe file above is the complete skill. Save it as SKILL.md under your agent's skills directory and it loads automatically.
Next steps
Quickstart
The same setup, step by step, in about five minutes.
Core Concepts
Detections versus verdicts, observe-first rollout, and where identity comes in.
Frequently asked questions
How do I set up Checkpoint using my AI coding agent?
Save the skill above into your agent's skills directory (Claude Code, Cursor, or any agent that reads skill or instruction files) and ask it to set up Checkpoint. It installs the CLI, works out which surface fits your stack, and prints the commands that need you: signing in, and entering the API key if you want server-side detection.
Which AI coding agents can use the skill?
Any agent that can read a markdown instruction file and run shell commands, including Claude Code, Cursor, Codex, and Windsurf. The skill is plain markdown with the exact commands, so agents without a skills directory can read it from AGENTS.md or .cursorrules.
Why doesn't the agent sign in or enter the API key for me?
Signing in approves a session in your name, and the API key authenticates your app's traffic. Both are yours. kya-os setup opens your browser for the sign-in, and kya-os detect install --surface sdk mints the app's key only after you confirm, writing it to a gitignored env file, so the key never passes through the agent's context or your shell history.
Do I need the skill at all?
No. The Quickstart is the same flow by hand. The skill's value is that your agent picks the right surface for your stack and makes the by-hand edits the CLI prints for Express, ASP.NET, and Java.