five-minute walkthrough

Getting started with KYE OSS

Install @kye/shadow-mode-sdk, register an observed action, generate an Evidence Pack, verify it offline. Pure local mode — no API key required.

Install the SDK

The SDK is published to npm under Apache 2.0.

npmbash

npm install @kye/shadow-mode-sdk

# or via pnpm / yarn / bun
pnpm add @kye/shadow-mode-sdk
yarn add @kye/shadow-mode-sdk
bun add @kye/shadow-mode-sdk

Run in local-only mode (no cloud)

Local mode persists observed actions to a local JSON file. No network calls. Useful for offline development and CI.

example.tstypescript

import { ObservedActionBuilder, LocalSink } from "@kye/shadow-mode-sdk";

const sink = new LocalSink({ path: "./.kye-shadow.jsonl" });

const action = new ObservedActionBuilder()
  .actor("kye:agent:acme.ap_processor_007")
  .principal("kye:user:acme.cfo.j_okonkwo")
  .action("payment.propose")
  .target("VND-217:£4,820.00")
  .context({ amount_gbp: 4820 })
  .build();

await sink.write(action);
console.log("recorded", action.observed_action_id);

Generate an Evidence Pack

The SDK's buildEvidencePack() assembles a CBOR pack from one or more observed actions and seals it with a local integrity tag for development use. (Production signing happens in the Cloud Gateway; the production construction is part of the patent track and is not disclosed here.)

example.ts (continued)typescript

import { buildEvidencePack } from "@kye/shadow-mode-sdk";

const pack = await buildEvidencePack({
  observed_actions: [action],
  tenant: "kye:tenant:acme.dev",
  signing_key: process.env.KYE_LOCAL_DEV_KEY,
});

await sink.writeEvidencePack(pack);

Verify the pack offline

Use the Conformance Pack verifier CLI to verify the pack without contacting any KYE endpoint.

bashcli

npx @kye/conformance-pack-verifier verify ./pack.cbor \
  --keys ./trusted-keys.json

# Output:
#   ✓ pack_id          kye:ep:acme.dev:01HF...
#   ✓ schema_version   kye.evidence.evidence_pack.v1
#   ✓ signature        valid (key kid=kye:pk:acme.local.001)
#   ✓ hash_chain       continuous (1 action)
#   ✓ verdict          PASS

Point at the Cloud Gateway (optional)

When you're ready to start ingesting into a real tenant, swap LocalSink for KyeClient with your gateway URL and tenant credentials. The builder and pack shapes are byte-identical.

example.ts (cloud)typescript

import { KyeClient } from "@kye/shadow-mode-sdk";

const client = new KyeClient({
  gatewayUrl: "https://gateway.kyeprotocol.com",
  tenant:     "kye:tenant:acme",
  apiKey:     process.env.KYE_API_KEY,
});

const decision = await client.ingest(action);
console.log(decision.decision, decision.evidence_pack_id);

Next steps

• Read the full package list for Python, the verifier CLI, and the widget protocol.
• Inspect the interactive sandbox if you'd rather click than code.
• Already convinced? Apply for a pilot → to run KYE on your real agent traffic.