{
  "markdown": "# `@shield-agent/kya`\n\nCLI and local MCP gate for Shield’s Know Your Agent path.\n\nIf an agent can change a real system, it has to ask Shield first. You register the agent, wrap the tool, and get Allow, Hold, or Deny. Hold waits for a person. This package does not scan your network. Agents that never call evaluate stay invisible on purpose.\n\nWalkthrough: [how you use it](https://shield-agent.com/how-kya-works#using).\n\n```bash\nnpx @shield-agent/kya@latest --help\n```\n\nRequires **Node.js 24+** (`engines.node: >=24`).\n\nIt works with any host that speaks MCP or OpenAPI. Vertical packs are optional. Shield is the only policy decision point: this gate never auto-approves an irreversible side effect.\n\nIf `KYA_API_KEY` is empty against an authenticated plane, network commands exit non-zero. `eval-tool`, `wrap`, and `invoke` exit `0` on ALLOW, `4` on REQUIRE_APPROVE, and `1` on DENY or unknown, so a line like `eval-tool && write` cannot skip the gate.\n\n`--offline` runs sample evaluate without a paid cloud (useful for DENY and REQUIRE_APPROVE demos). Creating an agent is itself a tool: offline, `kya.agent.register` comes back REQUIRE_APPROVE. Allow, break-glass, and approve mint modes live on the control plane.\n\n## 15-minute path\n\n```bash\n# Offline demo (no account, no monorepo)\nnpx @shield-agent/kya eval-tool --offline --tool-id org.sample.never.event --irreversible\n# → verdict: DENY\nnpx @shield-agent/kya eval-tool --offline --tool-id org.sample.data.write --irreversible\n# → verdict: REQUIRE_APPROVE\n\n# Scaffold + local plane\nnpx @shield-agent/kya init\nnpx @shield-agent/kya eval-tool --offline --tool-id kya.agent.register --irreversible\n# → verdict: REQUIRE_APPROVE\nnpx @shield-agent/kya register-agent --name solo-builder --version-hash dev-local\nnpx @shield-agent/kya eval-tool --tool-id org.sample.never.event --irreversible\nnpx @shield-agent/kya serve-mcp --stdio\n\n# Terminal desk (FREE personal panes; --offline works without a key)\nnpx @shield-agent/kya dash --once --offline\n# Interactive TTY: 1-8 panes, e force-eval, p auto-refresh, y confirms kill/shrink/decide\nnpx @shield-agent/kya dash\n```\n\n\nInstall hub: [https://shield-agent.com/install](https://shield-agent.com/install)\n\n## Dual plane\n\n```\n host=ide (authoring)          host=runtime (production)\n        │                              │\n        └────────── same agent ────────┘\n                    identity\n                    policy evaluate  → ALLOW | DENY | REQUIRE_APPROVE\n                    approval + trail\n```\n\nTag sessions with `KYA_HOST=ide` or `KYA_HOST=runtime`. Same policy path either way.\n\n## Environment\n\n| Variable | Required | Meaning |\n|----------|----------|---------|\n| `KYA_BASE_URL` | Yes (network cmds) | Control plane origin |\n| `KYA_API_KEY` | When auth is on | API key (or Bearer JWT for decide verbs) |\n| `KYA_HOST` | No (default `ide`) | `ide` \\| `runtime` |\n| `KYA_AGENT_ID` | After register | Agent principal id |\n| `KYA_MCP_PORT` | No (default `3920`) | HTTP MCP listen port |\n| `KYA_OFFLINE` | No | `1`/`true` for sample evaluate |\n| `KYA_DASH_PLAN` | No | `enterprise` unlocks licensed TUI panes |\n\n## MCP tools\n\n| Tool | Role |\n|------|------|\n| `kya.policy_evaluate` | `ALLOW` \\| `DENY` \\| `REQUIRE_APPROVE` |\n| `kya.session_ingest` | Observe / raise-only risk |\n| `kya.request_approval` | Open a human Hold. Does not execute the side effect |\n\nMCP Registry entry: `server.json` plus package `mcpName` `io.github.The-Pixel-Boys/shield-kya`.\n\n```json\n{\n  \"mcpServers\": {\n    \"shield-kya\": {\n      \"command\": \"npx\",\n      \"args\": [\"--no-install\", \"@shield-agent/kya@0.1.23\", \"serve-mcp\", \"--stdio\"],\n      \"env\": {\n        \"KYA_BASE_URL\": \"http://127.0.0.1:8090\",\n        \"KYA_API_KEY\": \"${KYA_API_KEY}\",\n        \"KYA_HOST\": \"ide\"\n      }\n    }\n  }\n}\n```\n\n## Wrap and decide\n\n```bash\nnpx @shield-agent/kya wrap --offline --tool-id org.sample.data.write --irreversible\nnpx @shield-agent/kya approve --id <approval-id>\nnpx @shield-agent/kya reject --id <approval-id>\n```\n\n`wrap` evaluates and may open a pending ticket. It never executes the side effect. `invoke` asks the live plane to authorize after Allow or APPROVED. It does not run the write on this machine. The TUI (`dash`) can `a`/`x` decide only after `y` confirm with a JWT (`sk_*` refused).\n\n## Claude connector\n\n**Desktop / Claude Code (local stdio):**\n\n```bash\n# Prefer a preinstalled package (no registry auto-install):\nnpx --no-install @shield-agent/kya@0.1.23 serve-mcp --stdio\n# Or after npm i -g / local install:\nkya serve-mcp --stdio\n```\n\nCopy `claude/claude_desktop_config.example.json` into Claude Desktop MCP settings, or use `.mcp.json` for Claude Code. Pack a Desktop extension with `npx @anthropic-ai/mcpb pack` (see `manifest.json`). That pack runs the packed `dist/cli.js`, not `npx -y`.\n\n**Claude.ai / Cowork (hosted):** add a custom connector at `https://shield-agent.com/mcp` with request header `Authorization: Bearer <KYA_API_KEY>` (or `X-API-Key`). It is not Directory-listed yet (API-key auth, no OAuth DCR).\n\n## OpenAI (Codex / Responses)\n\n**Codex CLI / IDE:** copy `openai/codex.config.example.toml` into `~/.codex/config.toml`. Local stdio uses `npx --no-install @shield-agent/kya@0.1.23 serve-mcp --stdio`. Hosted Codex uses `url = \"https://shield-agent.com/mcp\"` with `bearer_token_env_var = \"KYA_API_KEY\"`.\n\n**Responses API:** see `openai/responses-mcp.example.json` (`server_url` + `Authorization: Bearer <KYA_API_KEY>`).\n\n**ChatGPT Apps (chatgpt.com):** deferred. Developer Mode wants OAuth. Use Codex until then.\n\n## Gemini CLI\n\nMerge `gemini/settings.example.json` (stdio) or `gemini/settings.hosted.example.json` (`httpUrl` + Bearer) into `~/.gemini/settings.json` or `.gemini/settings.json`. Do not enable both at once.\n\n## Grok\n\nHosted custom connector: `https://shield-agent.com/mcp` (see `grok/README.md`). Grok rejects localhost. Prefer a Bearer machine key when the UI offers a request header. For a local agent host, use the same stdio launch as Claude/Codex/Gemini.\n\n## Cursor plugin\n\nThe package includes `.cursor-plugin/plugin.json`, `mcp.json`, and a wrap skill. Public listing repo: https://github.com/The-Pixel-Boys/shield-kya\n\n## ORR (reporting only)\n\n```bash\nnpx @shield-agent/kya orr run --path . --out ./orr-report --skip-optional-producers\nnpx @shield-agent/kya orr run --path . --out ./orr-report --scorecard ./scorecard.json --producer openssf.scorecard\nnpx @shield-agent/kya orr run --path . --out ./orr-report --producer harness.agentshield --agentshield-json ./agentshield-report.json\n```\n\nORR is a reporting board. Scanners, `--scorecard`, and `harness.agentshield` are evidence. They never ALLOW a high-stakes side effect, so they are not a second policy gate. AgentShield is optional and read-only: no `--fix`, no MiniClaw, no runtime hook. This package does not depend on `ecc-agentshield`. If you pass `--producer harness.agentshield` and have neither `--agentshield-json` nor an `agentshield` binary, ORR records a coverage gap and still exits 0. Explicit `--producer` always attempts; `--skip-optional-producers` only skips producers you did not ask for.\n\n## Optional sandbox wrap (Firecracker)\n\nBeside the gate, not inside MCP. Opt-in only:\n\n```bash\nKYA_SANDBOX=mock kya sandbox spawn\nKYA_SANDBOX=mock kya sandbox exec --sandbox-id <id> --cmd \"true\"\nKYA_SANDBOX=mock kya sandbox kill --sandbox-id <id>\n```\n\n`org.sample.sandbox.exec` without `--sandbox-id` is **DENY** `MISSING_SANDBOX_ID`. Real Firecracker needs `firecracker` + `jailer` on PATH and kernel/rootfs env (`KYA_SANDBOX_KERNEL`, `KYA_SANDBOX_ROOTFS`). We do not ship those binaries. `serve-mcp` still exposes only evaluate / ingest / request_approval.\n\n## Cost showback (observe only)\n\n`kya orr run --usage ./usage.json` (or `.kya/usage.json`) adds a showback section: tokens and estimated USD by agent and run. Subagents nest under `parentRunId`. That section is not a billing meter and not a policy gate. Hosted metrics show the same rollup when usage is ingested with a session.\n\n## Enterprise (separate tier)\n\nPin, private registry, multi-tenant density, ORR board ops, and support are not required for the day-1 `npx` path above.\n\n## Develop\n\n```bash\npnpm install\npnpm test\npnpm build\n```\n\n## Docs\n\n- [Install hub](https://shield-agent.com/install)\n- [How KYA works](https://shield-agent.com/how-kya-works)\n- [OTLP metrics (OSS + hosted)](docs/otlp.md)\n- [OWASP MCP governance map](docs/owasp-mcp-governance.md)\n- [Hosted operator SSO / SCIM (not in OSS CLI)](docs/hosted-operator-sso.md)\n- See also `LIMITATIONS.md` in this repo\n\n## OTLP (optional)\n\nOpt-in. Default off.\n\n**OSS CLI:** set `KYA_OTLP_ENDPOINT` (or `OTEL_EXPORTER_OTLP_ENDPOINT`) to export thin evaluate latency (`kya.client.evaluate.latency`) with tags `verdict` and `host` only. No tool args or API keys.\n\n**Hosted plane:** richer Micrometer gauges and timers when `KYA_OTLP_ENABLED=true`.\n\nFull env, Grafana/Datadog notes, forbid list, and a Collector sample: [`docs/otlp.md`](docs/otlp.md).\n",
  "bytes": 8970,
  "sha": "58b0bf0f0016eb57a2ede920118be1227c289298cec3b5637a1c161d3b87e5a3",
  "repo_slug": "the-pixel-boys/shield-kya",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_the_pixel_boys_shield_kya_763bd99a/readme"
}