brokre — AI-safe Credential Broker

<!-- README-I18N:START -->

English | 简体中文

<!-- README-I18N:END -->

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.8

0.2.8 is the current release: one-command npm install, auto MCP registration across major IDEs, auto binary upgrade on each MCP start — plus the bastion broker for multi-host / cluster operations (one laptop, one MCP session, many inner targets).

npm — install, auto-update, auto MCP setup

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

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.

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 --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 below. Gate is inactive until brokre bastion set-key; then default unlocks only bastion outbound paths; strict requires unlock for every exec/list.

See Cross-network list inheritance and Bastion proxy 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.

Full threat model: SECURITY.md, THREAT_MODEL.md.

Any CLI on PATH (generic by design)

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

brokre <any-cli-on-PATH> [args...]

First connection: run verbatim, capture the password you type at the prompt, offer to save as an alias. Next time: brokre <cli> <alias> … 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

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

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, 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. MCP Registry ID: io.github.Furowu/brokre.

MCP tools and usage

#### MCP vs CLI (essential for AI agents)

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

Common mistakes (AI agents)

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"
}

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 <<'EOF'\n#!/bin/sh\necho ok\nEOF"
}

Bastion routes work the same: args=["b150::db"] with shell_command as the remote script.

Not supported: interactive sudo -i without a command, vim/top, or sudo passwords different from the vault password field. See THREAT_MODEL.md T12.

On first connect with an empty vault, brokre opens manage in your browser (http://127.0.0.1:56777/?t=…). Session tokens stay on localhost — never returned to the AI. Set BROKRE_MCP_NO_AUTO_OPEN=1 to disable auto-open.

| MCP tool | Purpose |

Add credentials

After CLI install, the manager opens on first run (brokre manage --onboard --open). Or anytime:

brokre manage --open

Or save on first interactive connection (any CLI):

brokre ssh [email protected]
brokre my-tool --host internal.corp

Use (AI-safe)

brokre mysql prod-db -e "SHOW TABLES"
brokre ssh prod-bastion uname -a
brokre <your-cli> <alias> [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 by default: probes reachability (SSH aliases require a valid server banner; other protocols use TCP), merges bastion-discovered aliases (e.g. b150::db), and hides unreachable local LAN entries so AI agents do not pick wrong paths.

Cross-network list inheritance (bastion broker)

For cross-network access — travel, VPN, public entry points — when direct LAN aliases are unreachable locally but reachable via a bastion running brokre.

Prerequisites

1. Laptop: brokre bastion enable b150 (b150 is a saved SSH alias)
2. Bastion host runs brokre at ~/.brokre/bin/brokre (standard install / npx path) with inner aliases saved (e.g. db)

Smart list

brokre bastion unlock            # if bastion key is set
brokre list                      # includes b150::db (route=b150, access=via_b150)

When cross-network, local db (access=direct) is omitted if unreachable; use b150::db instead.

Execute

brokre ssh b150::db uname -a
# MCP: brokre_exec binary=ssh, args=["b150::db", "uname", "-a"]

When both paths work, the list shows both db (direct) and b150::db (via_b150) — distinguish by access.

Bastion proxy (cross-network / intranet entry)

Promote any saved SSH alias whose remote host runs brokre into a bastion broker. Secrets stay on the bastion; the laptop caches metadata and executes via SSH passthrough.

brokre bastion enable b150        # register ssh alias b150 as bastion
brokre bastion set-key              # set bastion unlock key (TTY)
brokre bastion unlock               # unlock outbound session (TTL, 30 min idle default)
brokre list --json                  # smart list: reachability + bastion-routed aliases
brokre ssh b150::db uname -a        # routed exec via b150 remote brokre
brokre bastion sync b150 --json     # fetch alias list from one bastion

• Route separator `::` (: is illegal in alias names): db (local), b150::db (via bastion), b1::b2::inner (multi-hop, default depth ≤2).
• Remote brokre: routed exec invokes ~/.brokre/bin/brokre on the bastion (with BROKRE_SOFT_MEMLOCK=1, BROKRE_ALLOW_FILE_KEYCHAIN=1, BROKRE_ROUTED_INNER=1 for headless Linux). Interactive commands (e.g. sudo -i) automatically get -tt.
• Guardrails: probe concurrency cap, ms timeouts, short cache, loop detection, audit route/bastion (HMAC v4).
• Manage UI: brokre manage Bastion tab — register/disable bastions, Web set-key and unlock/lock, strict-mode toggle, sync remote aliases; non-TTY still auto-opens /bastion-auth. Audit tab filters by bastion/source and shows route fields.

Bastion gate policy (default vs strict)

The bastion gate is a human unlock step before sensitive operations. It is off until you set a bastion key (brokre bastion set-key). After a key exists, unlock establishes a local TTL session (brokre bastion unlock, TTY passphrase, manage UI /bastion-auth, or MCP browser elicitation).

Policy is stored at ~/.brokre/bastion/policy.json (strict_mode, default false).

Examples (default mode, key set, session locked)

In strict mode, every row above requires unlock.

Set gate mode

brokre bastion strict status    # default | strict
brokre bastion strict on        # strict — all exec/list gated
brokre bastion strict off       # default — bastion outbound only

MCP read response includes strict_mode, gate_mode, key_set, unlocked. List/exec responses include bastion_gate (required, unlocked_during_call, idle_expires_at).

Unlock session TTL (defaults): 30 min idle (BROKRE_BASTION_IDLE_SECS), 8 h max lifetime (BROKRE_BASTION_MAX_SECS). Idle window renews on each gated call while unlocked (shared across CLI, MCP, and manage UI via ~/.brokre/run/bastion_session.json). Bastion gate auth is independent of manage UI session idle expiry. Disable auto-open browser on MCP unlock: BROKRE_BASTION_NO_AUTO_OPEN=1.

Reveal / delete (human-only, real TTY)

brokre reveal mysql prod-db --field password
brokre rm ssh prod-bastion

Audit log (metadata only)

brokre audit list --profile ssh --action exec --json
brokre audit verify --json

Events are stored at ~/.brokre/audit/audit.log (HMAC-chained). Command arguments are uniformly redacted as <REDACTED>. New events include a source field (cli, mcp, or manage). The manage UI Audit log tab and MCP brokre_audit_list expose the same metadata.

Manage UI security

• 127.0.0.1 only; session token in terminal
• Passwords: create / rotate only — no read API
• Delete / rotate require reveal passphrase (or YES for auto-saved records)
• 15-minute idle timeout

Architecture

┌─────────┐     ┌──────────┐     ┌─────────────┐     ┌────────────┐
│ AI/User │────▶│ brokre CLI│────▶│ OS Keychain │────▶│ Vault File │
└─────────┘     └──────────┘     └─────────────┘     └────────────┘
                      │
                      ▼
               ┌─────────────┐
               │  PTY + inj. │──▶ any CLI on PATH (ssh, mysql, gsql, …)
               └─────────────┘

• Double encryption: unique DEK per field; wrapped for exec and reveal separately.
• Vault metadata: profile, name, host_alias, saved_args in cleartext beside ciphertext (THREAT_MODEL.md T3).
• SSH private keys: 0600 temp file + -i for the session (docs/HARDENING.md).

Preset manage UI groups

Convenience tabs when the binary is on PATH:

Roadmap

Today: generic PTY wrapper + manage.toml groups + prompts.toml overrides.

Planned: full TOML connector profiles under ~/.brokre/profiles/ with per-tool injection strategies.

Piped stdin and OpenSSH sharing

• Piped stdin (tar | brokre ssh host 'tar xf -'): pipe data forwards only after injection completes.
• OpenSSH family (ssh, scp, sftp): shared saved credentials when the host matches. Interactive save required first (TTY).

Development

cargo test    # unit tests in src/ only (no tests/ integration suite in this repo)
cargo clippy --all-targets --all-features -- -D warnings
cargo build --release   # binary: target/release/brokre

Release version is declared in VERSION (also reflected in Cargo.toml and packages/brokre-mcp/package.json). Official binaries and npm packages are published by TechinOne via GitHub Releases and CI — not part of this open-source tree.

License

MIT — see LICENSE.

Techinone · 成都同创合一科技有限公司