Kprun

kprun v0.6.1

[](https://github.com/numikel/kprun/actions/workflows/ci.yml) [](LICENSE)

Local secrets injector for developers and AI agent workflows. KeePass .kdbx vault (KeePassXC-compatible), OS keychain unlock, per-process env injection — not session-wide.

Releases · [Changelog](CHANGELOG.md) · [Install](#installation) · [Quick start](#quick-start) · [Scripts & automation](#scripts-and-automation) · [Coding agents & OpenRouter](#coding-agents-and-openrouter) · [MCP integration](#mcp-integration) · [Security model](#security-model)

---

About

kprun stores API keys and tokens in a KeePass database on your machine. It unlocks the vault via KPRUN_KEYFILE, the OS credential store, or an interactive prompt, then injects secrets as environment variables into one child process only. Nothing is exported to your shell profile, nothing lands in MCP stdout.

Typical uses:

• Run MCP servers (npx …) without pasting tokens into client config files
• Launch coding agents (Claude Code, Hermes, Junie, AGY, …) with OpenRouter env vars injected for one session only
• Run Python, Node.js, or shell scripts with injected secrets for automation (kprun run myapi -- python script.py)
• Skip per-project .env files — secrets live in the vault and are injected at run time, not on disk in the repo
• Manage a dedicated dev-secrets vault separate from your personal password manager

How it works

flowchart LR
    subgraph without ["Without kprun"]
        direction TB
        W1["shell exports GITHUB_TOKEN=…"]
        W1 -->|"secrets in every child"| W2["all processes inherit env"]
    end

    subgraph with ["With kprun"]
        direction TB
        K1["kprun run github -- npx @mcp/server-github"]
        K1 --> K2["unlock vault(keyfile → keyring → prompt)"]
        K2 --> K3["read entry 'github' custom fields"]
        K3 --> K4["inject env into child only"]
        K4 --> K5["inherit stdio; audit log (key names only)"]
    end

Unlock priority: KPRUN_KEYFILE → OS keystore (kprun / master) → hidden stderr prompt.

Features

• ✅ KeePass / KeePassXC vault — entry title = service name; custom string fields = env var names
• ✅ Per-process injection — kprun run opens the vault read-only and spawns one child with merged env
• ✅ MCP-safe stdio — run prints nothing on stdout; child owns stdin/stdout/stderr
• ✅ Full secret lifecycle — init, set, get, unset, delete, export, import, doctor
• ✅ Audit log — JSON lines with entry names and injected key names; never values, never the vault path
• ✅ Cross-platform — Linux, macOS, Windows (PATHEXT-aware spawn, keyring v1)
• ✅ RTK-style install — install.sh / install.ps1 with SHA-256 checksum verify
• ✅ CI matrix — fmt, clippy, tests on ubuntu/windows/macos; release assets on tag v*

Requirements

• Rust: 1.88.0+ (to build from source)
• OS: Linux, macOS, or Windows
• Optional: KeePassXC to create or edit .kdbx files
• MCP client: Cursor, Claude Code, or any tool that spawns a subprocess over stdio

Installation

Quick install (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/numikel/kprun/refs/heads/main/scripts/install.sh | sh

Installs to ~/.local/bin by default. Override with KPRUN_INSTALL_DIR. Skip PATH changes with KPRUN_NO_MODIFY_PATH=1.

> Add to PATH manually if needed: > > ``bash > echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # or ~/.zshrc > ``

Quick install (Windows)

irm https://raw.githubusercontent.com/numikel/kprun/refs/heads/main/scripts/install.ps1 | iex

Default install dir: %LOCALAPPDATA%\kprun\bin. Adds user Path unless KPRUN_NO_MODIFY_PATH=1.

Open a new terminal, then verify:

kprun --version

Pre-built binaries

Download from GitHub Releases (after the first tag):

| Platform | Asset | |----------|-------| | Linux x86_64 | kprun-x86_64-unknown-linux-gnu.tar.gz | | Linux arm64 | kprun-aarch64-unknown-linux-gnu.tar.gz | | macOS Intel | kprun-x86_64-apple-darwin.tar.gz | | macOS Apple Silicon | kprun-aarch64-apple-darwin.tar.gz | | Windows | kprun-x86_64-pc-windows-msvc.zip + standalone kprun.exe |

Verify with checksums.txt from the same release unless KPRUN_SKIP_CHECKSUM=1.

Build from source

git clone https://github.com/numikel/kprun.git
cd kprun
cargo build --release -p kprun
# binary: target/release/kprun (or target//release/kprun)

Or install into Cargo bin dir:

cargo install --path crates/kprun

Or straight from Git, without cloning:

cargo install --git https://github.com/numikel/kprun

Updating

From previous v0.4.x

# Cargo
cargo install --git https://github.com/numikel/kprun --force

# Or re-run install script
curl -fsSL https://raw.githubusercontent.com/numikel/kprun/refs/heads/main/scripts/install.sh | sh

v0.5.0 breaking change: OS keychain account name changed (lexical path → SHA-256). On Windows or macOS /tmp vaults, re-run kprun init after updating to re-store the master password.

Binary updates

Download latest from GitHub Releases, verify checksum, replace executable.

Troubleshooting updates

Windows: "access denied" or "failed to remove file"

The executable may be locked by an antivirus, file system cache, or running process:

# Kill any running kprun process
Get-Process kprun -ErrorAction SilentlyContinue | Stop-Process -Force

# Remove the old binary manually
Remove-Item -Path "$env:USERPROFILE\.cargo\bin\kprun.exe" -Force -ErrorAction SilentlyContinue

# Retry installation
cargo install --git https://github.com/numikel/kprun --force

If cargo clean && cargo install --path crates/kprun still fails, wait 10–15 seconds (antivirus quarantine) and retry.

Quick start

# 1. Create vault — one command, no prompts. A master password is generated,
#    stored in the OS keychain, and shown once on stdout.
kprun init --quick
# ⚠️ SAVE THE MASTER PASSWORD PRINTED ABOVE — you'll need it to open the vault in KeePassXC.
# Retrieve later with: kprun reveal-master

# 2. Store secrets (entry title = service; fields = env vars)
kprun set github GITHUB_TOKEN=ghp_xxx

# 3. Inject into a child process
kprun run github -- npx -y @modelcontextprotocol/server-github

Windows (after install.ps1):

kprun init --quick
# ⚠️ SAVE THE MASTER PASSWORD PRINTED ABOVE (shown once for security)
# Retrieve later with: kprun reveal-master

kprun set github GITHUB_TOKEN=ghp_xxx
kprun run github -- npx -y @modelcontextprotocol/server-github

About the master password: kprun init --quick generates a random password, prints it once (save it for KeePassXC access), and stores it securely in the OS keychain. You don't need to memorize it — it's automatically unlocked for kprun run and other commands. If you forget it, retrieve it anytime with kprun reveal-master.

Prefer choosing your own master password (or a keyfile)? Run plain kprun init instead.

Attach an existing KeePassXC database

kprun init --db /path/to/existing.kdbx

Verifies unlock and optionally stores the master password in the OS keychain. Does not recreate the database.

Scripts and automation

Beyond MCP servers and coding agents, kprun run injects vault secrets into any child process that reads environment variables — Python, Node.js, shell scripts, and more. Handy for CI jobs, cron, Task Scheduler, and one-off scripts without checking secrets into a repo or exporting them in your shell profile.

Skip project .env files

Many tools expect secrets in a .env file (python-dotenv, dotenv in Node, framework auto-load). With kprun, store keys in the vault instead and launch through kprun run — the child sees normal environment variables, with no .env on disk, nothing to .gitignore, and no accidental commits. Scripts can use os.getenv / process.env as usual; you can drop load_dotenv() or require('dotenv').config() when env is always injected by kprun.

To move an existing flat .env into the vault once, see [Export and import](#export-and-import).

The -- separator is required — it marks where vault entry names end and the child command begins:

kprun run  [entry2 ...] --  [args...]

Without --, everything after run is parsed as entry names and the command is missing (common mistake).

Python

Store API keys or tokens under one vault entry, then run your script — secrets appear as normal env vars inside the child only:

kprun set myapi API_KEY=sk-... API_BASE=https://api.example.com
kprun run myapi -- python fetch_data.py
kprun run myapi -- python -m mypackage.cli --dry-run

Windows PowerShell:

kprun set myapi API_KEY=sk-... API_BASE=https://api.example.com
kprun run myapi -- python fetch_data.py

In Python, read them with os.environ["API_KEY"] (or os.getenv) — no kprun-specific API.

Node.js / JavaScript

Same pattern for node, npm scripts, or npx:

kprun set openai OPENAI_API_KEY=sk-...
kprun run openai -- node scripts/sync.js
kprun run openai -- npx tsx scripts/backup.ts

Windows PowerShell:

kprun run openai -- node scripts/sync.js

Combine multiple vault entries when a script needs keys from more than one service:

kprun run openai langfuse -- python pipeline.py

For scheduled jobs without an interactive session (no OS keychain prompt), use a keyfile — see [Automation and cron](#automation-and-cron).

Coding agents and OpenRouter

Many terminal coding agents read API keys and provider URLs from environment variables. Instead of exporting them in ~/.bashrc or ~/.zshrc (where every process inherits them), store the OpenRouter profile in your vault and launch the agent through kprun run.

The -- separator is required — it marks where vault entry names end and the child command begins:

kprun run  --  [args...]

One-time vault setup (Claude Code / OpenRouter)

Per OpenRouter's Claude Code guide, Claude Code expects these variables. Store them under one vault entry (title = openrouter here; any name works):

kprun set openrouter \
  OPENROUTER_API_KEY=sk-or-... \
  ANTHROPIC_BASE_URL=https://openrouter.ai/api \
  ANTHROPIC_AUTH_TOKEN=sk-or-... \
  ANTHROPIC_API_KEY=

KeePass fields are literal values — set ANTHROPIC_AUTH_TOKEN to the same key as OPENROUTER_API_KEY. Set ANTHROPIC_API_KEY to an empty string to avoid auth conflicts with a cached Anthropic login (run /logout inside Claude Code once if you previously signed in with Anthropic).

Optional model overrides (also from the OpenRouter docs):

kprun set openrouter \
  ANTHROPIC_DEFAULT_SONNET_MODEL='~anthropic/claude-sonnet-latest' \
  ANTHROPIC_DEFAULT_OPUS_MODEL='~anthropic/claude-opus-latest'

Launch examples

Claude Code — secrets stay in the child process only; your shell profile stays clean:

kprun run openrouter -- claude

Windows PowerShell:

kprun run openrouter -- claude

Verify inside Claude Code with /status (auth token: ANTHROPIC_AUTH_TOKEN, base URL: https://openrouter.ai/api).

Antigravity CLI (agy) — the CLI authenticates via Google by default. If you use OpenRouter through a plugin, extension, or any workflow that reads OPENROUTER_API_KEY from the environment, inject it the same way:

kprun set openrouter OPENROUTER_API_KEY=sk-or-...
kprun run openrouter -- agy

Hermes Agent — Nous Research's terminal agent reads OPENROUTER_API_KEY from the environment (alternative to ~/.hermes/.env). Model and provider stay in ~/.hermes/config.yaml; see OpenRouter's Hermes guide:

kprun set openrouter OPENROUTER_API_KEY=sk-or-...
kprun run openrouter -- hermes
# or: kprun run openrouter -- hermes --tui

Junie CLI — JetBrains' terminal agent uses OpenRouter as a native BYOK provider via JUNIE_OPENROUTER_API_KEY; see OpenRouter's Junie guide:

kprun set openrouter \
  OPENROUTER_API_KEY=sk-or-... \
  JUNIE_OPENROUTER_API_KEY=sk-or-...
kprun run openrouter -- junie

Headless CI example (same injected env, no shell profile):

kprun run openrouter -- junie "Review and fix any code quality issues in the latest commit"

GitHub Copilot CLI — Copilot fixes the model at startup and speaks OpenAI-compatible APIs; env injection alone is awkward for live model switching. For Copilot CLI (and Codex CLI with OpenRouter), the author recommends copilot-cli-custom-proxy instead: a local tray proxy that swaps models on the fly, injects the API key from memory, and launches Copilot/Codex with the right env — without putting keys in your shell profile.

| Agent | kprun fit | Notes | |-------|-----------|-------| | Claude Code | ✅ Best fit | Env-based OpenRouter setup; see OpenRouter docs | | Hermes Agent | ✅ Best fit | OPENROUTER_API_KEY; config in ~/.hermes/config.yaml; see OpenRouter docs | | Junie CLI | ✅ Best fit | JUNIE_OPENROUTER_API_KEY; see OpenRouter docs | | Antigravity CLI (agy) | ⚠️ Partial | Default auth is Google; use kprun when the workflow reads env vars | | Copilot CLI / Codex CLI | ❌ Use proxy | Prefer copilot-cli-custom-proxy |

One OpenRouter key can power every tool above; generate it at openrouter.ai/settings/keys.

Configuration

| Variable | Default | Description | |----------|---------|-------------| | KPRUN_DB | ~/.kprun/secrets.kdbx | Path to the KeePass database | | KPRUN_KEYFILE | — | Path to a cryptographic key file (second factor) | | KPRUN_LOG | ~/.kprun/access.log | Audit log path (JSON lines; see [Audit log format](#audit-log-format)) | | KPRUN_INSTALL_DIR | ~/.local/bin / %LOCALAPPDATA%\kprun\bin | Install script target | | KPRUN_NO_MODIFY_PATH | unset | Set to 1 to skip shell PATH updates | | KPRUN_SKIP_CHECKSUM | unset | Set to 1 to skip install checksum verify | | KPRUN_VERSION | latest release | Pin install script version | | KPRUN_TEST_MASTER | — | Test hook (only in builds compiled with --features test-hooks; not present in GitHub Release binaries): fixed master password for automation |

Install script env vars are documented in scripts/install.sh and scripts/install.ps1.

CLI reference

kprun init   [--db PATH] [--no-store] [--keyfile PATH] [--quick [--force]]
kprun run     [entry2 ...] --  [args...]
kprun list   [--json]
kprun get     [--keys] [--reveal]
kprun set     KEY=val [KEY2=val2 ...] | --stdin
kprun unset   KEY [KEY2 ...]
kprun delete 
kprun export [--format json|dotenv] [--stdout] [--reveal]
kprun import  [--merge]
kprun migrate  [--entry ] [--merge] [--gitignore] [--delete]
kprun doctor [--mcp ]
kprun reveal-master
kprun deinit [--delete-vault [--yes]]

Notes:

• get and export show key names by default; use --reveal only when you need values (stderr warning + audit).
• init --quick generates a 128-bit master password, creates a password-only vault, and stores the password in the OS keychain; the password is printed once on stdout. --force overwrites an existing vault after interactive co

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: numikel
• Source: numikel/kprun
• License: MIT
• Homepage: https://kprun.michalsk.pl/

Install and usage instructions live in the source repository linked above.