Brokre

brokre — AI-safe Credential Broker

English | [简体中文](README.zh-CN.md)

brokre is a local credential broker for AI agents and humans. Use it with Cursor, Claude Code, Kimi Code, Trae, OpenClaw, Hermes Agent, ChatClaw, and other MCP-capable clients to run ssh, mysql, psql, and more — passwords never enter AI context, environment variables, or ps output. It wraps any CLI on your PATH — not only SSH or MySQL — and injects saved passwords at the prompt without exposing plaintext to the AI process, shell history, or process environment.

Developed by Techinone (成都同创合一科技有限公司).

What's New in 0.2.17

0.2.17 is the current release: SessionRelay routed SSH by default, multi-hop bastion routes, local-only list by default, and the existing one-command npm install / auto MCP registration / auto binary upgrade flow.

npm — install, auto-update, auto MCP setup

npm install -g brokre          # or: npx -y brokre@latest

| Capability | What happens | |------------|----------------| | Auto MCP registration | postinstall runs brokre-setup-mcp — detects installed IDEs only and merges npx -y brokre@latest into each global MCP config. Re-run: brokre mcp setup or npx brokre-setup-mcp. Skip: BROKRE_MCP_SKIP_SETUP=1. | | Auto binary upgrade | On each MCP start, compares npm package version with PATH / ~/.brokre/bin/brokre; downloads matching GitHub Release when missing or older. | | CLI without npm | brokre version / brokre upgrade for install.sh users; brokre mcp setup to register MCP after installing IDEs. | | Supported IDEs | Cursor, VS Code, VS Code Insiders, Claude Code, Claude Desktop, Trae, Kimi Code, Windsurf, OpenClaw — see [packages/brokre-mcp/README.md](packages/brokre-mcp/README.md). |

Recommended MCP config (also applied by auto-setup):

{ "command": "npx", "args": ["-y", "brokre@latest"] }

Bastion broker — cluster management

The bastion layer lets AI agents operate many hosts behind one jump box without copying vault passwords into context or scattering secrets on the laptop.

| Advantage | What it means in practice | |-----------|----------------------------| | Single control plane | Register a bastion SSH alias (b150), sync inner aliases from remote brokre, and drive the whole cluster from brokre list / MCP brokre_list | | Smart routing | b150::db, b150::app-01, multi-hop b1::b2::inner — route separator ::; routed SSH uses SessionRelay by default | | Secrets stay on the bastion | Routed exec runs ~/.brokre/bin/brokre on the jump host; laptop holds metadata and session gate, not inner-host passwords | | Human gate, agent-friendly | Bastion outbound requires unlock (TTY, /bastion-auth, or MCP URL elicitation); gate auth survives manage UI idle expiry so long MCP runs keep working | | Cluster-safe defaults | Local-only list by default; explicit bastion discovery; reachability probes with ms timeouts and concurrency caps; loop detection and audit route/bastion fields | | Privileged ops over routes | brokre_exec_elevated and sudo/sudo -i paths work through bastions with session reuse and PTY hardening |

Typical flow for a K8s / DB / batch cluster behind one entry host:

brokre bastion enable b150
brokre bastion sync b150 --json          # pull inner alias catalog
brokre bastion unlock
brokre list --include-bastions --json    # b150::db, b150::worker-01, …
brokre ssh b150::db systemctl status   # MCP: brokre_exec with routed alias

MCP equivalent:

{ "binary": "ssh", "args": ["b150::db", "uname", "-a"] }

Gate policy (default vs strict) — see [Bastion gate policy](#bastion-gate-policy-default-vs-strict) below. Gate is inactive until brokre bastion set-key; then default unlocks only bastion outbound paths; strict requires unlock for every exec while list remains local-only unless bastion discovery is requested.

See [Cross-network list inheritance](#cross-network-list-inheritance-bastion-broker) and [Bastion proxy](#bastion-proxy-cross-network--intranet-entry) below for setup details.

CLI security (core)

brokre is built around one rule: secrets stay out of the AI's reach and out of observable process state.

| Layer | What brokre does | |-------|-----------------| | No env / ps leakage | Injection is PTY prompt-based — passwords are never passed via -p, SSHPASS, MYSQL_PWD, or exported env vars | | Parent never holds plaintext (Unix) | Saved passwords decrypt in a short-lived brokre --internal-injector child, written once to the PTY, then the child exits | | AI cannot reveal | brokre reveal requires a real TTY + master passphrase; unavailable in the web UI and not exposed via MCP | | Vault at rest | Per-field AES-256-GCM; DEK wrapped with OS keyring (Linux) or ~/.brokre/.master_kek (macOS) + optional Argon2id reveal passphrase | | Audit | HMAC-chained JSONL at ~/.brokre/audit/audit.log; brokre audit list queries history (metadata only); brokre audit verify detects tampering | | MCP boundary | MCP exposes metadata (brokre_list), exec (brokre_exec, brokre_exec_elevated), brokre_setup, and read-only audit (brokre_audit_list, brokre_audit_verify) — no passwords, session tokens, or reveal | | Manage UI | Binds 127.0.0.1 only; passwords are write-only; audit log tab for history; session token printed in your terminal, never returned to AI | | OS hardening | Core dumps disabled, ptrace checks (Linux), optional mlockall — see [docs/HARDENING.md](docs/HARDENING.md) |

Full threat model: [SECURITY.md](SECURITY.md), [THREATMODEL.md](THREATMODEL.md).

Any CLI on PATH (generic by design)

brokre is not a fixed list of database/SSH wrappers. The core model is:

brokre  [args...]

First connection: run verbatim, capture the password you type at the prompt, offer to save as an alias. Next time: brokre … auto-injects — AI and scripts only see the alias name.

Preset prompt patterns ship for common tools (ssh, mysql, psql, redis-cli, ftp, clickhouse, git, docker, kubectl, sudo, …). Everything else uses a generic password: / passphrase: matcher — no code changes required.

brokre gsql prod-cluster -c "SELECT 1"    # any proprietary CLI on PATH
brokre kubectl get pods                   # if your cluster CLI prompts for a password
brokre my-internal-tool --host db.internal

Customize when needed:

• ~/.brokre/prompts.toml — per-binary prompt regex overrides
• ~/.brokre/manage.toml — custom sections in the manage UI (e.g. GaussDB, internal tools)

Built-in manage UI tabs (when the binary is installed) include SSH, FTP, MySQL, PostgreSQL, Redis, ClickHouse, MinIO — convenience only; the PTY wrapper works for any CLI.

Install (MCP first — recommended for AI)

The npm package brokre launches the local brokre mcp server over stdio for Cursor, Claude Code, Kimi Code, Trae, OpenClaw, Windsurf, VS Code, and other MCP clients.

Choose your install path

| Path | Best for | Install | MCP in IDEs | CLI upgrade | |------|----------|---------|-------------|-------------| | npm (recommended) | AI users; want one command | npm install -g brokre | Automatic on install (postinstall) | npm + auto-download on each MCP start | | install.sh / Homebrew | Production; no Node for daily use | curl … \| bash or brew install brokre | Run brokre mcp setup after IDE install | brokre version / brokre upgrade | | Manual MCP JSON | Custom layouts only | CLI or npm already present | Edit IDE config by hand | Depends on how CLI was installed |

Recommended MCP entry (also what auto-setup writes):

{ "command": "npx", "args": ["-y", "brokre@latest"] }

No Node — point MCP at the native binary: { "command": "brokre", "args": ["mcp"] }.

Path A — npm one-liner (0.2.8+)

npm install -g brokre
# or without global install:
npx -y brokre@latest

On npm install, three things happen automatically:

1. MCP launcher — brokre-mcp / npx -y brokre@latest spawns brokre mcp.
2. IDE auto-registration — postinstall runs brokre-setup-mcp: detects installed IDEs only (app, CLI, or real usage artifacts — not empty folders) and merges the MCP entry above into each global config. Idempotent; preserves your other MCP servers.
3. Binary auto-upgrade — on each MCP start, if PATH or ~/.brokre/bin/brokre is older than the npm package, the matching GitHub Release is downloaded.

IDEs covered by auto-setup

| IDE | Global config | |-----|----------------| | Cursor | ~/.cursor/mcp.json | | VS Code / Insiders | …/Code/User/mcp.json | | Claude Code | ~/.claude.json | | Claude Desktop | …/Claude/claude_desktop_config.json | | Trae | …/Trae/User/mcp.json | | Kimi Code | ~/.kimi-code/mcp.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json | | OpenClaw | ~/.openclaw/openclaw.json (mcp.servers) |

Re-run registration (e.g. you installed brokre before Cursor, then installed Cursor later):

brokre mcp setup              # via CLI — same logic as postinstall
npx brokre-setup-mcp          # via npm
brokre mcp setup --dry-run    # preview only
brokre mcp setup --force      # overwrite existing brokre entry

Skip auto-registration on npm install: BROKRE_MCP_SKIP_SETUP=1. Disable binary auto-download: BROKRE_SKIP_AUTO_INSTALL=1. Pin a binary: BROKRE_BIN=/path/to/brokre.

Requires Node.js 18+ for the npm path.

Path B — Native CLI (install.sh / Homebrew, no npm)

curl -fsSL https://raw.githubusercontent.com/Furowu/brokre/main/install.sh | bash

brew tap Furowu/brokre
brew install brokre

Version and upgrade (built into the CLI — no npm required):

brokre version                # version, binary path, install type
brokre version --check        # compare with latest GitHub release
brokre version --check --json
brokre upgrade                # download latest release (curl + tar)
brokre upgrade --check        # exit 1 if an update is available
brokre upgrade 0.2.10         # install a specific version
brokre upgrade --force        # reinstall even when up to date

Re-run install.sh also upgrades when a newer release exists.

Register MCP after CLI install (needs Node for the setup script, or npx fallback):

brokre mcp setup

Manual per-IDE setup (optional)

Use this only if you skip auto-setup or need project-scoped config.

Cursor — [one-click install](cursor://anysphere.cursor-deeplink/mcp/install?name=brokre&config=eyJicm9rcmUiOnsiY29tbWFuZCI6Im5weCIsImFyZ3MiOlsiLXkiLCJicm9rcmVAbGF0ZXN0Il19fQ==), or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "brokre": { "command": "npx", "args": ["-y", "brokre@latest"] }
  }
}

Claude Code — user scope in ~/.claude.json or claude mcp add --scope user brokre -- npx -y brokre@latest. Project scope: .mcp.json with "type": "stdio".

More clients and env vars: [packages/brokre-mcp/README.md](packages/brokre-mcp/README.md). MCP Registry ID: io.github.Furowu/brokre.

MCP tools and usage

| MCP tool | Purpose | |----------|---------| | brokre_list | Saved local aliases by default; set include_bastions=true to discover routed aliases (b150::db), which may require bastion unlock; includes access/availability/bastion_gate | | brokre_exec | Run any saved CLI alias (binary + args); ssh supports shell_command for remote scripts; ssh + sudo/su auto-reuses elevated session | | brokre_exec_elevated | Remote privileged command (alias, command, mode); default session=reuse (10 min idle timeout) | | brokre_setup | Open manage UI in browser for the human to add creds | | brokre_audit_list | Query audit history (metadata only — args redacted) | | brokre_audit_verify | Verify tamper-evident audit log chain | | brokre_bastion_policy | Read or set bastion gate mode (default / strict); returns key_set, unlocked |

MCP vs CLI (essential for AI agents)

brokre is not a drop-in for ssh / mysql — you must prefix with brokre for vault injection.

| Task | MCP (in IDE) | CLI (terminal / debugging) | |------|--------------|----------------------------| | List aliases | brokre_list | brokre list --json | | SSH remote command | brokre_exec binary=ssh, args=["prod","uname","-a"] | brokre ssh prod uname -a | | Any CLI | brokre_exec binary=mysql, args=["prod-db","-e","SHOW TABLES"] | brokre mysql prod-db -e "SHOW TABLES" | | Write remote script | shell_command="…" (ssh only) | brokre ssh prod sh -c '…' (whole script as one -c arg) | | Privileged exec | brokre_exec_elevated command="…" | brokre ssh prod sudo … (MCP has session pool; CLI uses fresh PTY each time) | | Add credentials | brokre_setup (opens browser) | brokre manage --open | | First-time save | not available (human TTY required) | brokre ssh user@10.0.0.1 |

Common mistakes (AI agents)

| Wrong | Right | |-------|-------| | ssh prod uptime | brokre ssh prod uptime | | MCP args=["prod","uname -a"] (one shell string) | args=["prod","uname","-a"] (argv tokens) | | MCP args=["prod","sh -c 'echo hi'"] | shell_command="echo hi" or args=["prod","sh","-c","echo hi"] | | bare mysql -h … -p | brokre mysql … |

For remote SSH: tokens after the alias are argv slices, not one shell command. Use split tokens for simple commands; use shell_command for complex scripts.

MCP elevated sessions (sudo / su, Unix)

By default, brokre mcp reuses a background elevated shell per (alias, mode, user) so sudo passwords are not re-prompted on every call.

brokre_exec_elevated (preferred for privilege escalation):

{
  "alias": "prod",
  "command": "systemctl status nginx",
  "mode": "sudo_login",
  "session": "reuse"
}

| Field | Description | |-------|-------------| | mode | sudo, sudo_login (or sudo-i), su | | session | reuse (default), new (close old session and open fresh), close (end session; pass command: "") | | user | su mode only; default root |

When the session pool is enabled, responses include session_reused and session_idle_expires_at in addition to exit_code / stdout / stderr. session_idle_expires_at is a rolling idle-window hint refreshed on each call, not a fixed expiry timestamp. stderr is usually empty on the pool path.

brokre_exec: binary=ssh with sudo/su in args auto-uses the same pool (always reuse; no session=new|close). Example: args=["prod","sudo","whoami"].

Writing remote scripts/files (shell_command, binary=ssh only): pass only the alias in args; put the full shell script in shell_command (brokre normalizes to sh -c). Do not embed sh -c '...' in args or split printf/redirects across argv tokens. For privileged system paths use brokre_exec_elevated.command.

{
  "binary": "ssh",
  "args": ["prod"],
  "shell_command": "cat > /tmp/deploy.sh   [args...]

List metadata (safe for AI / scripts)

brokre list --json              # no bastions: local aliases only; with bastions: smart list (below)
brokre list --all --json        # include unreachable aliases (debugging)
brokre list --no-bastion-discovery   # local only — no SSH, no probe

When bastions are registered, brokre list stays local-only by default and does not SSH to bastions or trigger bastion unlock. Use brokre list --include-bastions (MCP: include_bastions=true) when you actually need routed aliases such as b150::db; that remote discovery may require unlock.

Cross-netw

…

Source & license

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

• Author: Furowu
• Source: Furowu/brokre
• License: MIT

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