Home

BlacklistedAIProxy: The Official Wiki

[ Blacklisted Binary Labs ] — We didn't get the memo saying we had to play nice.

Welcome to the central intelligence repository for BlacklistedAPI. This wiki covers everything from high-level architecture to deployment, troubleshooting, and advanced proxy manipulation.

---

💀 1. What It Is & Why You Need It

BlacklistedAPI is an OpenAI-compatible reverse proxy gateway designed to jailbreak client-only restrictions on top-tier AI models (Gemini, Claude Kiro, Grok, Codex, Qwen, Kimi).

Why use it? Big AI companies lock their free or CLI-based models behind proprietary clients. If you want to use them in your own IDE or scripts, you usually have to pay premium API fees. BlacklistedAPI acts as a middleman—impersonating official clients, bypassing TLS fingerprints, and converting proprietary protocols into a standard OpenAI-compatible API stream.

The Result: You get to use models like Claude Opus 4.5, Gemini 3 Pro, and Grok 3/4 in your own tools for free (within the provider's native usage limits).

---

🗺️ 2. How It Works: The Architecture

BlacklistedAPI operates via a multi-stage pipeline:

1. Protocol Conversion Bridge: Listens for standard OpenAI REST payloads and translates them into Anthropics (Claude) or Google (Gemini) formats on the fly.
2. Gateway Router: Detects the requested model (either via URL path routing or the payload body) and dispatches it.
3. Provider Pool Manager: Handles multiple authenticated accounts. If Account 1 is rate-limited, it automatically routes to Account 2 (Round-Robin with async token refresh).
4. Go TLS Sidecar (uTLS): Bypasses Cloudflare and other WAFs by spoofing legitimate browser JA3/TLS fingerprints. Node.js natively gets blocked; the Go sidecar sneaks you in.
5. Observability Engine: OpenTelemetry and Langfuse trace every request for granular debugging.

---

🚀 3. Core Features

• Protocol Jailbreak Engine: Handles OAuth 2.0 PKCE, session simulation, and token refreshes.
• Account Pooling: Multi-account failover, deduplication, and concurrency limits.
• TLS Fingerprint Spoofing: Embedded Go microservice to bypass WAFs.
• Red-Teamed Security: Hardened with Promptfoo evaluation suites.
• API Potluck: Community key-sharing pool for load distribution.
• WRB Tauri Desktop Dashboard: A premium, native Windows tabbed UI for managing configs, pools, and telemetry.

---

🩸 4. History, Lineage & Repurposed Code

We didn't write everything from scratch because rewriting working code is a waste of cycles. We stripped the best parts from several legendary open-source codebases, bolted them together, and weaponized the result. Here is the DNA of BlacklistedAPI:

The Core Engines

• router-for-me/CLIProxyAPI (Go):
  • What we took: The original CLI proxy engine logic, OpenAI/Gemini/Claude/Codex endpoint compatibility, and the foundational multi-account round-robin scheduler.
  • Why we used it: They proved the concept worked. They built the upstream spoofing primitives we needed to start bypassing client restrictions.
• justlovemaki/AIClient-2-API (Node.js):
  • What we took: The Node.js implementation, the Web UI management console architecture, the TLS fingerprint bypass sidecar integration, and multi-protocol conversion logic.
  • Why we used it: It provided a massive UX upgrade and native Node.js extensibility, allowing us to drop in enterprise telemetry and the promptfoo hardening suites.

The Desktop UI Stack

For the WRB Tauri Desktop App, we cannibalized high-end UI primitives to build a luxury tabbed dashboard without writing boilerplate:

• tauri-apps/tauri (Rust/Web): Used as the core native Windows shell wrapper for deep system integration.
• greensock/GSAP: Repurposed for motion choreography and premium interaction feel (glass panel transitions).
• shoelace-style/shoelace: Stripped for their modern Web Component tab primitives to handle our Dashboard/Workspace/Provider routing.
• floating-ui/floating-ui: Used strictly for smart tooltip positioning and micro-interactions.
• chartjs/Chart.js: Integrated specifically to power the header sparkline telemetry widgets.
• micku7zu/vanilla-tilt.js: Dropped in to provide the subtle depth/tilt effect on the glass UI panels.

---

📖 5. Deployment Guides & Walkthroughs

🐳 Docker (Recommended for Servers)

The cleanest way to run the proxy.

docker run -d \
  -p 3000:3000 \
  -p 8085-8086:8085-8086 \
  -p 1455:1455 \
  -p 19876-19880:19876-19880 \
  --restart=always \
  -v "$(pwd)/configs:/app/configs" \
  --name blacklistedapi \
  crazyrob425/blacklisted-api

Access the management UI at http://localhost:3000.

🪟 Windows Native (Installer & Portable)

Download the latest .exe from Releases.

• Full Install: Installs as a Windows Service (BlacklistedAIProxy) with a self-healing watchdog. Runs at boot natively.
• Portable Mode: Installs to a removable drive, runs completely in RAM via %TEMP%, and wipes all traces upon exit.

🚘 WRB Tauri Desktop App

For a native Windows UI experience:

cd desktop/wrb-dashboard-tauri
npm install && npm run tauri:build

---

🔌 6. Integrations (Connecting Your Apps)

Point your favorite AI-assisted tools to your local gateway (http://localhost:3000).

Tool	Setting	Value
Cherry-Studio	API Base URL	http://localhost:3000
Continue.dev	API Base URL	http://localhost:3000
Cline	API Base URL	http://localhost:3000
OpenCode	Base URL	http://localhost:3000

---

🛠️ 7. Tips, Tricks & Shortcuts

Hardcode Routing via Path

If your client doesn't let you specify models cleanly, force the routing via the API endpoint path:

# Force Gemini
POST http://localhost:3000/gemini/v1/chat/completions

# Force Grok
POST http://localhost:3000/grok/v1/chat/completions

System Prompt Injection

Override or append system prompts at the gateway level in configs/config.json:

{
  "systemPrompt": {
    "mode": "override",
    "content": "You are a helpful assistant deployed via BlacklistedAPI. Answer concisely."
  }
}

Plugins

Activate built-in plugins from the UI:

• AI Monitor: Sniffs raw payloads pre/post conversion.
• Langfuse Bridge: Ships telemetry directly to Langfuse.

---

⚠️ 8. Common Issues & Fixes

Issue: Requests are timing out or getting 403 Forbidden. Cause: Cloudflare or WAF blocked your IP/Node.js client. Fix: Ensure the Go TLS Sidecar is running. Check port conflicts.

Issue: Rate Limit Exceeded on a specific model. Cause: You exhausted your free tier on that specific upstream provider. Fix: Add additional authenticated accounts to your Provider Pool via the UI. The router will automatically failover to the next healthy account.

Issue: Windows Service crashes silently. Cause: Node.js memory leak or fatal upstream error. Fix: The installer configures BlacklistedAIProxyWatchdog. Ensure the watchdog service is enabled in services.msc to auto-restart the proxy within 5 seconds.

---

🔮 9. Future Plans & Roadmap

We are scaling BlacklistedAPI from a simple proxy into a localized AI operating system. The following modules are actively in R&D:

🎞️ Multimodal & Video Gen Pipelines

Text streams are solved; the next frontier is heavy binary payloads. We are reverse-engineering the undocumented WebSocket (WS/WSS) endpoints used by Grok and Gemini for real-time video generation and multimodal ingestion.

This requires rewriting the core bridge to support chunked binary streaming, allowing you to feed local video files through the proxy and receive generative video outputs using the standard OpenAI /v1/audio and /v1/video endpoints (which we are polyfilling). We will implement local caching and FFmpeg integration to ensure format compliance before hitting the upstream providers, drastically cutting down on rejected payloads.

🛡️ Expanded Auth & Headless Session Extraction

OAuth PKCE is great, but providers are getting smart. To combat strict endpoints (like Anthropic's browser-only Web UI), we are integrating a lightweight, headless Playwright/Puppeteer module.

This engine will dynamically spin up invisible browser instances to solve CAPTCHAs, execute localized JavaScript challenges, extract active session cookies, and inject them directly into the Go TLS sidecar. Token rotation will become fully automated—when a session expires, the headless worker will quietly log back in, grab a fresh JWT/Cookie, and update the Account Pool without dropping a single API request.

🕸️ P2P Mesh Network (API Potluck 2.0)

The current API Potluck is centralized; we're moving it to a decentralized peer-to-peer mesh. By implementing WebRTC and a localized DHT (Distributed Hash Table), BlacklistedAPI instances will be able to share token buffers and route requests through each other.

If your IP is hardware-banned by Cloudflare for hitting xAI too hard, the mesh will transparently route your Grok request through another user's proxy in a different geographic region. E2E encryption will ensure that neither the middleman nor the proxy host can read your prompts or API keys, creating an unblockable, distributed compute cluster of free AI accounts.

🛒 The Plugin Marketplace

We are opening the gateway up. We are building a native Plugin Marketplace within the WRB Desktop App, allowing users to browse, install, and update community-built middleware scripts with a single click.

Plugins will have full access to the pre- and post-flight request lifecycle. Some of the badass, high-end plugins already in development include:

• God-Mode Auto-Jailbreaker: Detects the target model and dynamically wraps your prompt in the exact specific "Developer Mode" or "DAN" exploit currently working for that specific LLM version, stripping provider guardrails automatically.
• Token Launderer: Modifies prompt syntax, injects noise, and alters request timing/headers to obfuscate your AI footprint, making it mathematically impossible for providers to build a behavioral profile on your account to ban you.
• Bounty Hunter: A background worker that scrapes GitHub, Pastebin, and Discord for leaked, valid API keys and auto-injects them into your load-balancing pool.

🤖 Built-in MCP Swarm Chatbot

You shouldn't need a third-party UI to use the proxy you just built. We are embedding an optional, native Chatbot Interface directly into the dashboard.

This isn't just a standard chat wrapper—it is hardwired for Multi-Agent Swarms and features full MCP (Model Context Protocol) server support. You can configure a swarm where Claude Opus acts as the orchestrator, Gemini handles rapid web search, and Qwen writes the code. You type one prompt, the built-in UI splits it across your proxy pool concurrently, synthesizes the results, and executes commands locally using MCP to read your file system or hit local databases.

---

🤝 10. Call for Collaborators: We Need Hackers

BlacklistedAPI is growing faster than we can write code. If you looked at the roadmap above and thought, "I know exactly how to build that," then we want you.

We are actively looking for collaborators to help build out the future of this proxy. We need:

• Go Developers: To harden the uTLS sidecar and implement new WAF bypass techniques.
• Node.js/TypeScript Engineers: To build out the Plugin Marketplace and MCP Swarm orchestrator.
• Reverse Engineers: To break down undocumented APIs (OpenAI, Anthropic, xAI) and extract their auth flows.
• UI/UX Designers: To continue polishing the Tauri desktop dashboard and the new built-in Chatbot.

How to help:

1. Check the Issues tab for anything tagged help wanted or good first issue.
2. Fork the repo, build a proof-of-concept for one of the roadmap items, and drop a Pull Request.
3. Found a new undocumented API endpoint? Open a discussion thread or submit an adapter PR.

We don't care about your resume. If your code compiles and bypasses the firewall, you're in. If it follows the rules or has corporate overlord propaganda written all over it, you're out.

---

Built with spite, Node.js, and an unhealthy obsession with free AI models.