Skip to main content
Glama
bw-proxy

bw-proxy

by KpihX

๐Ÿ” BW-Proxy โ€” Sovereign Bitwarden Appliance

Zero Trust ยท AI-Blind ยท ACID Durable
The authoritative appliance for Bitwarden organization vault control. Keep AI agents and LLMs blind to your real secrets while giving them full auditing and refactoring powers.


๐Ÿ›๏ธ Project Architecture (Sovereign Tree)

BW-PROXY PROJECT
โ”œโ”€โ”€ ๐Ÿ“‚ src/bw_proxy/     โ—„โ”€โ”€ Core Engine (ACID Transaction, WAL, Redaction)
โ”œโ”€โ”€ ๐Ÿ“‚ scripts/          โ—„โ”€โ”€ Host-side Shims (Dynamic porting, Browser HITL)
โ”œโ”€โ”€ ๐Ÿ“‚ docs/             โ—„โ”€โ”€ Deep-dive Hardening & Operator Guides
โ”œโ”€โ”€ ๐Ÿ“„ install.sh        โ—„โ”€โ”€ System-wide Appliance Installer (Root-owned)
โ”œโ”€โ”€ ๐Ÿ“„ Makefile          โ—„โ”€โ”€ Developer & Release Automator
โ””โ”€โ”€ ๐Ÿ“„ Dockerfile        โ—„โ”€โ”€ Multi-stage Hardened Runtime

Related MCP server: stillvault-mcp

๐Ÿš€ Installation Modes

A. Appliance Mode (Standard Pro)

Ideal for production use. Installs a root-owned binary and uses the official image.

Via curl (Zero-Clone):

curl -fsSL https://raw.githubusercontent.com/KpihX/bw-proxy/main/install.sh | sudo bash

What it does internally:

  1. Image: Pulls ghcr.io/kpihx/bw-proxy:latest.

  2. Binary: Creates /usr/local/bin/bw-proxy (owned by root).

  3. Config: Creates /etc/bw-proxy/.

  4. Data: Creates a persistent Docker volume bw_mcp_bw-data.


B. Developer Mode (Source Clone)

Ideal for contribution or source-level auditing.

git clone https://github.com/KpihX/bw-proxy.git
cd bw-proxy
make docker-install  # Requires SUDO for builds

โš™๏ธ Core Mechanisms (The Magic)

1. The HITL Browser Flux

When an AI agent requests a vault change, the proxy intercepts the execution:

  1. Port Allocation: The host shim finds a free random port.

  2. Container Launch: The appliance starts, mapping the internal HITL server to that port.

  3. URL Interception: The shim detects the Approval URL in stdout and automatically opens your browser.

  4. Human Approval: You review the rationale and the diff, then approve with your Master Password.

2. The 3-Phase ACID Commit (WAL)

Every mutation is transactional.

  • Simulation: Actions are validated in RAM first.

  • WAL: Actions are encrypted and logged to disk before execution.

  • Commit: Actions are sent to the Bitwarden CLI.

  • Rollback: If a crash occurs, the proxy performs a LIFO rollback on the next start.

3. Scoped Union Fetch

To handle organizational vaults without metadata loss:

  • The proxy discovers all accessible Organizations and Collections first.

  • It then performs scoped queries (--organizationid) to fetch "rich" items with full metadata.

  • It merges results with the global vault list, ensuring organizational assignments are preserved.


๐Ÿ•น๏ธ Interface Modes

The CLI is the most efficient and agnostic way to interact with the appliance. It uses RPC 2.0 (JSON), supports exact examples, and provides rich help documentation.

For AI Agents: Using the CLI via run_command is more token-efficient than MCP and offers greater flexibility.

bw-proxy admin status   # Health check
bw-proxy admin unlock   # Create a 5-minute session lease
bw-proxy do list-items  # Quick redacted scan
TIP

AI Integration: To enable full AI recognition of these commands, copy the .agents/skills/bw-proxy directory to your global ~/.agents/skills/ or into a project-specific .agents/skills/ directory.

2. MCP Mode (Standard Stdio)

Start the stdio server for standard MCP clients like Gemini, Claude, or Cursor.

bw-proxy mcp serve

๐Ÿ› ๏ธ Maintenance & Release

  • Update: curl ... | sudo bash (re-runs the installer).

  • Uninstall: sudo ./uninstall.sh.

  • Release (Dev): make release (automatic tagging and GHCR propulsion).


โš–๏ธ License

MIT License. See LICENSE for details.

Designed with โค๏ธ by KpihX.

Available Tools

10 tools
compare_secrets_batchD

Inputs: payload (required). Returns: result

find_all_vault_duplicatesD

Inputs: payload (required). Returns: result

find_duplicates_batchD

Inputs: payload (required). Returns: result

find_item_duplicatesD

Inputs: payload (required). Returns: result

get_proxy_audit_contextD

Inputs: limit. Returns: result

get_templateD

Inputs: template_type (required). Returns: result

get_vault_mapD

Inputs: folder_id, trash_state, include_orgs, search_items, +3 more. Returns: result

inspect_transaction_logD

Inputs: n, tx_id. Returns: result

propose_vault_transactionD

Inputs: rationale (required), operations (required). Returns: result

refactor_item_secretsD

Inputs: rationale (required), operations (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    D1.5/5.0

    Scored across 10 tools

    Disambiguation2/5

    Multiple tools focus on finding duplicates (find_all_vault_duplicates, find_duplicates_batch, find_item_duplicates) with unclear scope distinctions. Without descriptions, an agent would likely struggle to choose between them.

    Naming Consistency2/5

    Naming patterns are inconsistent: some start with 'find', some with 'get', others with different verbs (compare, inspect, propose, refactor). The placement of 'batch' varies, and there is no consistent verb_noun structure.

    Tool Count4/5

    10 tools is a reasonable count for a specialized secret management proxy. It covers a variety of operations without being excessive, though some categories are overrepresented.

    Completeness2/5

    The tool set lacks basic CRUD operations (create, read, update, delete) for items or vaults. Advanced operations like proposing transactions and refactoring are present, but foundational actions are missing, leaving significant gaps.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents and automation scripts to securely interact with self-hosted Vaultwarden instances through the Bitwarden CLI, automatically managing vault sessions and providing tools to read, create, update, and delete secrets programmatically.
      9 npm
      2
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to securely use real secrets (API keys, database passwords) by requiring human approval for each release, ensuring secrets never enter the model's context.
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides a zero-knowledge credential vault for AI agents, allowing secure storage, retrieval, and management of secrets with cross-agent delegation and tamper-evident audit.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to securely read and write to an Obsidian-compatible Markdown vault with per-agent access control, audit logging, and conflict resolution.
      Apache 2.0