🔐 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---
🚀 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): ``bash curl -fsSL https://raw.githubusercontent.com/KpihX/bw-proxy/main/install.sh | sudo bash ``
What it does internally:
- Image: Pulls
ghcr.io/kpihx/bw-proxy:latest. - Binary: Creates
/usr/local/bin/bw-proxy(owned by root). - Config: Creates
/etc/bw-proxy/. - 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:
- Port Allocation: The host shim finds a free random port.
- Container Launch: The appliance starts, mapping the internal HITL server to that port.
- URL Interception: The shim detects the Approval URL in stdout and automatically opens your browser.
- 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
1. CLI Mode (Recommended for Humans & AI Agents) 🚀
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. ``bash 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-proxydirectory 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. ``bash 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.
