# Kprun

> Local secrets injector for developers and AI agent workflows — KeePass vault, OS keychain unlock, per-process env injection.

- **Type:** MCP server
- **Install:** `agentstack add mcp-numikel-kprun`
- **Verified:** Pending review
- **Seller:** [numikel](https://agentstack.voostack.com/s/numikel)
- **Installs:** 0
- **Category:** [Security](https://agentstack.voostack.com/c/security)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [numikel](https://github.com/numikel)
- **Source:** https://github.com/numikel/kprun
- **Website:** https://kprun.michalsk.pl/

## Install

```sh
agentstack add mcp-numikel-kprun
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/numikel/kprun/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

```mermaid
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](https://keepassxc.org/) 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)

```bash
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)

```powershell
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:

```bash
kprun --version
```

### Pre-built binaries

Download from [GitHub Releases](https://github.com/numikel/kprun/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

```bash
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:

```bash
cargo install --path crates/kprun
```

Or straight from Git, without cloning:

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

## Updating

### From previous v0.4.x

```bash
# 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](https://github.com/numikel/kprun/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:

```powershell
# 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

```bash
# 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`):

```powershell
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

```bash
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:

```text
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:

```bash
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:

```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`:

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

Windows PowerShell:

```powershell
kprun run openai -- node scripts/sync.js
```

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

```bash
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:

```text
kprun run  --  [args...]
```

### One-time vault setup (Claude Code / OpenRouter)

Per [OpenRouter's Claude Code guide](https://openrouter.ai/docs/cookbook/coding-agents/claude-code-integration), Claude Code expects these variables. Store them under one vault entry (title = `openrouter` here; any name works):

```bash
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):

```bash
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:

```bash
kprun run openrouter -- claude
```

Windows PowerShell:

```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:

```bash
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](https://openrouter.ai/docs/cookbook/coding-agents/hermes-integration):

```bash
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](https://openrouter.ai/docs/cookbook/coding-agents/junie):

```bash
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):

```bash
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](https://github.com/numikel/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](https://openrouter.ai/docs/cookbook/coding-agents/claude-code-integration) |
| Hermes Agent | ✅ Best fit | `OPENROUTER_API_KEY`; config in `~/.hermes/config.yaml`; see [OpenRouter docs](https://openrouter.ai/docs/cookbook/coding-agents/hermes-integration) |
| Junie CLI | ✅ Best fit | `JUNIE_OPENROUTER_API_KEY`; see [OpenRouter docs](https://openrouter.ai/docs/cookbook/coding-agents/junie) |
| 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](https://github.com/numikel/copilot-cli-custom-proxy) |

One OpenRouter key can power every tool above; generate it at [openrouter.ai/settings/keys](https://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](https://github.com/numikel)
- **Source:** [numikel/kprun](https://github.com/numikel/kprun)
- **License:** MIT
- **Homepage:** https://kprun.michalsk.pl/

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-numikel-kprun
- Seller: https://agentstack.voostack.com/s/numikel
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.