Agenten stärken
Installation vom Herausgeber. Kein PlugMCP-Endpunkt.
Host a copy with our keys and logs.
Noch kein paketiertes Release in der Registry. Folgen Sie der README des Repositorys.
Remote-URL oder ein Befehl auf Ihrem Rechner? Worin sich die beiden Installationen unterscheiden
Auf PlugMCP ausführen
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
StartenVom Herausgeber
Stop storing API keys in mcp.json and shell profiles. kprun solves this by keeping secrets in an encrypted KeePass vault and injecting them only into spawned processes. Designed for MCP servers, coding agents, and dev scripts. Features: per-proces injection, audit logging, cross-platform, KeePassXC-compatible, CI/CD-ready.
Stop storing API keys in mcp.json and shell profiles. kprun solves this by keeping secrets in an encrypted KeePass vault and injecting them only into spawned processes — no shell-wide exports, no plaintext config files. Designed for MCP servers, coding agents, and dev scripts. Features: per-process injection, audit logging (key names only), cross-platform (Linux/macOS/Windows), KeePassXC-compatible, CI/CD-ready.
Sections: About · How it works · Features · Requirements · Installation · Updating · Quick start · Scripts & automation · Coding agents & OpenRouter · Configuration · CLI reference · CLI Functions · Export and import · MCP integration · Automation and cron · Project structure · Development · Security model · Releases · Contributing · License
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:
npx …) without pasting tokens into client config fileskprun run myapi -- python script.py).env files — secrets live in the vault and are injected at run time, not on disk in the repoflowchart 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<br/>(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.
kprun run opens the vault read-only and spawns one child with merged envrun prints nothing on stdout; child owns stdin/stdout/stderrinit, set, get, unset, delete, export, import, doctorinstall.sh / install.ps1 with SHA-256 checksum verifyv*.kdbx filescurl -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:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # or ~/.zshrc
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
Download from GitHub Releases (after the first tag):
Verify with checksums.txt from the same release unless KPRUN_SKIP_CHECKSUM=1.
git clone https://github.com/numikel/kprun.git
cd kprun
cargo build --release -p kprun
# binary: target/release/kprun (or target/<triple>/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
# 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.
Download latest from GitHub Releases, verify checksum, replace executable.
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.
# 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.
kprun init --db /path/to/existing.kdbx
Verifies unlock and optionally stores the master password in the OS keychain. Does not recreate the database.
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.
.env filesMany 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.
The -- separator is required — it marks where vault entry names end and the child command begins:
kprun run <entry> [entry2 ...] -- <command> [args...]
Without --, everything after run is parsed as entry names and the command is missing (common mistake).
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.
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.
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 <entry> -- <agent-command> [args...]
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'
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.
One OpenRouter key can power every tool above; generate it at openrouter.ai/settings/keys.
Coding agents (Claude Code, Cursor, Codex, Copilot, Windsurf, OpenCode,
Antigravity) default to creating .env files or asking you to paste secrets
into chat. kprun agents installs a secrets policy into the instruction
files those tools already read, teaching them to prefer kprun run injection
instead.
kprun supports the open AGENTS.md standard as its single source of truth:
one repo-level AGENTS.md covers every tool that reads it natively. Claude
Code additionally gets a native CLAUDE.md containing the same full policy
block (no import indirection); both files refresh together on every install,
so they cannot drift. Gemini CLI is deliberately skipped — it is being sunset
in favor of Antigravity, which reads AGENTS.md.
The policy block sits between and markers; re-running install refreshes only
that region and never touches surrounding content.
kprun agents print # canonical block on stdout
kprun agents install # AGENTS.md + CLAUDE.md in the current directory
kprun agents install --path sub/dir # another directory
kprun agents install -g # global files of auto-detected agents
kprun agents install -g --target claude,codex # explicit tools, no detection
Install script env vars are documented in scripts/install.sh and scripts/install.ps1.
kprun init [--db PATH] [--no-store] [--keyfile PATH] [--quick [--force]]
kprun run <entry> [entry2 ...] -- <command> [args...]
kprun list [--json]
kprun get <entry> [--keys] [--reveal]
kprun set <entry> KEY=val [KEY2=val2 ...] | --stdin
kprun unset <entry> KEY [KEY2 ...]
kprun delete <entry>
kprun export [--format json|dotenv] [--stdout] [--reveal] [--output PATH]
kprun import <file> [--merge]
kprun migrate <file> [--entry <name>] [--merge] [--gitignore] [--delete]
kprun scan [--path DIR] [--history [--full-history]] [--json]
kprun doctor [--mcp <entry>] [-- <command>...]
kprun mcp -e <entry> [--header "Name: template"]... [--bearer FIELD] [--transport auto|streamable-http|sse] [--timeout SECS] [--allow-insecure-http] <url>
kprun agents print | install [--path <dir>] | install -g [--target <tool>[,<tool>...]]
kprun reveal-master [--db PATH]
kprun deinit [--db PATH] [--delete-vault [--yes]]
For detailed workflow examples, see Export and import, MCP integration, and Automation and cron below.
kprun initPurpose: Create a new KeePass vault or attach an existing one. The vault stores secrets in a .kdbx file and the master password can be stored in the OS keychain for automatic unlocking.
Syntax:
kprun init [--db PATH] [--no-store] [--keyfile PATH] [--quick [--force]]
Options:
--db PATH — Path to the KeePass database (default: ~/.kprun/secrets.kdbx or KPRUN_DB env var). If the path points to an existing database, kprun verifies unlock and optionally stores the master password in the keychain.--keyfile PATH — Path to a cryptographic key file (256 random bits encoded as hex). Created if missing. Acts as a second factor alongside the master password; both are required to unlock. Useful for automation when the OS keychain is unavailable (cron, Task Scheduler).--no-store — Do not store the master password in the OS keychain. Requires interactive prompts on every kprun command. Incompatible with kprun mcp (which cannot prompt).--quick — Non-interactive setup: generates a random 128-bit master password (printed once to stdout), creates a password-only vault (no keyfile required), and stores the password in the OS keychain. Save the printed password — you will need it to open the vault in KeePassXC. Incompatible with --keyfile and --no-store.--force — Requires --quick. Overwrites an existing vault after confirmation; does not ask interactively, assumes yes.Limitations:
.kdbx format). If the vault is compromised, all secrets are at risk.kprun init --quick on temporary vaults to update the keychain entry.Examples:
# Quick setup: auto-generated password, stored in keychain
kprun init --quick
# ⚠️ SAVE THE MASTER PASSWORD PRINTED ABOVE
# Custom database path with keyfile
kprun init --db /vault/secrets.kdbx --keyfile /vault/master.key
# Attach an existing KeePassXC database
kprun init --db ~/Documents/MyPasswords.kdbx
# Re-initialize vault (overwrites after confirmation)
kprun init --quick --force
kprun runPurpose: Inject secrets from vault entries into a child process environment. The child process inherits only the injected variables plus a safe default environment (PATH, HOME, etc.). Nothing is exported to your shell profile.
Syntax:
kprun run [--clean-env] <entry> [entry2 ...] -- <command> [args...]
Arguments:
<entry> [entry2 ...] — One or more vault entry titles. Secrets from all entries are merged into the child's environment. If an entry doesn't exist, kprun exits with error code 1.-- — Required separator that marks where entry names end and the child command begins.<command> [args...] — Command to run in the child process. Receives the injected environment variables.Options:
--clean-env — Inject vault secrets into a minimal, safe environment instead of inheriting parent env. Drops parent variables except PATH, HOME, and a small allowlist. Useful for scripts that should not see unrelated secrets from the parent shell.Limitations:
-- separator is mandatory — without it, every positional argument is parsed as an entry name and the command is never found.Examples:
# Run Python with injected secrets from 'myapi' entry
kprun run myapi -- python script.py
# Multiple entries: secrets from both are merged
kprun run openai langfuse -- python pipeline.py
# NPX with injected GitHub token
kprun run github -- npx -y @modelcontextprotocol/server-github
# Run with minimal environment (drops parent env)
kprun run api --clean-env -- node server.js
kprun listPurpose: Display all vault entries and their custom field names (key names), but not values.
Syntax:
kprun list [--json]
Options:
--json — Output as a single JSON array of objects, each with entry (entry title) and keys (array of field names). Suitable for scripting and CI pipelines.Limitations:
kprun get --reveal for values on a single entry).1 if the vault cannot be opened (missing DB, unlock failed).Examples:
# Human-readable list
kprun list
# Output:
# github
# GITHUB_TOKEN
# GITHUB_URL
# openai
# OPENAI_API_KEY
# JSON format for scripting
kprun list --json
# Output: [{"entry":"github","keys":["GITHUB_TOKEN","GITHUB_URL"]},...]
# Filter entries with jq (requires --json)
kprun list --json | jq -r '.[].entry'
kprun getPurpose: Show custom fields (key names and optionally values) for a single vault entry.
Syntax:
kprun get <entry> [--keys] [--reveal]
Arguments:
<entry> — Vault entry title to read.Options:
--keys — Print only field names, one per line (default behavior includes both names and placeholder values).--reveal — Print full KEY=value lines with secret values. Triggers a stderr warning and audit log record — use deliberately. Audit log will record that the value was revealed but never the actual value.Limitations:
1 if the entry is not found or the vault cannot be opened.[secret] text.Examples:
# Show key names only
kprun get github
# Output:
# GITHUB_TOKEN=[secret]
# GITHUB_URL=[secret]
# Show only the names
kprun get github --keys
# Output:
# GITHUB_TOKEN
# GITHUB_URL
# Reveal actual values (audit logged)
kprun get github --reveal
# Output (+ stderr warning):
# GITHUB_TOKEN=ghp_xxx...
# GITHUB_URL=https://github.com
kprun setPurpose: Create a new vault entry or update secret fields on an existing entry.
Syntax:
kprun set <entry> KEY=val [KEY2=val2 ...] | --stdin
Arguments:
<entry> — Vault entry title. Created if it doesn't exist.KEY=val [KEY2=val2 ...] — One or more KEY=value pairs to set. Values are parsed as literal strings (no shell expansion).Options:
--stdin — Read KEY=value lines from stdin instead of argv. Blank lines and # comment lines are skipped. Avoids exposing secrets in shell history or process listings. Incompatible with positional arguments.Limitations:
--stdin for sensitive values.kprun set commands expose secrets to shell history and ps output during execution — prefer --stdin for sensitive values.1 if the vault cannot be opened or unlocked.Examples:
# Set a single key on an existing entry (risky: shows in shell history)
kprun set github GITHUB_TOKEN=ghp_xxx
# Set multiple keys at once
kprun set openai OPENAI_API_KEY=sk-... OPENAI_ORG_ID=org-...
# Use stdin to avoid shell history (secure)
kprun set github --stdin <<'EOF'
GITHUB_TOKEN=ghp_xxx
GITHUB_URL=https://github.com
EOF
# Or pipe from a file
cat secrets.txt | kprun set myapi --stdin
kprun unsetPurpose: Remove custom fields (secret keys) from a vault entry without deleting the entry itself.
Syntax:
kprun unset <entry> KEY [KEY2 ...]
Arguments:
<entry> — Vault entry title.KEY [KEY2 ...] — One or more field names to remove.Limitations:
1 if the entry is not found or the vault cannot be opened.kprun delete.Examples:
# Remove a single key
kprun unset github GITHUB_TOKEN
# Remove multiple keys
kprun unset openai OPENAI_API_KEY OPENAI_ORG_ID
# Entry still exists after unset
kprun get github # succeeds, but entry has fewer fields
kprun deletePurpose: Completely remove a vault entry and all its custom fields.
Syntax:
kprun delete <entry>
Arguments:
<entry> — Vault entry title to delete.Limitations:
1 if the entry is not found or the vault cannot be opened.Examples:
# Permanently delete an entry
kprun delete old-api
# Entry is now gone
kprun get old-api # exits with error "Entry not found"
kprun exportPurpose: Export vault entries to JSON or dotenv format for backup, migration, or sharing vault structure. See Export and import section below for workflow details, format examples, and round-trip procedures.
Syntax:
kprun export [--format json|dotenv] [--stdout] [--reveal] [--output PATH]
Options:
--format json|dotenv — Output format: json (default, structured) or dotenv (kprun dotenv round-trip).--stdout — Write to stdout instead of a file (suitable for piping).--reveal — Include secret values in the export (unencrypted on disk — use carefully, audit logged).--output PATH — Write to this file instead of the default kprun-export.json or .env.Limitations:
[secret]). Use --reveal to export actual values.1 if the vault cannot be opened or the output file cannot be written.Quick examples:
kprun export --format json --stdout # JSON to stdout
kprun export --reveal --output /tmp/backup # Values to file (unsafe)
kprun export --format dotenv --stdout # Dotenv format
kprun importPurpose: Import vault entries from JSON or dotenv files. By default replaces all vault content; use --merge to add or update without deleting. See Export and import section below for accepted formats and workflow examples.
Syntax:
kprun import <file> [--merge]
Options:
--merge — Add or update imported entries; keep others in vault. Without this, entire vault is replaced.Limitations:
.env files (no # entry headers) cannot be imported — use kprun migrate instead.1 if the file cannot be read or is malformed.Quick examples:
kprun import backup.json # Replace vault
kprun import new-entries.json --merge # Add to existing vault
kprun migratePurpose: Migrate a standard project .env file (flat KEY=value format) into the vault. Automatically names the entry after the file's directory, handles .gitignore setup, and can delete the source file after import.
Syntax:
kprun migrate <file> [--entry <name>] [--merge] [--gitignore] [--delete]
Arguments:
<file> — Path to a standard .env file (e.g., .env, config/.env, backend/.env).Options:
--entry <name> — Vault entry title for the imported secrets (default: name of the directory containing the file, e.g., .env → root, backend/.env → backend).--merge — Add keys to an existing entry instead of creating a new one.--gitignore — Automatically add the file's name to .gitignore without prompting (useful for CI).--delete — Delete the source .env file after successful import. Only deletes if the file was successfully imported and re-read for byte-identity verification.Limitations:
.env format (no # entry headers). For kprun dotenv format, use kprun import.KEY=" ") to keep whitespace.1 if the file cannot be read or parsed.--delete is passed.Examples:
# Migrate and ask about .gitignore
kprun migrate backend/.env
# Migrate and automatically handle .gitignore, then delete the file
kprun migrate backend/.env --gitignore --delete
# Migrate to a custom entry name
kprun migrate .env --entry prod-secrets --merge
# CI-friendly: minimal interaction, full cleanup
kprun migrate app/.env --entry app --gitignore --delete
kprun doctorPurpose: Diagnose vault configuration and generate a ready-to-paste MCP server config snippet for mcp.json.
Syntax:
kprun doctor [--mcp <entry> [-- <command>...]]
Options:
--mcp <entry> — Print a JSON MCP config snippet for this vault entry instead of diagnostics. Suitable for pasting into mcp.json.-- <command>... — MCP server command to append (e.g., -- npx -y @modelcontextprotocol/server-github). Without this, the snippet is incomplete and hints at manual completion.Output:
--mcp: Summary of vault location, unlock method, and configuration issues (if any).--mcp <entry>: A ready-to-paste JSON object for mcpServers (Linux/macOS use symlink, Windows use full path).Limitations:
--mcp is used without a command, the output is incomplete (only ["run", "<entry>", "--"]); you must manually add the server command.1 if the vault cannot be opened or the entry is not found.Examples:
# Diagnose configuration
kprun doctor
# Generate MCP snippet for GitHub
kprun doctor --mcp github -- npx -y @modelcontextprotocol/server-github
# Output:
# {
# "command": "kprun",
# "args": ["run", "github", "--", "npx", "-y", "@modelcontextprotocol/server-github"]
# }
# Copy to your mcp.json:
# "mcpServers": {
# "github": { ... snippet ... }
# }
kprun mcpPurpose: Bridge stdio JSON-RPC messages to a remote HTTP MCP server, injecting vault-backed auth headers. Enables secure, non-interactive access to hosted MCP servers (GitHub Copilot, Context7, etc.) without storing credentials in mcp.json. See MCP integration section below for detailed setup, transport modes, and authentication patterns.
Syntax:
kprun mcp -e <entry> [--header "Name: template"]... [--bearer FIELD] \
[--transport auto|streamable-http|sse] [--timeout SECS] \
[--allow-insecure-http] <url>
Arguments & Options:
-e, --entry <entry> — Vault entry whose custom fields fill {{FIELD}} templates.<url> — Remote MCP endpoint URL (supports {{FIELD}} substitution).--header "Name: template" — Extra HTTP header (repeatable), with {{FIELD}} substitution.--bearer FIELD — Shorthand for Authorization: Bearer {{FIELD}}.--transport auto|streamable-http|sse — Transport mode (auto default, tries Streamable HTTP then legacy SSE fallback).--timeout SECS — Per-request timeout (default 30).--allow-insecure-http — Allow vault-backed credentials over plaintext http:// to non-loopback hosts.Limitations:
KPRUN_KEYFILE.Quick examples:
kprun mcp -e github --bearer TOKEN https://api.githubcopilot.com/mcp/
kprun mcp -e context7 --header "CONTEXT7_API_KEY: {{CONTEXT7_API_KEY}}" https://mcp.context7.com/mcp
kprun reveal-masterPurpose: Print the stored master password for the current vault to stdout. Useful for opening the vault in KeePassXC or for emergency recovery.
Syntax:
kprun reveal-master [--db PATH]
Options:
--db PATH — Path to the KeePass database (default: KPRUN_DB or ~/.kprun/secrets.kdbx).Limitations:
1 if the password cannot be retrieved from the keychain or if the database is not found.kprun init or re-stored with kprun init --db <path>). If --no-store was used, the password is not available.Examples:
# Print master password to stdout (with stderr warning)
kprun reveal-master
# Copy to clipboard (macOS)
kprun reveal-master | pbcopy
# Copy to clipboard (Linux with xclip)
kprun reveal-master | xclip -selection clipboard
# Copy to clipboard (Windows PowerShell)
kprun reveal-master | Set-Clipboard
kprun deinitPurpose: Remove the stored master password from the OS keychain, and optionally delete the vault file itself. Useful for cleanup or switching to a different vault.
Syntax:
kprun deinit [--db PATH] [--delete-vault [--yes]]
Options:
--db PATH — Path to the KeePass database (default: KPRUN_DB or ~/.kprun/secrets.kdbx).--delete-vault — Also delete the vault file (.kdbx). Asks for confirmation unless --yes is passed.--yes — Requires --delete-vault. Skip confirmation prompt and immediately delete the vault file.Limitations:
1 if the database is not found or the keychain entry cannot be removed.--yes skips the safety prompt.Examples:
# Remove stored password (vault file is kept)
kprun deinit
# Remove stored password and delete the vault file (with confirmation)
kprun deinit --delete-vault
# Remove password and vault, skip confirmation (CI-friendly)
kprun deinit --delete-vault --yes
kprun scanPurpose: Fast heuristic scan for accidentally committed secrets in git-tracked files and history. Detects well-known API key formats (AWS, GitHub, OpenAI, Stripe, etc.). Not a substitute for dedicated scanners like gitleaks or trufflehog.
Syntax:
kprun scan [--path DIR] [--history [--full-history]] [--json]
Options:
--path DIR — Directory to scan (default: current directory). Must be inside a git repository.--history — Additionally scan git history (git log -p, last 500 commits by default).--full-history — Requires --history. Remove the 500-commit limit and scan entire history.--json — Output a single JSON document suitable for CI pipelines. Findings are masked (e.g., ghp_x7Kq…(40 chars)).Detected formats:
AKIA…)ghp_… family, github_pat_…)sk-proj-…)sk-ant-…)sk_live_…, sk_test_…)AIza…)xoxb-… family)glpat-…)-----BEGIN … PRIVATE KEY-----)Known limitations:
sk-… keys (bare prefix) are not detected — too ambiguous to match with high confidence..env.example, .env.sample, .env.template, .env.dist are scanned for content but not flagged as files (they are templates).ghp_x7Kq…(40 chars)) — full secret values never appear in output.Exit codes:
0 — No findings.1 — Findings detected.2 — Execution error (git missing, --path outside repository).Examples:
# Scan current directory working tree only
kprun scan
# Scan and include git history (last 500 commits)
kprun scan --history
# Scan entire history
kprun scan --history --full-history
# Scan a subdirectory
kprun scan --path backend
# JSON output for CI pipelines
kprun scan --json | jq '.findings'
# Exit code check for CI gates
kprun scan --history --json && echo "✓ Clean" || echo "✗ Findings detected"
kprun agentsInstall the kprun secrets policy into coding-agent instruction files.
kprun agents print
kprun agents install [--path <dir>]
kprun agents install -g [--target <tool>[,<tool>...]]
print — write the canonical policy block to stdout (plain markdown).install — create or refresh AGENTS.md and CLAUDE.md in --path
(default: current directory). Idempotent: only the content between the
kprun:agent-policy markers is ever rewritten; a second run reports
unchanged.install -g — write the global instruction files of agents detected by
their config directories in HOME (~/.claude, ~/.codex,
~/.config/opencode, ~/.codeium/windsurf, ~/.copilot /
COPILOT_HOME). --target skips detection and installs for the named
tools, creating missing directories. --path and -g are mutually
exclusive. Accepted targets: claude, codex, opencode, windsurf,
copilot, cursor (Cursor prints guidance only — its global rules are
GUI-only).Never touches the vault — no unlock, works without KPRUN_DB. Per-file
results (created / updated / unchanged) go to stderr; exit code is
non-zero if any file failed.
import accepts JSON (.json) or kprun dotenv (.env). JSON is the structured format from kprun export --stdout. Dotenv is not a generic project .env file — it is the round-trip format produced by kprun export --format dotenv.
Each vault entry is a comment line with the entry title, followed by KEY=value lines. Separate entries with a blank line:
# github
GITHUB_TOKEN="ghp_xxx"
# postgres
DATABASE_URL="postgres://local"
To migrate a flat project .env (keys only, no title comments), use kprun migrate — it parses the standard format directly, names the entry after the file's directory, and can clean up the repository:
kprun migrate backend/.env # asks before touching .gitignore
kprun migrate backend/.env --gitignore --delete # CI-friendly, full cleanup
kprun migrate .env --entry backend --merge # explicit title, add to existing entry
For the kprun dotenv round-trip format itself:
kprun import secrets.env --merge # add/update keys; keep other vault entries
kprun import secrets.env # replace vault content with file entries
Inspect the canonical dotenv layout with:
kprun export --format dotenv --stdout --reveal
Structure-only dotenv exports (key names in # comments, no values) cannot be imported — re-export with --reveal first.
MCP clients spawn a command and talk over the child's stdio. Use kprun run as a transparent wrapper.
Linux / macOS (with kprun on PATH):
{
"mcpServers": {
"github": {
"command": "kprun",
"args": ["run", "github", "--", "npx", "-y", "@modelcontextprotocol/server-github"]
}
}
}
Windows (prefer full path — some MCP clients do not resolve PATH reliably):
{
"mcpServers": {
"github": {
"command": "C:\\Users\\you\\AppData\\Local\\kprun\\bin\\kprun.exe",
"args": ["run", "github", "--", "npx", "-y", "@modelcontextprotocol/server-github"]
}
}
}
Generate a ready-to-paste fragment:
kprun doctor --mcp github
For other entries, append the MCP server command after --:
kprun doctor --mcp qdrant -- npx -y @modelcontextprotocol/server-qdrant
Without a child command, generic entries emit ["run", "<entry>", "--"] and a stderr hint — paste the server command into args manually or re-run with --.
After editing MCP config, check git diff — some tools may write secrets back to disk.
Hosted MCP servers (GitHub Copilot, remote SaaS endpoints, …) don't spawn a local child process — the client talks HTTP directly to a URL, so the bearer token or API key normally sits in plaintext inside mcp.json. kprun mcp closes that gap: it's a stdio↔HTTP bridge that reads the token from the vault at launch and never writes it to disk.
kprun mcp -e <entry> [--header "Name: template"]... [--bearer FIELD] \
[--transport auto|streamable-http|sse] [--timeout SECS] \
[--allow-insecure-http] <url>
-e, --entry <ENTRY> — vault entry whose custom fields fill {{FIELD}} templates in headers and the URL--header "Name: template" — extra header, repeatable, with {{FIELD}} substitution--bearer FIELD — shorthand for --header "Authorization: Bearer {{FIELD}}"--transport — auto (default, follows the MCP spec's backwards-compatibility detection: try Streamable HTTP, fall back to the deprecated HTTP+SSE only when the server answers initialize with 404/405), streamable-http, or sse (deprecated HTTP+SSE only). Known limitation: the legacy HTTP+SSE path is validated against mock servers only — providers have retired the live endpoints (e.g. DeepWiki's /sse now returns 410 Gone) — and the legacy stream has no auto-reconnect. Using it prints a deprecation warning on stderr; prefer Streamable HTTP URLs.--timeout SECS — per-request timeout for POST round-trips (default 30; SSE streams are exempt — they're long-lived by design)--allow-insecure-http — kprun refuses to send vault-backed credentials (--bearer, any --header, or a {{FIELD}} in the URL) over plaintext http:// to a non-loopback host, because they would be readable by any network observer. http:// to loopback (127.0.0.0/8, ::1, localhost) is always allowed for local dev servers. This flag deliberately overrides the refusal for a trusted network path — prefer https://.Client config:
"GitHub": {
"command": "kprun",
"args": ["mcp", "-e", "github", "--bearer", "TOKEN",
"https://api.githubcopilot.com/mcp/"]
}
Providers that use a custom header (not Authorization: Bearer) need --header instead of --bearer. Context7 is a common case — the native client config puts the API key in plaintext:
"context7": {
"url": "https://mcp.context7.com/mcp",
"headers": { "CONTEXT7_API_KEY": "YOUR_API_KEY" }
}
Store the key in the vault (kprun set context7 CONTEXT7_API_KEY=ctx7sk-..., or --stdin to avoid shell history), then bridge with:
"context7": {
"command": "kprun",
"args": ["mcp", "-e", "context7",
"--header", "CONTEXT7_API_KEY: {{CONTEXT7_API_KEY}}",
"https://mcp.context7.com/mcp"]
}
The {{CONTEXT7_API_KEY}} placeholder must match a custom field on the context7 vault entry (kprun get context7 lists field names). Starting the bridge writes one audit line (entries: ["context7"], injected_keys: ["CONTEXT7_API_KEY"], command: "mcp mcp.context7.com") — not one line per tool call.
kprun mcp never prompts — it needs a non-interactive unlock path. Run kprun init first so the master password is cached in the OS keyring, or set KPRUN_KEYFILE (see Automation and cron). Note the keyfile is a second key component, not a password replacement: for a vault protected by password + keyfile, the password must be in the keyring (do not use --no-store at init), otherwise non-interactive unlock fails with Incorrect key. Like run, it writes nothing but JSON-RPC frames to stdout; the audit log gets one line when the bridge starts (header names and URL host only, never token values) — not on each MCP tool call in that session.
Auth troubleshooting: a missing token yields a clear HTTP 401 error, and some servers (e.g. GitHub Copilot MCP) answer an invalid token with HTTP 400 — both now fail fast with a credentials hint and never retry over legacy SSE. Automatic fallback to the deprecated HTTP+SSE transport happens only when the server answers initialize with 404/405 (the MCP spec's signature of a pre-Streamable server); for an unusual legacy server that responds otherwise, pass --transport sse explicitly.
When no interactive session is available (cron, Task Scheduler), the OS keychain may be unavailable. Use a keyfile:
kprun init --keyfile ~/.kprun/master.key
export KPRUN_KEYFILE=~/.kprun/master.key
kprun run myservice -- python /path/to/job.py
# or: kprun run myservice -- node /path/to/job.js
# or: kprun run myservice -- /path/to/script.sh
Windows Task Scheduler — set KPRUN_KEYFILE and KPRUN_DB in the task environment, then:
kprun run myservice -- python C:\jobs\nightly.py
The keyfile is generated by kprun (64 random bytes), not a plaintext password file. Restrict permissions (chmod 600 on Unix; user-only ACL on Windows).
For scheduled jobs, set KPRUN_DB and KPRUN_KEYFILE in the job environment. Use --no-store at init if you do not want the master password in the keychain — but note this breaks kprun mcp, which cannot prompt: with --no-store the password exists nowhere non-interactive, and the keyfile alone cannot open a password+keyfile vault.
kprun/
├── crates/
│ ├── kprun-core/ # vault, unlock, inject, audit (no clap / Command)
│ └── kprun/ # CLI binary, spawn, commands
├── scripts/
│ ├── install.sh # RTK-style installer (Unix)
│ └── install.ps1 # Windows installer
├── tests/ # integration tests (run, init, manage, export, doctor, …)
├── .github/workflows/
│ ├── ci.yml # fmt, clippy, test matrix
│ └── release.yml # cross-build + checksums on tag v*
└── docs/
├── kprun.gif # demo animation
└── changelogs/ # per-version release notes
git clone https://github.com/numikel/kprun.git
cd kprun
cargo build -p kprun
cargo test --all-features
KeePassXC compatibility test (optional, local fixture):
# Create tests/fixtures/keepassxc.kdbx in KeePassXC (gitignored)
# Entry title: fixture; custom attribute: FIXTURE_KEY
KPRUN_KEEPASSXC_FIXTURE=1 KPRUN_TEST_MASTER='your-pass' \
cargo test reads_keepassxc_fixture -- --ignored
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
Use a dedicated dev-secrets vault, not your personal password manager.
Report vulnerabilities per SECURITY.md ([email protected]); do not file public issues for security bugs.
Secrets exist in the child process environment after injection (same model as other secret runners).
Audit log records entry names, injected key names, and a non-identifying vault id — never values, never the vault path (see Audit log format).
Do not use setx or global shell profiles for API keys.
Pass only the entries a command needs: kprun run openai -- python script.py, not every secret at once.
export --reveal and get --reveal print values to the terminal — use deliberately.
kprun reveal-master joins the --reveal family: it prints the vault master password to stdout with a stderr warning and an audit record (db_id only, never the value) — use deliberately.
Inline kprun set <entry> KEY=value puts the secret in your shell history and in process listings (ps, Task Manager) while the command runs. For sensitive values prefer kprun set <entry> --stdin and type or pipe KEY=value lines (blank lines and # comments are skipped):
kprun set github --stdin <<'EOF'
GITHUB_TOKEN=ghp_xxx
EOF
kprun scan)kprun scan is a fast, high-confidence heuristic: prefix-anchored
matching for well-known key formats over all git-tracked files, plus
detection of tracked .env files (.env.example / .env.sample /
.env.template / .env.dist count as templates — not flagged as files,
but their content is still scanned). With --history it also scans lines
added in git log -p (last 500 commits; --full-history removes the
limit). Both the working-tree and --history scans are scoped to --path;
history covers commits reachable from HEAD (not unmerged branches,
stashes, or commits reachable only from other refs).
AKIA…), GitHub tokens (ghp_… family
and github_pat_…), OpenAI project keys (sk-proj-…), Anthropic keys
(sk-ant-…), Stripe keys (sk_live_… / sk_test_…), Google API keys
(AIza…), Slack tokens (xoxb-… family), GitLab PATs (glpat-…), and
private-key blocks (-----BEGIN … PRIVATE KEY-----).sk-… keys — the bare sk- prefix
is too ambiguous to match with high confidence.ghp_x7Kq…(40 chars)): the full secret
value never appears in scan output, --json included.--json prints a single machine-readable document ("version": 1)
with findings and scan stats for CI consumption.Every audit record is one JSON line with exactly these fields:
When is a line written? One line per kprun process that reads secrets from the vault — not per downstream operation inside that process. For kprun run, that is once when the child is spawned. For kprun mcp, that is once when the MCP client starts the bridge; every JSON-RPC frame (including repeated tool calls) reuses the same process and does not append further lines. A new line appears only when the client restarts the MCP server (reload config, IDE restart, reconnect). Individual MCP method names, request counts, and RPC payloads are never logged.
Examples — run (one line per spawned child):
{"ts":"2026-07-08T14:03:11+0100","pid":4242,"db_id":"9f2b4c1a8e3d5f07","entries":["openai"],"injected_keys":["OPENAI_API_KEY"],"command":"python"}
mcp (one line when Cursor starts the bridge; four Context7 tool calls in the same session still produce this single line):
{"ts":"2026-07-10T23:00:00+0200","pid":12345,"db_id":"9f2b4c1a8e3d5f07","entries":["context7"],"injected_keys":["CONTEXT7_API_KEY"],"command":"mcp mcp.context7.com"}
Prior to v0.3.2 the record carried a db field with the full vault path; lines written by older versions are left untouched — rotate or delete old logs if that matters to you.
Entry titles are written verbatim to the unencrypted audit log on each such vault read and are retained until rotation pushes them out (two files, ~10 MB).
Choose service-oriented, non-identifying titles (github, openai,
staging-db) rather than names of people or clients.
Releases are published when a maintainer tags vX.Y.Z and pushes:
git tag vX.Y.Z
git push origin main --tags
CI validates the changelog file and version match, builds release binaries for five targets, and publishes a GitHub Release whose body comes from docs/changelogs/vX.Y.Z.md.
git checkout -b feat/my-change).feat(cli): add example command, fix(core): handle locked db).cargo fmt, cargo clippy --all-targets --all-features -- -D warnings, and cargo test --all-features.main.Use English for code, comments, and CLI messages.
MIT License — see LICENSE.
@numikel
Security note: kprun injects secrets into child process environments. Treat the vault file, keyfile, and audit log as sensitive. Do not commit .kdbx files or keyfiles to version control.
Stop storing API keys in mcp.json and shell profiles. kprun solves this by keeping secrets in an encrypted KeePass vault and injecting them only into spawned processes. Designed for MCP servers, codin
Übersicht
Stop storing API keys in mcp.json and shell profiles. kprun solves this by keeping secrets in an encrypted KeePass vault and injecting them only into spawned processes. Designed for MCP servers, coding agents, and dev scripts. Features: per-proces injection, audit logging, cross-platform, KeePassXC-compatible, CI/CD-ready.
Tools
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
Kprun läuft lokal über stdio.
Zuletzt geprüft: 2026-10-28. Stop storing API keys in mcp.json and shell profiles. kprun solves this by keeping secrets in an encrypted KeePass vault and injecting them only into spawned processes. Designed for MCP servers, coding agents, and dev scripts. Features: per-proces injection, audit logging, cross-platform, KeePassXC-compatible, CI/CD-ready.