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 identified by a toolId. Every tool call gets one answer: ALLOW, DENY, or REQUIRE_APPROVE.

npx @shield-agent/kya@latest --help

Start with npx MCP snippet

Two environments: tag sessions host=ide (while you build) or host=runtime (in production). Same identity, policy, approval, and trail.

Path 1 · preferred day-1

Offline-friendly npx (15 minutes)

Node 22+ (24 recommended). No Java. No Postgres. No add-on packs. Older Node? The CLI offers to install 24 and finish for you. First see DENY, then REQUIRE_APPROVE, without a paid console.

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

# Permission denied (EACCES) on Linux? No sudo and no install needed:
npx @shield-agent/kya@latest start

# Optional offline sample (not the production gate)
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)

Install fails with EACCES? The global npm folder belongs to root (common on Linux). Do not use sudo. Run without a global install: npx @shield-agent/kya@latest start. Or give npm a folder you own: npm config set prefix ~/.npm-global, add ~/.npm-global/bin to your PATH, then run the install again.

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

Default wrap is observe: it records the trail without a second approval. To hold risky actions for a person, set KYA_HOLD=1. Live report: kya receipt --open. The hosted console starts receiving events when you set KYA_BASE_URL and 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: an empty API key against a console that requires sign-in exits with an error (use --offline for a local sample).

More ways to install

npm stays the reference path. Same package, other channels. Locally KYA is advisory: it records the trail, lets work continue if something fails, and blocks only the never-list and the guard pack (destructive shell commands, secret access, exfiltration). Real blocking runs on the MCP policy path against a hosted workspace.

# Claude Code plugin (advisory: records the trail, lets work continue on errors, blocks the never-list and the guard pack)
/plugin marketplace add The-Pixel-Boys/shield-kya
/plugin install kya@shield-kya

# Codex CLI plugin (same behaviour; then trust the two Shield KYA hooks in /hooks)
codex plugin marketplace add The-Pixel-Boys/shield-kya
codex plugin add kya@shield-kya

# Homebrew (Homebrew 7 may ask you to trust the tap: `brew tap The-Pixel-Boys/tap` first)
# The formula is small. Semantic search is opt-in; without it, search stays lexical.
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

# Gemini CLI extension (same behaviour; Gemini runs its hooks without a trust step)
gemini extensions install https://github.com/The-Pixel-Boys/shield-kya

Bring AGT logs in with kya import --from agt; the hosted console accepts the same format (import guide).

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 policy check reaches your agents. No account. No paid console.

kya gate - local MCP gateway

One local-only listener in front of any MCP server. A starter policy is generated for the most common servers: destructive and admin-level tools are denied, and everything else is recorded in the report. kya gate init → setup → run, then kya connect <host> --gate. Server matrix: mcp-servers.md.

SDK shims - inside your agent code

Building agents on LangGraph, the Vercel AI SDK, Mastra, OpenAI Agents, the Claude Agent SDK, or a Python framework? Wrap the tool function 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)

Many workspaces on one deployment, pinned or private agent registries, operational reviews, and support. Never required for the day-1 npx path. Hosted extras stay optional.

What next: one shared console, one API key per team or runtime, laptops on host=ide, production on host=runtime. Wrap the writes that matter. Operators work in 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 · agent hosts

Where your agents already run

Connect Claude, ChatGPT, Grok, or Gemini hosts through MCP and OpenAPI connectors. These are connectors, not directory listings. Same MCP, OpenAPI, and OAuth standards. There is no private Shield protocol.

Agent platforms

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

Standards only

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

How we decide

One decision point

Shield KYA makes the decision. Scanners and edge steps write evidence or run after approval. They never allow a risky tool on their own.

Your own tools

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

What we count

Registered agents, policy checks, approvals, and orphaned agents. We do not sell quality or speed scores.

Light install guide → How KYA works