Black Vault

BlackVault

The open-source API key firewall for AI agents. Agents never see the real key. Kill access instantly. Per-token rate limits, budgets, and model restrictions.

Quick Start • Universal Gateway • Features • Proxy Usage • Access Controls • Deploy • Issues • Contributing

---

The Problem

When you share an API key with an AI agent (OpenClaw, Moltbook bots, LangChain, CrewAI, or any agent framework), you can't revoke just that agent's access without rotating the key and breaking every other agent that uses it.

BlackVault fixes this with a proxy layer:

Agent → BlackVault (bvt_ token) → OpenAI / Anthropic / Google / Nebius (real key)
         ↑                         ↑
    You control this          Agent never sees this

One key, many proxy tokens. Kill a token = instant 401. No rotation needed.

Universal AI Gateway

One endpoint. One token. Every AI provider. BlackVault includes an OpenAI-compatible gateway at /api/v1/chat/completions that auto-routes to the correct provider based on the model name and translates request/response formats automatically.

# Use Claude through BlackVault (auto-translates OpenAI format → Anthropic)
curl https://your-blackvault.vercel.app/api/v1/chat/completions \
  -H "Authorization: Bearer bvt_your_token" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-5-20250929", "messages": [{"role": "user", "content": "hello"}], "max_tokens": 1024}'

# Use GPT through the same endpoint and token
curl https://your-blackvault.vercel.app/api/v1/chat/completions \
  -H "Authorization: Bearer bvt_your_token" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "hello"}]}'

# Use Gemini through the same endpoint and token
curl https://your-blackvault.vercel.app/api/v1/chat/completions \
  -H "Authorization: Bearer bvt_your_token" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-2.0-flash", "messages": [{"role": "user", "content": "hello"}]}'

Works with ANY OpenAI-compatible tool

OpenClaw:

OPENAI_BASE_URL=https://your-blackvault.vercel.app/api/v1
OPENAI_API_KEY=bvt_your_token

LangChain (Python):

from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
    base_url="https://your-blackvault.vercel.app/api/v1",
    api_key="bvt_your_token",
    model="claude-sonnet-4-5-20250929"  # or gpt-4o, gemini-2.0-flash, etc.
)

OpenAI SDK (Python):

import openai
client = openai.OpenAI(
    base_url="https://your-blackvault.vercel.app/api/v1",
    api_key="bvt_your_token"
)
response = client.chat.completions.create(
    model="claude-sonnet-4-5-20250929",  # any model, any provider
    messages=[{"role": "user", "content": "hello"}]
)

OpenAI SDK (Node.js):

import OpenAI from "openai";
const client = new OpenAI({
  baseURL: "https://your-blackvault.vercel.app/api/v1",
  apiKey: "bvt_your_token",
});
const response = await client.chat.completions.create({
  model: "gemini-2.0-flash", // routes to Google automatically
  messages: [{ role: "user", content: "hello" }],
});

Cursor / Continue / Cline: Set the base URL to https://your-blackvault.vercel.app/api/v1 and API key to bvt_your_token in your IDE settings.

How it works

| Model prefix | Routes to | Format translation | |---|---|---| | gpt-*, o1*, o3* | OpenAI | None (native) | | claude-* | Anthropic | OpenAI ↔ Anthropic Messages API | | gemini-* | Google AI | OpenAI ↔ Gemini API | | deepseek-ai/*, meta-llama/* | Nebius | None (OpenAI-compatible) |

The gateway looks up the user's vault key for the target provider automatically. One bvt_ token can access ALL providers the user has keys for.

MCP Server

BlackVault is also a remote MCP server, so any MCP client (Claude Desktop, Cursor, Claude Code, …) can get governed access to your vaulted AI keys. Your MCP config holds a bvt_ token — never a provider key — and every tool call is subject to your budget caps, rate limits, model restrictions, kill switch, and audit trail.

Endpoint: https://your-blackvault.vercel.app/api/mcp (JSON-RPC 2.0 over Streamable HTTP)

Config (Claude Desktop / Cursor mcp.json):

{
  "mcpServers": {
    "blackvault": {
      "url": "https://your-blackvault.vercel.app/api/mcp",
      "headers": { "Authorization": "Bearer bvt_your_token" }
    }
  }
}

Tools exposed:

| Tool | What it does | |------|--------------| | list_models | Lists the models this token may use, across your vaulted provider keys. | | chat | Runs a completion on any allowed model (gpt-*, claude-*, gemini-*, open-source via Nebius). BlackVault injects the real key, enforces budget/rate/model limits, and audits the call. |

The agent never sees a provider key, and revoking the bvt_ token (or hitting the kill switch) blocks its next MCP call instantly. See [docs/design/0002-mcp-credential-broker.md](docs/design/0002-mcp-credential-broker.md) for the roadmap (generic HTTP-credential brokering and upstream-MCP proxying are next).

Features

Core

• Universal AI Gateway — One OpenAI-compatible endpoint for ALL providers. Auto-routes by model name, translates formats. Works with OpenClaw, LangChain, CrewAI, Cursor, and any OpenAI-compatible tool.
• Encrypted Vault — AES-256-GCM with per-user derived keys. Zero-knowledge at rest.
• Proxy Gateway — Forward requests to OpenAI, Anthropic, Google AI, Nebius AI with full SSE streaming.
• Instant Kill Switch — Revoke a session, a key, or everything. Propagates in

X-BlackVault-Cost: 0.003200 X-BlackVault-Budget-Limit: 5.0000 X-BlackVault-Budget-Remaining: 4.9968 X-Session-RateLimit-RPM-Limit: 30 X-Session-RateLimit-RPM-Remaining: 28 X-BlackVault-Allowed-Models: gpt-4o-mini,gpt-3.5-turbo

## Architecture

src/ ├── app/ │ ├── api/ │ │ ├── v1/chat/completions/ # Universal AI Gateway (OpenAI-compatible) │ │ ├── v1/models/ # Available models endpoint │ │ └── proxy/[provider]/[...path]/ # Direct proxy gateway │ ├── (dashboard)/ # Dashboard pages │ └── page.tsx # Landing page ├── server/ │ ├── db/schema.ts # Drizzle schema (Postgres) │ ├── routers/ # tRPC routers │ │ ├── vault.ts # Key CRUD + encryption │ │ ├── proxy.ts # Token generation, sessions, rate limits │ │ ├── killswitch.ts # Emergency revocation │ │ └── cost.ts # Real-time cost queries │ └── services/ │ ├── encryption.ts # AES-256-GCM encrypt/decrypt │ ├── proxy-auth.ts # Token auth + IP/budget enforcement │ ├── model-router.ts # Model → provider auto-routing │ ├── format-translator.ts # OpenAI ↔ Anthropic/Google translation │ ├── proxy-providers.ts # Provider configs │ ├── proxy-pricing.ts # Token cost estimation │ ├── ratelimit.ts # Global + per-session rate limiting │ └── redis.ts # Upstash Redis cache └── lib/ ├── constants.ts # Provider configs, activity types └── utils.ts # Shared utilities

## Tech Stack

| Layer | Technology |
|-------|------------|
| Framework | Next.js 16 + React 19 + TypeScript |
| API | tRPC 11 |
| Database | Neon Postgres + Drizzle ORM |
| Cache & Rate Limiting | Upstash Redis |
| Auth | Clerk |
| Styling | Tailwind CSS v4 + Framer Motion |
| Encryption | AES-256-GCM (Node.js crypto) |
| Charts | Recharts |

## Security

- API keys encrypted at rest with AES-256-GCM using per-user derived keys (HMAC-SHA256)
- Proxy tokens SHA-256 hashed before storage -- plaintext never persisted
- Session lookups Redis-cached (60s TTL) for fast revocation
- **Three-tier rate limiting:** global (200 RPM/user) + per-session RPM + per-session RPD via Redis sliding window
- **Budget enforcement:** session-level spend caps block at 402 when exhausted
- **Model restrictions:** per-session model allowlists prevent unauthorized model usage
- **IP allowlisting:** per-session IP restrictions enforced at auth time
- CORS allows `*` on proxy (tokens are the auth boundary, not origin)
- All secrets are environment variables -- never in code

## Deploy

### Vercel (recommended)

1. Fork this repo
2. Import in [Vercel](https://vercel.com)
3. Add environment variables from `.env.example`
4. Deploy

### Self-hosted

```bash
npm run build
npm start

Roadmap

• [x] Universal AI Gateway -- OpenAI-compatible endpoint, auto-routes to any provider
• [x] Per-Session Rate Limiting -- Configurable RPM/RPD per proxy token
• [x] Budget Caps & Model Restrictions -- Per-token spend limits and model whitelists
• [x] MCP Server -- Remote MCP server (/api/mcp) exposing governed list_models + chat tools to Claude Desktop, Cursor, Claude Code, etc.
• [ ] OpenClaw Skill -- Official skill for the OpenClaw AI assistant
• [ ] Groq, Mistral, Together AI -- More provider support
• [ ] Webhook alerts -- Notify when budget thresholds hit or rate limits trigger
• [ ] Token scoping -- Per-token endpoint restrictions
• [ ] Usage analytics dashboard -- Graphs of cost, latency, and token usage over time
• [ ] Team workspaces -- Shared vaults with role-based access

Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

Good first issues: Check the good first issue label.

Contributors

Star History

If BlackVault is useful to you, consider giving it a star. It helps others discover the project.

[](https://star-history.com/#venkat22022202/black-vault&Date)

License

[MIT](LICENSE)

Source & license

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

• Author: venkat22022202
• Source: venkat22022202/black-vault
• License: MIT
• Homepage: https://black-vault-murex.vercel.app

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