katanakitAI
katanakitAI
Section titled “katanakitAI”The AI toolbox of KatanaKit: it stores your AI provider API keys encrypted at
rest and turns them into working configuration for the coding agents you use —
including MCP server registration. It ships as toolkit services plus a CLI, kai,
so the same vault can back a script, a CI job or your terminal.
Everything is local-first: the vault lives on your machine, backups are re-encrypted blobs you can move anywhere, and no secret is ever sent anywhere.
Install
Section titled “Install”npm install -g katanakit-js # or: bun add -g katanakit-jskai helpNo install needed — run it straight from npm:
npx katanakit-js keys list # npmbunx katanakit-js keys list # bunHow it works
Section titled “How it works”Core services plus one infrastructure adapter and the CLI:
| Layer | Module | Responsibility |
|---|---|---|
| Core | keyvault.service.ts |
Key record lifecycle (create, rotate, revoke), masking, provider env names |
| Core | mcp.service.ts |
MCP server registry + OpenCode mcp.servers emission |
| Core | agentconfig.service.ts |
Per-agent config emission (“auto configuration” + “manual connection”) |
| Infrastructure | vault.store.ts |
scrypt + AES-256-GCM envelope, atomic writes, owner-only file mode |
| CLI | adapters/cli (kai) |
keys, mcp and agents command groups |
The vault file is ~/.config/katanakitai/vault.enc.json (override with
KATANAKITAI_VAULT). Every vault command needs KATANAKITAI_PASSPHRASE.
CLI cookbook
Section titled “CLI cookbook”Store a key
Section titled “Store a key”export KATANAKITAI_PASSPHRASE="…"kai keys add openai --label ci --secret "sk-…"# or pipe it, so the secret never touches shell history:echo "sk-…" | kai keys add openai --label ciList, reveal, rotate, revoke
Section titled “List, reveal, rotate, revoke”kai keys list # masked secrets onlykai keys reveal <id> # the ONLY place a secret is printedkai keys rotate <id> --secret "sk-new…"kai keys revoke <id>Rotation keeps the record id stable, so generated configs stay valid.
Register an MCP server
Section titled “Register an MCP server”kai mcp add context7 --url https://mcp.context7.com/mcpkai mcp add playwright --command "bunx @playwright/mcp"kai mcp add private --url https://mcp.example.com/mcp \ --header 'Authorization=Bearer {env:PRIVATE_MCP_TOKEN}'Credential values use {env:NAME} references — the vault keeps the secret,
generated config keeps the indirection.
Generate agent configuration
Section titled “Generate agent configuration”kai agents listkai agents config opencode --key <keyId>kai agents config claude-code --key <keyId> --writeThe output mirrors every agent-setup UI:
- Auto configuration — the file the tool reads. For OpenCode the API key is
referenced as
{env:OPENAI_API_KEY}, never inlined. For Claude Code theenvblock of~/.claude/settings.jsonholds the value as written (that is how Claude Code reads it), so the file is created with600permissions and the notes say to keep it out of version control. - Manual connection — the env exports and endpoint to paste by hand.
Secrets are masked in every preview. --reveal prints real values;
--write writes them (that is the explicit act) and refuses to overwrite an
existing file without --force.
Back up the vault
Section titled “Back up the vault”kai keys export --out ~/backups/keys.enc.jsonThe backup is sealed with the same passphrase — safe to push to your own storage.
Library usage
Section titled “Library usage”import { useCreateKeyRecord, useMaskSecret, useEmitAgentConfig,} from "katanakit-js";
const record = useCreateKeyRecord({ provider: "openai", label: "ci", secret: "sk-…",});const config = useEmitAgentConfig("opencode", { provider: "openai", secret: "sk-…", mcpServers: [],});For persistence, use the infrastructure adapter:
import { useSaveVaultFile, useLoadVaultFile, useVaultPath } from "katanakit-js";
const path = await useVaultPath();await useSaveVaultFile(path, vaultData, passphrase);Security notes
Section titled “Security notes”- Encryption: scrypt (N=16384, r=8, p=1) + AES-256-GCM, with the KDF parameters stored inside the envelope so they stay upgradeable.
- A wrong passphrase and a tampered file fail the same way — the error never says which one it was.
kai keys listand every config preview mask secrets; onlykai keys revealand an explicit--reveal/--writeshow real values.- The vault file and generated files are written with owner-only permissions
(
600).