Start offline with npx. No monorepo clone. No paid cloud for the demo.
Then wire MCP, run a free local console, or use hosted. Tools are keyed by
toolId. Sole PEP: ALLOW / DENY / REQUIRE_APPROVE.
npx @shield-agent/kya@latest --help
Dual plane: tag sessions host=ide (authoring) or host=runtime (production).
Same identity, policy, approval, and trail.
Node 24+. No Java. No Postgres. Zero vertical packs. Older Node? The CLI offers to install 24 and finish for you. First see DENY, then REQUIRE_APPROVE, without a paid plane.
# One liner - init + wire MCP + open live activity report
npm i -g @shield-agent/kya@latest
cd your-project
kya start
# Cursor loads shield-kya live - no restart. Claude Code: `claude --resume`
# keeps your conversation. Per-host reload behavior: /integrations
# The report runs in the background - your terminal returns immediately.
# `kya stop` stops it; `kya receipt --open` reopens it.
# Optional offline sample (not production PEP)
kya eval-tool --offline --tool-id org.sample.never.event --irreversible
# → DENY
kya wrap --offline --tool-id Write --irreversible --args '{"path":"src/x.ts","content":"hi"}'
# → observed REQUIRE_APPROVE (no second Hold by default)
Default wrap is observe (records the trail, no second approve).
Org Hold path: KYA_HOLD=1. Live report: kya receipt --open.
A hosted plane starts when you set KYA_BASE_URL + KYA_API_KEY.
Walkthrough: How KYA works.
Full guide:
/docs/kya/light-install
· npm @shield-agent/kya
· source The-Pixel-Boys/shield-kya
· fail closed: empty API key against an auth plane exits non-zero (use --offline for local sample).
npm stays the reference path. Same package, other channels. Locally KYA is advisory: it records the trail, fails open on errors, and denies only a small never-list. Enforcement lives on the MCP gate path and the hosted plane.
# Claude Code plugin (advisory, fails open; records the trail, blocks only the never-list)
/plugin marketplace add The-Pixel-Boys/shield-kya
/plugin install kya@shield-kya
# Homebrew (Homebrew 7 may ask you to trust the tap: `brew tap The-Pixel-Boys/tap` first)
# The formula installs about 270MB because of the optional semantic-search runtime.
brew install The-Pixel-Boys/tap/shield-kya
# Scoop (not yet verified on Windows)
scoop bucket add The-Pixel-Boys https://github.com/The-Pixel-Boys/scoop-bucket.git
scoop install shield-kya
Bring AGT logs in with kya import --from agt;
the hosted console accepts the same format
(import guide).
MCP works on Cursor, Copilot, Claude-class, Codex-class, and custom runtimes. Those names are examples.
{
"mcpServers": {
"shield-kya": {
"command": "npx",
"args": ["-y", "@shield-agent/kya", "serve-mcp", "--stdio"],
"env": {
"KYA_BASE_URL": "http://127.0.0.1:8090",
"KYA_API_KEY": "${KYA_API_KEY}",
"KYA_HOST": "ide"
}
}
}
}
Fallback from source:
npx --yes -p github:The-Pixel-Boys/shield-kya kya serve-mcp --stdio.
Tools: kya.policy_evaluate · kya.session_ingest · kya.request_approval
(request only. It never executes the side effect).
Descriptor: /connectors/mcp.json
· public repo: The-Pixel-Boys/shield-kya
· MCP notes in light install.
Two more ways the same evaluate path reaches your agents - no account, no paid plane.
One loopback-only listener in front of any MCP server. Per-tool policy is
generated from the top-20 server taxonomy: destructive and ADMIN-tier tools
are denied outright, everything else is audited into the report.
kya gate init → setup → run, then
kya connect <host> --gate. Server matrix:
mcp-servers.md.
Building agents on LangGraph, the Vercel AI SDK, Mastra, OpenAI Agents, the
Claude Agent SDK, or a Python framework? Wrap the tool callable with
governed() - ALLOW runs, DENY never runs, every call lands on
the trail. Recipes:
sdk-integrations.md.
Want Approvals UI + Postgres + policy playground on your machine at $0 paid SaaS?
Run the free local stack, then point KYA_BASE_URL at it.
Docker/Podman for Postgres 16; SDKMAN or equivalent for Java 25.
Seeded local login for non-prod. Create an API key under Settings.
npx @shield-agent/kya@latest with
KYA_BASE_URL=http://127.0.0.1:8090.
Multi-tenant density, pin/private registry, ORR board ops, and support. Never required for the day-1 npx path. Hosted extras stay optional.
What next: one shared plane, API keys per team or runtime, laptops on
host=ide, production on host=runtime.
Wrap the writes that matter. Operators live on Approvals, Sessions, and Agents.
Unwrapped tools stay invisible. Location (office or vendor cloud) does not change the rules.
Security reviews: map Shield to OWASP MCP governance (owner, logging, scope, meaningful Hold). See the public OWASP map in the KYA docs. Org MCP inventory and Tier scoring are on the hosted roadmap.
Click install on Claude, ChatGPT, Grok, Gemini, AWS, Azure, or GCP when listings are available. Same MCP, OpenAPI, and OAuth standards. There is no private Shield protocol.
23 host recipes - connect, config, or wrap. See /integrations.
AWS · Azure · GCP SaaS contracts when you buy there. Entitlements stay with the cloud.
MCP, OpenAPI, OAuth 2.1 / OIDC, generic webhooks. Any host that speaks those.
Shield KYA evaluates. Scanners and edges write evidence or run after APPROVED. They do not ALLOW a high-stakes tool on their own.
Stable toolId plus metadata. Creating an agent is kya.agent.register. Vertical packs are optional.
Principals, evaluates, approvals, orphans. We do not sell quality or speed scores.