The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Shield Kya listing page.
@shield-agent/kyaCLI and local MCP gate for Shield’s Know Your Agent path.
If 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.
Walkthrough: how you use it.
Requires Node.js 24+ (engines.node: >=24).
It 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.
If 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.
--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.
Install hub: https://shield-agent.com/install
Tag sessions with KYA_HOST=ide or KYA_HOST=runtime. Same policy path either way.
| Variable | Required | Meaning |
|---|---|---|
KYA_BASE_URL | Yes (network cmds) | Control plane origin |
KYA_API_KEY | When auth is on | API key (or Bearer JWT for decide verbs) |
KYA_HOST | No (default ide) | ide | runtime |
KYA_AGENT_ID | After register | Agent principal id |
KYA_MCP_PORT | No (default 3920) | HTTP MCP listen port |
KYA_OFFLINE | No | 1/true for sample evaluate |
KYA_DASH_PLAN | No | enterprise unlocks licensed TUI panes |
| Tool | Role |
|---|---|
kya.policy_evaluate | ALLOW | DENY | REQUIRE_APPROVE |
kya.session_ingest | Observe / raise-only risk |
kya.request_approval | Open a human Hold. Does not execute the side effect |
MCP Registry entry: server.json plus package mcpName io.github.The-Pixel-Boys/shield-kya.
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).
Desktop / Claude Code (local stdio):
Copy 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.
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).
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".
Responses API: see openai/responses-mcp.example.json (server_url + Authorization: Bearer <KYA_API_KEY>).
ChatGPT Apps (chatgpt.com): deferred. Developer Mode wants OAuth. Use Codex until then.
Merge 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.
Hosted 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.
The package includes .cursor-plugin/plugin.json, mcp.json, and a wrap skill. Public listing repo: https://github.com/The-Pixel-Boys/shield-kya
ORR 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.
Beside the gate, not inside MCP. Opt-in only:
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.
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.
Pin, private registry, multi-tenant density, ORR board ops, and support are not required for the day-1 npx path above.
LIMITATIONS.md in this repoOpt-in. Default off.
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.
Hosted plane: richer Micrometer gauges and timers when KYA_OTLP_ENABLED=true.
Full env, Grafana/Datadog notes, forbid list, and a Collector sample: docs/otlp.md.