Install · Know Your Agent

Start with one command

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

Start with npx MCP snippet

Dual plane: tag sessions host=ide (authoring) or host=runtime (production). Same identity, policy, approval, and trail.

Path 1 · preferred day-1

Offline-friendly npx (15 minutes)

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)

KYA activity receipt — agent tool trail with Allow, Deny, and Hold

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

Path 2

MCP snippet (any host)

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.

OSS · in the kya CLI

kya gate & SDK shims

Two more ways the same evaluate path reaches your agents — no account, no paid plane.

kya gate — local MCP gateway

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.

SDK shims — in-process governance

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.

Path 3 · full local free

Laptop console (secondary)

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.

1. Postgres + Java 25

Docker/Podman for Postgres 16; SDKMAN or equivalent for Java 25.

2. Boot console on :8090

Seeded local login for non-prod. Create an API key under Settings.

3. Wire light CLI

npx @shield-agent/kya@latest with KYA_BASE_URL=http://127.0.0.1:8090.

Solo free local guide →

Path 4 · enterprise hosted

Hosted console (third)

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.

Optional · marketplaces

Where your agents already run

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.

Agent platforms

23 host recipes — connect, config, or wrap. See /integrations.

Cloud marketplaces

AWS · Azure · GCP SaaS contracts when you buy there. Entitlements stay with the cloud.

Standards only

MCP, OpenAPI, OAuth 2.1 / OIDC, generic webhooks. Any host that speaks those.

How we decide

Sole PEP

Shield KYA evaluates. Scanners and edges write evidence or run after APPROVED. They do not ALLOW a high-stakes tool on their own.

Your own tools

Stable toolId plus metadata. Creating an agent is kya.agent.register. Vertical packs are optional.

What we count

Principals, evaluates, approvals, orphans. We do not sell quality or speed scores.

Light install guide → How KYA works