dotkc Keychain secrets for OpenClaw

OpenClaw-first secrets workflow

Secrets you can run, not paste.

dotkc stores secrets in your OS Keychain (macOS Keychain / iCloud Keychain) and injects them into commands when you need them. It’s built for personal OpenClaw/local-agent setups where you want secure, repeatable env injection without sprinkling secrets across .env files, shell history, or CI logs.

Get started npm source 
# store secrets in Keychain (interactive hidden prompt)
dotkc set vercel acme-app-dev CLERK_SECRET_KEY

# inspect (redacted by default)
dotkc run vercel:acme-app-dev

# run your app with env injected
dotkc run vercel:acme-app-dev -- pnpm dev

Inspect mode prints redacted values by default. Use --unsafe-values only on a trusted machine.

A simple (and safe) personal workflow
Developer MacBook dotkc writes to Keychain iCloud Keychain sync (encrypted) Mac mini runs OpenClaw OpenClaw import / set dotkc run Goal: keep secrets out of repos, files, and chat—while still being easy to use.
Keychain Durable secret storage
Sync iCloud sync to your OpenClaw host
Run Inject env into tools safely

Why dotkc?

The pain

  • .env files drift and leak (repos, backups, screenshots).
  • Copy/paste secrets into terminals ends up in history.
  • Agents (like OpenClaw) need secrets frequently, but you don’t want them in chat.

The idea

  • Store secrets once in Keychain.
  • Reference them by a stable name.
  • Inject them into commands at runtime.

Designed for OpenClaw

  • Keychain is OS-native and works well with personal machines.
  • iCloud Keychain can sync to the Mac mini hosting OpenClaw.
  • Inspect mode helps you verify imported secrets quickly.

How it works

dotkc stores secrets using a simple 3‑dimension naming model: service + category + KEY.

Storage model

Secrets are stored in the OS credential store under: (service, category:KEY)

  • service: the SaaS or system (e.g. vercel, github)
  • category: project/environment (e.g. acme-app-dev)
  • KEY: env var name (e.g. CLERK_SECRET_KEY)

Tip: avoid : in category names to keep parsing unambiguous.

Two modes: run vs inspect

  • Run: dotkc run <spec> -- <cmd> injects env into the child process.
  • Inspect: dotkc run <spec> prints redacted values so you can sanity check quickly.

Want full values? Use --unsafe-values (and accept the logging risk).

OpenClaw pattern: manage secrets on your laptop → sync via iCloud Keychain → OpenClaw host uses dotkc run to inject secrets into tools (Next.js, REST services, CLIs, etc.).

Quickstart

Install

npm i -g dotkc
# or
pnpm add -g dotkc

Initialize Keychain permission

dotkc init

Run once to trigger macOS Keychain prompts.

Import from .env (interactive selection)

cd /path/to/your/project

dotkc import vercel acme-app-dev .env

Inspect (redacted)

dotkc run vercel:acme-app-dev
# or JSON
# dotkc run --json vercel:acme-app-dev

Run your app

dotkc run vercel:acme-app-dev -- pnpm dev
# Next.js
# dotkc run vercel:acme-app-dev -- pnpm build

Wildcard vs exact specs

# wildcard (all KEYs under category)
dotkc run vercel:acme-app-dev -- node ./app.mjs

# exact (single key)
dotkc run vercel:acme-app-dev:CLERK_SECRET_KEY -- node ./app.mjs

Why Keychain vs .env?

  • OS‑native encryption + access control (you can review/deny access per app).
  • Less accidental leakage (repos, zip files, backups, screenshots, shell history).
  • Sync (iCloud Keychain) works well for personal laptop ↔ Mac mini setups.
  • Better agent hygiene: OpenClaw can use secrets without you pasting them into chat.

dotkc is optimized for personal workflows. For large teams and production secret management, consider dedicated platforms (Vault, AWS/GCP secrets, 1Password CLI, etc.).

FAQ

Is inspect mode safe?

It’s safer than printing raw values: dotkc prints redacted values + length by default. Still, be mindful of terminal logs, screen recording, and shared machines.

How do I print the full values?

Use dotkc run --unsafe-values <spec>. dotkc will print a warning to stderr.

Does dotkc support Windows/Linux?

It uses a Keychain backend via keytar bindings. Behavior depends on OS support. The main target is macOS + personal machines (especially iCloud Keychain sync).

What does dotkc store exactly?

Secrets are stored as Keychain entries keyed by service and category:KEY. dotkc never stores secrets in your git repo unless you explicitly put them there.

Notes

CI note

dotkc is published via GitHub Actions. The Keychain backend requires OS dependencies on Linux runners (e.g. libsecret), so CI installs it during tests/publish.

pnpm note

Because dotkc depends on a native module, pnpm may require approving build scripts in global installs. If you hit a native addon error, run: 

pnpm approve-builds -g

Links