What you do with it

The package is a checkpoint your agents call before a write, export, deploy, or spawn. It does not scan office Wi-Fi, a VPN, or the public internet for unknown agents. Agents that never call evaluate stay off the desk.

Same four steps on a laptop or in a company:

1. Stand up a control plane (local console or hosted).
2. Register each agent as a named principal.
3. Wrap the tools that write, export, deploy, or spawn another agent so they evaluate first.
4. When the verdict is Hold, someone works Approvals. Then the plane authorizes invoke. The agent never gets the secret.

Allow proceeds and is logged. Deny stops the call. The Policy page cards are a dry-run of that question. They are not a company-wide on/off switch.

After a local install

1. Run the offline eval. You should see DENY, then REQUIRE_APPROVE.
2. init and register-agent.
3. Add the MCP snippet in your editor with KYA_HOST=ide, or wrap one write in your own code.
4. Call the tool once. Open Approvals. Accept or Reject.
5. Optional: run the free local console on :8090 and point KYA_BASE_URL at it.

--offline is a sample. It is not the production gate. Until a real tool calls evaluate, the console looks empty or tutorial-only.

Install commands · Solo free local

After a company install

1. One shared plane (hosted or self-host). That is the census and the Approvals queue.
2. Issue API keys per team or per runtime. Do not reuse a laptop key in production.
3. Tag laptops host=ide and production bots host=runtime.
4. Wrap the writes that matter. Unwrapped tools are not governed.
5. Operators live on Approvals, Sessions, and Agents. Kill or revoke a named principal. Shrink a live session that should lose Deploy.

Hosted console · Self-host

What it sees

Location does not matter. Office LAN and a vendor cloud use the same rules. The split that matters is authoring versus production.

Covered: any agent you register that calls evaluate (internal bot, contractor laptop, SaaS runtime, marketplace MCP).

Not covered: agents that never wrap, raw network traffic, personal ChatGPT with no Shield connector, automatic discovery of shadow processes on the LAN. Orphans show only if you already have the principal.

Dual plane

One policy enforcement point for authoring and production:

Host	Intent
host=ide	Build, evaluate, observe, dry-run in IDE / CLI
host=runtime	Production agents serving real work

Same identity, policy, approval, and trail on both hosts.

Your own tools

• Govern any stable toolId. You do not need a prebuilt adapter module.
• Verdicts: ALLOW, DENY, or REQUIRE_APPROVE.
• Protocol-first install: MCP, OpenAPI / HTTP, generic webhooks.
• Vertical packs are optional accelerators.

Six layers

Layer	Capability
L1	Agent identity and lifecycle (registry, version hash, kill/revoke)
L2 to L3	Sign-in, authorization, and delegation bounds
L4	Runtime policy: ALLOW, DENY, or REQUIRE_APPROVE
L5	Behavior monitoring and kill switch
L6	Evidence graph, hash-chained event log, export

Create is a tool

Registering an agent goes through the same policy engine as any other write. A person can mint a root agent under the workspace mint mode (allow with a trail, break-glass with a reason, or require approve). When one agent creates another, that spawn is always evaluated. Missing APPROVED means no child.

Sessions can shrink

Clearance is what this session may still do: Read, Build, or Deploy. It is not the named-agent census and it is not risk. HIGH risk follows the workspace shrink mode (operator, auto to Build, or require approve). Shrink never kills the agent. Restore is a separate operator action.

Passports are signed

The v1 JSON passport stays for old clients. v2 is a signed claim (shield-kya-agent-passport-v2 and shield-kya-session-claim-v1) using the control-plane key. Verify returns valid, expired, revoked, or bad signature. The claim is a control-plane signature, not a PKI certificate.

Fail closed defaults

• If approval is required and missing, the side effect is denied.
• Policy DENY blocks the action. There is no silent bypass.
• Session risk may only raise severity. It never auto-allows a high-stakes action.
• Personal data is redacted before model calls.

Modules

• Core: registry, policy, approve, redaction, trail.
• Observe: sensor ingest and session risk (optional).
• Audit: graph dual-write for exportable account (optional).
• Edge: optional Gatekeeper only after Shield has approved. Shield still decides policy.

What Shield owns

Identity, policy, human approval, personal data redaction, and the event trail stay here. Domain workflows and vendor connectors do not own approval or the event log.

Public source: The-Pixel-Boys/shield-kya. Same mark as the header.

Install Getting started Docs Use cases