Skip to content

About

Web UI for managing LiteLLM proxy backends, models and API usage

Resources

Stars

4 stars

Watchers

1 watching

Forks

Repository files navigation

Bipolar Code

Tu gateway personal de LLMs, self-hosted. Una sola app que:

  • Sirve modelos locales grandes con llama.cpp gestionado (multi-GPU AMD/NVIDIA vía Vulkan, tensor-split automático, descarga de modelos desde Hugging Face en la UI).
  • Gestión inteligente (2.13): clasifica cada request por complejidad y lo enruta al destino con cuota y capacidad (modo shadow para probar sin riesgo), y delega tareas de código a los CLIs instalados (Claude Code, Codex, Copilot, Antigravity, Ollama) según tier y cuota.
  • Habla los dos idiomas: Anthropic Messages API (/v1/messages) y OpenAI (/v1/chat/completions) — cualquier herramienta que use Claude o un endpoint OpenAI-compatible puede apuntar aquí.
  • Enruta por escenario: tareas background → modelo chico, código → modelo grande local, razonamiento pesado → Anthropic real. Con failover automático si un provider local está caído.
  • Gestiona providers cloud (Copilot, Anthropic, NVIDIA NIM, OpenRouter, DeepSeek…) con cambio de un clic, chat con streaming, tracking de uso/costos.
Claude Code / OpenClaw / VS Code / Cursor / bot Telegram
        │  (Anthropic API u OpenAI API + tu API key)
        ▼
  bipolar-code :8000  ──routing──►  llama-server local (tus GPUs)
                      ──routing──►  GitHub Copilot / Anthropic / NIM / …

Capturas

Dashboard: estado del proxy y proveedor activo Providers: routing por escenario y gestión inteligente
Dashboard: estado del proxy y cambio de proveedor con un clic. Providers: reglas por escenario, failover y tabla tier → providers (modo shadow).
Agentes: delegación y orden por tier Agentes CLI detectados con versión y cuota
Agentes: workspaces permitidos, orden de agentes por tier y pensadores. Agentes CLI: CLIs detectados con versión, auth, cuota y tope mensual.
Usage: gasto por período y por provider Settings: claves de cada provider enmascaradas
Usage: gasto por período y requests/tokens por provider. Settings: claves de cada provider, siempre enmascaradas.

Las capturas ocultan montos, rutas y claves.


Quick Start (desde cero, sin experiencia)

  1. Descarga el ejecutable de la página de Releases:

    • bipolar-code-windows.exe — Windows
    • bipolar-code-linux — Linux
    • bipolar-code-macos — macOS
  2. Ejecútalo:

    • Windows: doble clic en bipolar-code-windows.exe
    • Linux/macOS: chmod +x bipolar-code-linux && ./bipolar-code-linux

    Al primer arranque crea solo su directorio de configuración (Windows: C:\litellm\, Linux/macOS: ~/.litellm/) y genera una API key propia — no necesitas crear nada a mano.

  3. Abre http://localhost:8000. La UI te pedirá la API key la primera vez: está en Settings → Acceso y Seguridad → Copiar API Key completa (o en el archivo .env del directorio de configuración, variable UI_API_KEY).

  4. Elige un provider en la pestaña Providers y pulsa Activar. Para probar sin GPU ni cuentas de pago: NVIDIA NIM (gratis con registro) u OpenRouter (tiene modelos free). Las keys de cada provider se pegan en Settings.

  5. (Solo si vas a usar providers cloud vía proxy — Copilot/Anthropic): instala litellm una vez:

    pip install litellm

    Para modelos locales (llama.cpp, LM Studio, Ollama) no hace falta: bipolar-code les habla directo.

Listo. Todo lo demás son casos de uso.


Caso de uso 1 — Claude Code con el backend que tú elijas

En este PC: Dashboard → Routing de Claude Code → Proxy. Eso escribe ANTHROPIC_BASE_URL/ANTHROPIC_API_KEY por ti (settings.json + registro en Windows). Reinicia Claude Code y ya está pasando por bipolar-code. Volver a Anthropic directo = un clic (Direct).

En otros PCs de tu red: Settings → Conectar PCs remotas muestra el snippet exacto con tu IP LAN:

// ~/.claude/settings.json → "env"
"ANTHROPIC_BASE_URL": "http://192.168.x.x:8000",
"ANTHROPIC_API_KEY": "<tu API key de bipolar-code>"

Un portátil sin GPU usa los modelos del PC grande. Fuera de tu LAN: VPN (Tailscale/WireGuard), nunca expongas el puerto a internet.

Caso de uso 2 — Modelo local grande (llama.cpp gestionado)

  1. Descarga un release Vulkan de llama.cpp y descomprímelo (o pon llama-server en el PATH).
  2. Providers → tarjeta llama.cpp (Local multi-GPU):
    • Pega la ruta de llama-server (si no está en PATH).
    • Modelos (buscar / descargar): busca un GGUF en Hugging Face (ej. Qwen3-Coder-Next Q4_K_M), descárgalo con barra de progreso y pulsa Usar. Modelos gated: variable HF_TOKEN en Settings.
    • Pulsa Iniciar y luego Activar el provider.
  3. El panel detecta tus GPUs y reparte el modelo proporcionalmente a la VRAM libre (--tensor-split automático — dos AMD distintas mezcladas funcionan, ej. R9700 32GB + RX 7800 XT 16GB = pool de 48GB).

Extras del panel:

  • Auto-arranque: levanta llama-server al abrir bipolar-code.
  • Router mode: sirve TODOS los GGUF descargados a la vez con carga/descarga dinámica — cada request elige modelo por nombre (combínalo con el routing por escenario).
  • Logs del servidor en la propia UI para diagnosticar cargas/OOM.
  • Granja multi-PC (avanzado): rpc_servers en la config del provider suma GPUs de otros PCs corriendo ggml-rpc-server (--rpc). Solo vale la pena para modelos que no caben en un solo PC; usa cable 2.5GbE+ y el mismo build de llama.cpp en todos los nodos.

Caso de uso 3 — OpenClaw (o cualquier agente que hable Anthropic)

OpenClaw quema tokens con ganas (system prompt grande, heartbeats). Apuntado a bipolar-code, eso sale gratis en tu GPU:

  • Provider Anthropic de OpenClaw → ANTHROPIC_BASE_URL=http://<ip-de-bipolar>:8000 + ANTHROPIC_API_KEY=<tu API key>.
  • Alternativa OpenAI-compat: baseUrl http://<ip>:8000/v1 (mismo camino que OpenClaw usa para Ollama/LM Studio).
  • Recomendado: routing por escenario (abajo) para que sus heartbeats vayan al modelo chico y el trabajo real al grande. Nota: los agentes exigen tool-calling sólido — modelos clase Qwen3-Coder, no 7B genéricos.

Caso de uso 4 — VS Code Copilot Chat, Cursor, Cline, Continue…

VS Code Copilot Chat (proveedor Bipolar)

bipolar aparece como proveedor propio en el selector de modelos de Copilot Chat, con su catálogo de providers/modelos más «Bipolar Auto».

  1. Compila la extensión: cd integrations/vscode-copilot && npm install && npm run package (genera un .vsix).
  2. Instálala en VS Code: Extensions → «…» → «Install from VSIX…» → elige el .vsix.
  3. En Copilot Chat → «Manage Models…» → «Add Models…» → «Bipolar».
  4. Escribe la URL http://<ip>:8000 y la API key de bipolar-code.

En el selector verás:

  • «Bipolar Auto»: bipolar decide en cada mensaje (reglas, routing inteligente, failover).
  • «<provider> · <modelo>»: fuerza ese provider (sin failover a otro provider).

La extensión ajusta Copilot CLI para los modelos de Bipolar y el catálogo consulta Ollama para usar el contexto y las capacidades reales de cada modelo. Detalles: Copilot CLI y las herramientas.

Detalles y solución de problemas: integrations/vscode-copilot/README.md.

Para delegar código a los agentes CLI de bipolar desde Copilot Chat (igual que desde Claude Code), mira el tutorial docs/delegar-desde-copilot.md.

Cursor, Cline, Continue y otros clientes OpenAI-compatible

Cualquier cliente BYOK con proveedor "OpenAI compatible":

  • URL: http://<ip>:8000/v1
  • API key: la de bipolar-code

El request llega al provider activo (o al que diga el routing).

Caso de uso 5 — Routing por escenario + failover transparente

Providers → Routing por escenario. Reglas primer-match-gana sobre el nombre de modelo que pide el cliente:

Patrón Min tokens Provider destino Para qué
haiku 0 llamacpp → GGUF chico Background de Claude Code (gratis y rápido)
opus 0 Anthropic real Solo razonamiento pesado
(vacío) 60000 provider con contexto largo Prompts gigantes
(sin match) — provider activo Todo lo demás

Failover (mismo panel): lista de providers de respaldo — si el destino local no responde, el request cae al primero alcanzable. Ej: copilot, anthropic = si apagaste llama-server, todo sigue funcionando solo.

Pools de llaves: cada provider con auth_env_var puede tener llaves extra (extra_auth_env_vars, se agregan en la tarjeta del provider en Providers → Llaves del pool). El slot 0 es la llave principal y los slots 1..n las extra; solo cuentan los slots con valor en el .env.

Failover dentro del mismo request: si el destino elegido falla, el request se reintenta en la siguiente llave o el siguiente provider antes del primer byte, sin que el cliente vea un error. El orden es llave → provider: un 429 mueve a la siguiente llave del mismo provider; una caída del provider salta a los pasos del siguiente destino.

Qué se reintenta y qué no: se reintenta ante 401/403/429/402 (cuota, rate limit, auth), 5xx/529 (sobrecarga, error del upstream) y fallas de conexión o timeout. No se reintenta ante 400/413/422 ni otros 4xx: un request mal formado se devuelve tal cual, no se pasea por todos los providers.

Cada respuesta dice qué pasó: X-Bipolar-Target: <provider>#<slot> (quién respondió) y X-Bipolar-Attempts: <n> (cuántos intentos hubo). Si ningún destino responde, el cliente recibe un status HTTP real — 429 si hubo cuota o rate limit, 529 si hubo sobrecarga, 502 en otro caso (o el status del error fatal) — con el cuerpo de error en el formato de su API, para que aplique su propio backoff.

Caso de uso 6 — Bot de Telegram

Chatea con tu stack desde el teléfono. En Settings (o el .env):

TELEGRAM_BOT_TOKEN=<token de @BotFather>
TELEGRAM_ALLOWED_CHAT_IDS=123456789

Allowlist vacía = bot inerte (default seguro). El bot responde con el provider activo/ruteado.

Caso de uso 7 — Delegar tareas desde Claude Code (MCP de bipolar)

bipolar-code expone en /mcp un servidor MCP (JSON-RPC sobre HTTP) para delegar tareas de código a los agentes CLI del host, sin plugins. Desde Claude Code, una sola vez:

claude mcp add --transport http --scope user bipolar http://localhost:8000/mcp --header "x-api-key: <ui_api_key>"

(<ui_api_key> es tu API key: Settings → Acceso y Seguridad, o UI_API_KEY en el .env. En otros PCs de la LAN, cambia localhost por la IP del gateway.)

Cinco herramientas:

Herramienta Para qué
delegate Crea un job: task, workspace (ruta absoluta del repo) y opcionales tier, agent, verify (comandos), review, wait_s (0–540, default 0). Con wait_s > 0, espera a que termine o venza.
job_status Estado del job (job_id, wait_s opcional): intentos, verificación, revisión, archivos tocados.
job_output Últimas líneas del log (job_id, tail_chars, default 4000).
cancel_job Cancela un job en curso.
list_agents Agentes habilitados con su estado de cuota.

Los plugins *-plugin-cc siguen funcionando, pero ya no son necesarios: las reglas de delegación pueden llamar a delegate directamente.


Caso de uso 8 — Gestión inteligente: routing por complejidad y delegación a agentes CLI

Providers → Routing inteligente. Cada request a /v1/messages o /v1/chat/completions se clasifica en un tier (trivial, simple, standard, complex) con señales deterministas (tokens, tools, tool_result en curso, intención del último mensaje, hint del modelo pedido, thinking) y va al primer destino elegible de la tabla tier → providers: se descartan los que estén en cooldown por 429/cuota, sin capacidad (tools, visión, contexto), fuera de presupuesto o inalcanzables. Las reglas explícitas del caso 5 siguen ganando.

  • Shadow primero: en modo shadow no cambia ningún destino, solo registra qué habría elegido. Cada respuesta lleva la cabecera X-Bipolar-Route y la decisión queda en Usage → Decisiones de routing (acuerdo legacy↔smart, motivos, rechazos). Cuando te convenza, pásalo a Activo.
  • Explicable: POST /api/smart/explain con un body de ejemplo devuelve tier, puntaje, motivos y destino sin llamar a nadie; X-Bipolar-Tier: complex fuerza el tier desde el cliente.
  • Presupuestos por destino y ventana (día, semana, mes) sobre usage.db.

Pestaña Agentes: bipolar-code detecta los CLIs instalados en el host (claude, codex, copilot, agy de Antigravity, ollama, cursor-agent de Cursor, dsh de DeepSeek Harness, muse de Meta, junie de JetBrains y openrouter, que usa Claude Code), muestra versión, auth y estado de cuota (Antigravity expone sus dos pools con agy -p "/usage", gratis; Cursor informa con cursor-agent about, sin gastar cuota) y delega tareas de código al mejor disponible:

DeepSeek Harness (dsh, la app de escritorio de DeepSeek) es el último carril de todos los tiers (último recurso: cobra por token contra saldo prepago): deepseek-flash en trivial y simple, deepseek-v4-pro en standard y complex. Corre dsh --profile headless --json - con la tarea por stdin y DSH_PERMISSION_MODE=workspace-write: el sandbox del propio dsh (token restringido en Windows) confina las escrituras al workspace y, como el modo headless no tiene a quién pedir aprobación, toda escalada se rechaza. Usa el login de la app (~/.dsh/.credentials.yaml, provider deepseek-account) o, sin login, DEEPSEEK_API_KEY; cobra contra el saldo de platform.deepseek.com (Insufficient Balance marca al agente como agotado). Al actualizar desde una versión anterior, deepseek se agrega una sola vez al final de tu tier_order (y muse al principio); después el orden es tuyo. En Windows, el sandbox de dsh necesita que tu usuario tenga control total explícito sobre el workspace: con solo derechos de dueño (típico en carpetas fuera del perfil, como C:\proyectos) su herramienta de shell falla con SetNamedSecurityInfoW failed (Win32 5) aunque las ediciones de archivos funcionen. Arreglo, una vez por árbol: icacls C:\proyectos /grant <usuario>:(OI)(CI)F.

Muse Code de Meta es el primer carril de todos los tiers del broker y usa el modelo predeterminado de tu cuenta. Se ejecuta en modo headless con --no-foreign-personal-context para no cargar reglas personales de Claude Code; en Windows, comprueba el sandbox con muse sandbox windows check y configúralo con muse sandbox windows setup si no está listo. Las ejecuciones headless pueden ser lentas; evita workspaces privados bajo %USERPROFILE%\AppData, donde el shell aislado de Muse puede quedarse colgado.

Cursor requiere ~/.cursor-rescue/cli-config.json, generado por /cursor:setup del plugin cursor-plugin-cc; sus reglas permissions.deny prevalecen sobre --force. En el plan Free de Cursor solo funciona el modelo auto.

JetBrains Junie (junie) corre su CLI en modo headless con la tarea por stdin, el modelo gratuito junie-lite por defecto (la capa gratis solo permite ese; con créditos JetBrains puedes poner otro modelo por tier) y todas las ubicaciones por defecto de Junie apagadas, para que no importe tus skills y comandos de ~/.claude; si quieres darle skills, ponlas en skill_locations del agente. Atención: en Windows Junie headless aprueba cualquier comando solo, ignora su allowlist.json y no tiene sandbox ni modo solo lectura: revisa siempre el diff. Inicia sesión una vez con junie en una terminal (o exporta JUNIE_API_KEY). Se agrega una sola vez a tu tier_order justo antes de deepseek.

OpenRouter (openrouter) usa claude -p contra la API Anthropic de https://openrouter.ai/api y solo admite modelos :free. Requiere una workspace_allowlist propia; si está vacía, el broker rechaza el job. Como los modelos gratis pueden guardar los prompts, no incluyas secretos en la tarea. Claude Code usa un CLAUDE_CONFIG_DIR aislado y el sondeo valida la clave con GET /api/v1/key sin consumir requests. Si un modelo recibe rate limit, está sobrecargado o deja de estar disponible, el broker prueba otro modelo :free configurado; el agotamiento de cuota diaria no activa ese cambio.

curl -sS -H "x-api-key: $KEY" -H "content-type: application/json" -d '{"task":"Genera tests para src/pagos.py (firmas abajo) ...","workspace":"C:/repos/miapp"}' http://localhost:8000/api/delegate/jobs
  • El broker clasifica la tarea, recorre el orden de agentes de ese tier y salta los agotados, no instalados u ocupados. Si un intento muere por cuota (429, out of credits, RESOURCE_EXHAUSTED, el stream was interrupted de agy) marca al agente como exhausted hasta su reset (5 h, diario o semanal) y reintenta en el siguiente; Antigravity prueba primero su otro pool.
  • Cada job corre como subproceso acotado (timeout, kill del árbol de procesos) dentro de un workspace de la lista blanca, vacía por defecto, así que nada corre hasta que la configures. Los flags de seguridad de cada CLI son fijos: claude acceptEdits sin Task/Agent, codex workspace-write, copilot con deny list de rm, git push, reset, clean y checkout, agy solo si existe tu deny list global. El log se sigue por SSE en GET /api/delegate/jobs/{id}/stream; al terminar, el job trae files_touched.
  • Los CLIs autentican con sus propias sesiones: el hijo recibe un entorno mínimo sin claves del gateway ni ANTHROPIC_BASE_URL, para que un claude hijo no vuelva a entrar por bipolar.
  • Si una tarea pide borrar archivos, el agente los enumera, uno por línea, en .bipolar/jobs/<job>/borrar.txt; no usa comandos de borrado, que siguen bloqueados. bipolar solo acepta rutas relativas, sin .. ni rutas bajo .git o .bipolar, dentro del workspace y sin symlinks; cada ruta debe ser un archivo regular versionado en Git o creado por ese job. El manifiesto se elimina al procesarlo.

/v1 enruta solo entre providers HTTP; los agentes CLI reciben tareas por la API de jobs (un CLI trae su propio loop de herramientas y no puede devolver tool_use a Claude Code a mitad de turno).

Puerta de calidad: cada job pasa por verificación y revisión antes de darse por bueno:

  • verify: lista de comandos (hasta 10) que corren sin shell dentro del workspace, con entorno mínimo y timeout. El primero que devuelva distinto de 0 cuenta como fallo, y un job cuya verificación falla nunca termina como succeeded.
  • review: un "pensador" en solo lectura (de la cadena thinkers, por defecto claude, codex) revisa el diff del job más la salida de los checks y devuelve approve, revise o reject. El revisor nunca es el mismo trabajador.
  • revise con revisiones restantes (max_revisions, por defecto 1): el trabajador vuelve a correr con los issues del revisor. reject, revisiones agotadas o verificación que sigue fallando: se escala al siguiente pensador disponible (o al siguiente carril del tier), que parte del estado que dejó el intento anterior — nunca se revierte nada.
  • Sin pensadores disponibles, la revisión se salta (skipped): tener revisor no es requisito para aprobar.
  • allow_request_verify (Agentes → ajustes, apagado por defecto): con él apagado, pedir verify por API o MCP se rechaza con 400.
  • bipolar compara el árbol antes y después de cada revisión. Si detecta un cambio sin jobs concurrentes en el mismo workspace, invalida el veredicto y termina el job en failed con review_status="tampered"; no escala ni revierte los cambios.
  • Los hallazgos pueden incluir {issue, file, quote}. Las citas se validan contra el archivo o el diff; las que no aparecen se descartan. Si un revise o reject solo tiene citas descartadas, no cuenta como petición de cambios.
  • El trabajador debe terminar con STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED. NEEDS_CONTEXT termina el job sin escalar. BLOCKED también, salvo que el intento no haya cambiado archivos y el job no fije agente: entonces se prueba otro carril una sola vez (suele ser el entorno del carril, p. ej. un sandbox que no arranca). DONE_WITH_CONCERNS entrega sus dudas al revisor.
  • En las rondas posteriores, los pedidos de revisiones anteriores se presentan al revisor como datos delimitados para contrastarlos con la tarea original; la corrección los recibe para conservar los cambios ya pedidos.
  • Si verify falla porque otro proceso bloquea archivos de build, el job termina con verify_environment, sin otra ronda de corrección ni escalada.
  • GET /api/delegate/stats resume aprobaciones por agente y tier. delegation.demote_low_acceptance (apagado por defecto) mueve al final a los agentes cuya aprobación queda bajo demote_below_pct tras al menos demote_min_samples resultados.
  • Los códigos 401/429/503/529 en la salida de un CLI solo cuentan como señales si aparecen con contexto de código HTTP; un número suelto no cambia el estado de cuota, autenticación o sobrecarga. Un status HTTP recibido como tal sí se usa.

Eficiencia de la delegación (2.22): Dashboard y Agentes muestran el panel Eficiencia de la delegación (GET /api/delegate/efficiency?days=N): jobs, tasa de éxito, qué porcentaje de los éxitos hizo Claude (tu misma cuenta o la API pagada), costo reportado, reparto por fondo (suscripción Claude, API Anthropic, suscripciones externas, prepago, gratis) y avisos accionables. Lo que aprendimos midiendo 507 jobs reales:

  • Delegar en Claude Code con la misma cuenta no ahorra cupo; hacerlo en Opus lo gasta al precio más alto. Claude Code trae ahora modelos por tier (haiku / sonnet / sonnet / opus), editables en Agentes → Por tier, y su revisor usa sonnet.
  • Si un carril propio está solo ocupado, el job espera su turno en vez de saltar a uno medido (anthropic, deepseek o cualquiera con tope mensual). Los límites de concurrencia se aplican sin reiniciar.
  • Cada corrida (trabajo, revisiones y revisores) registra su uso con la caché incluida; OpenRouter registra costo 0; los jobs quedan en delegate_jobs y el log de cada job conserva los campos de cada evento.
  • El delegado de Claude Code puede correr exactamente los comandos de verify de su job (antes se le negaban y corregía a ciegas). Para leer usa sus herramientas Read/Grep/Glob, que quedan dentro del workspace: cat, grep, ls o Get-Content leerían fuera, rg --pre ejecuta comandos y cmake -E rm borra, así que no se permiten.
  • Entregar una tarea chica a otro agente cuesta casi lo mismo que hacerla: escribir el contrato y revisar el diff no son gratis. Conviene delegar tareas grandes, de mucha lectura o fáciles de verificar con verify.

Para delegar desde GitHub Copilot Chat (o Copilot CLI) igual que desde Claude Code: docs/delegar-desde-copilot.md.

Cuentas por CLI: claude, codex y deepseek admiten varias cuentas, una entrada más por cuenta con su propia carpeta de config bajo <config_dir>/accounts/. Agentes → Agregar cuenta crea la entrada (<base>-<n>, deshabilitada hasta que la habilites) y muestra los comandos de login; para Claude:

$env:CLAUDE_CONFIG_DIR='<carpeta-de-la-cuenta>'; claude

y dentro de Claude Code, /login con la cuenta que quieras asociar. Cuando una cuenta llega a su límite, el siguiente job usa la otra automáticamente; el reporter de statusline de cada cuenta informa a bipolar del uso real de 5 h y 7 días. Cursor no admite cuentas: su carpeta de config lleva la deny list del plugin y una cuenta la pisaría.

Varias suscripciones de Claude Code: bipolar-claude

Si tienes dos (o más) suscripciones de Claude Code, bipolar-claude (en scripts/) las usa por turno y cae al proxy cuando todas están agotadas. Agrega la carpeta scripts del repo a tu PATH, o invócalo directo: scripts\bipolar-claude.cmd en Windows, scripts/bipolar-claude.sh en Linux/macOS. Necesita Python 3 en el PATH.

  1. Configuración recomendada: deja tu ~/.claude apuntando a bipolar (ANTHROPIC_BASE_URL=http://localhost:8000, caso de uso 1) y pon cada suscripción en su propia cuenta (claude-2, claude-3…). Así, claude a secas es el modo proxy transparente, y bipolar-claude usa primero las suscripciones.
  2. Crear las cuentas: Agentes → Agregar cuenta (base claude), una por suscripción; luego haz login en cada una con $env:CLAUDE_CONFIG_DIR='<carpeta>'; claude y /login dentro. Habilítalas para que el broker también las use.
  3. Uso: bipolar-claude consulta a bipolar qué cuenta tiene cupo y abre claude con CLAUDE_CONFIG_DIR apuntando a ella, pasando todos tus argumentos. Si todas están agotadas (o no hay cuentas), abre en modo proxy con ANTHROPIC_BASE_URL y tu API key solo para ese proceso. Si bipolar no responde, abre claude normal.

Perfil espejo: una cuenta recién creada estaría vacía (sin tus plugins, skills ni servidores MCP). En cada lanzamiento, bipolar-claude sincroniza desde tu ~/.claude: junctions (mklink /J) para skills, agents, commands, rules, hooks y plugins, copia de CLAUDE.md, settings.json sin las variables del proxy (ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY) y con el statusline apuntando al reporter de uso, y fusión de tus mcpServers. Nunca copia credenciales, proyectos ni historial. --bc-no-mirror lo salta.

Flags propios (llevan el prefijo --bc-; el resto pasa intacto a claude):

  • --bc-dry-run: muestra qué haría (modo, variables y argumentos) sin lanzar nada. Para verificar: bipolar-claude --bc-dry-run.
  • --bc-continue (experimental): retoma en la cuenta actual la sesión más reciente de este directorio, copiando su transcript desde la cuenta usada la última vez (claude --resume <id>). Si no hay sesión previa, abre una nueva y avisa. Cambiar de cuenta dentro de una sesión no es posible: cada carpeta de config es una isla.

Por qué las suscripciones no van detrás del proxy: los términos de Anthropic prohíben usar las credenciales OAuth de la suscripción fuera de Claude Code, así que bipolar nunca las toca: solo comprueba que el login existe. Y técnicamente no encajaría: un claude -p ejecuta sus propias herramientas y responde texto, no puede devolverle bloques tool_use al cliente de afuera. Por eso las suscripciones solo se usan como CLIs (broker headless y lanzador).


Extras

  • Compresión semántica (Settings, opt-in): al acercarse al límite de contexto, resume el historial viejo con el provider activo en vez de truncarlo.
  • Uso y costos: pestaña Usage — tokens, costo estimado por provider/modelo.
  • Chat integrado con streaming y visión.
  • Token de Copilot se auto-refresca en background.

Deploy con Docker (servidor / headless)

docker compose up -d --build

Gateway + UI en :8000, config en el volumen bipolar-data. llama-server NO va dentro (necesita las GPUs del host): córrelo en el host y apunta el provider llamacpp a http://host.docker.internal:4002.

Arranque con Windows (sin iniciar sesión)

Se registran dos tareas. bipolar-code backend permite arrancar sin sesión iniciada; bipolar-code backend sesion mueve el backend a la sesión interactiva al iniciar sesión, porque el sandbox de Windows de Muse y Codex necesita una sesión interactiva. Mientras bipolar corre en la sesión 0, el broker descarta a Muse y Codex como trabajadores y revisores con sandbox_requires_interactive_session.

# PowerShell como administrador; pide la contraseña de Windows para la tarea de arranque
powershell -ExecutionPolicy Bypass -File scripts\install-autostart.ps1

La instalación principal registra bipolar-code backend solo al encender, con tu cuenta y contraseña, así funcionan las credenciales del llavero de Windows (gh, Copilot); la tarea se reinicia hasta 3 veces si falla. También registra la tarea de sesión y la inicia en ese momento.

El script:

  • Crea una regla de firewall que bloquea el puerto 8000 salvo desde loopback y la red de WSL (172.16.0.0/12).

  • Reinicia bipolar con la tarea de arranque nueva.

  • Registra bipolar-code backend sesion para ejecutarse al iniciar sesión, de forma interactiva y sin administrador. Para instalar o registrar esta tarea por separado:

    # PowerShell sin administrador
    powershell -ExecutionPolicy Bypass -File scripts\install-session-task.ps1
  • Al ejecutarse con -TomarSesion, si encuentra el puerto ocupado por la instancia de la sesión 0, start-bipolar.ps1 detiene la tarea con contraseña para liberarlo y arranca bipolar en la sesión interactiva. El lanzador escribe sus mensajes en bipolar-launcher.log, junto al log del backend.

  • Si el puerto está ocupado en otro caso, start-bipolar.ps1 sale con código 0 sin lanzar otra instancia.

El lanzador puede ser scripts\start-bipolar.ps1 del repo: arranca uvicorn con el Python del venv (%LOCALAPPDATA%\bipolar-code\venv, ver Dev Setup) y no arranca si el venv no existe. Pásalo con -Launcher <repo>\scripts\start-bipolar.ps1 a install-autostart.ps1; no lo copies a otra carpeta, porque resuelve la raíz del repo desde su propia ubicación.

start-bipolar.ps1 escucha por defecto en 0.0.0.0; la regla de firewall limita el acceso a loopback y WSL. Desde WSL, Windows es la puerta de enlace: curl http://$(ip route show default | awk '{print $3}'):8000/api/health.

Seguridad

  • Todo (/api/*, /v1/* y /mcp) exige tu API key — nada queda anónimo en la LAN.
  • Rate limiting por IP configurable (RATE_LIMIT_RPM). X-Forwarded-For se ignora salvo que la conexión venga de un proxy listado en TRUSTED_PROXIES.
  • El plano de control (/api/*) responde 403 a cualquier IP que no sea loopback, LAN privada (RFC1918/ULA), link-local o Tailscale (100.64.0.0/10), aunque traiga la key. Se mira solo la IP de la conexión, nunca X-Forwarded-For. /v1/* no se filtra. En Docker, si el reenvío de puertos no conserva la IP de origen (Docker Desktop, userland-proxy), las conexiones llegan con la IP privada del gateway y el filtro no distingue el tráfico público.
  • Fuera de la LAN: VPN. No abras el puerto al internet público.
  • /mcp es plano de control, igual que /api: exige la API key y respeta el mismo filtro de redes (CONTROL_PLANE_ALLOWED_CIDRS).
  • bipolar y LiteLLM se autentican entre sí con LITELLM_MASTER_KEY. Si falta, bipolar genera una clave aleatoria de 32 bytes y la guarda en el .env del directorio de configuración; no es la API key que usas para acceder al gateway.
  • Los comandos de verify corren en tu host sin shell y con entorno mínimo, pero fuera de cualquier sandbox y con tu usuario. Como mitigaciones, el workspace debe estar en la lista permitida y allow_request_verify viene apagado en instalaciones nuevas.
  • Ojo con lo que implica: verificar es ejecutar código que el agente delegado pudo modificar. pytest carga el conftest.py del repo, npm test corre los scripts de package.json, y un script del propio repo puede haber sido reescrito por el agente. Los agentes trabajan dentro de su sandbox, pero la verificación corre afuera. Delega con verify solo en repos y agentes en los que confíes, y revisa el diff antes de ejecutar cualquier cosa por tu cuenta.

Dev Setup (código fuente)

Requisitos: Python 3.11+, Node 20+.

bipolar corre en su propio venv para que el proxy de LiteLLM y las versiones de FastAPI/Starlette no toquen el Python global ni las herramientas que dependen de él. LiteLLM va fijado en backend/requirements-litellm.txt porque varias versiones tienen CVEs críticos y una publicación de PyPI fue comprometida; súbelo solo a una versión verificada.

En Windows el venv vive en %LOCALAPPDATA%\bipolar-code\venv, fuera del repo: los sandboxes de Muse y Codex marcan su workspace con integridad baja, y un python.exe dentro del repo no podría escribir en %TEMP% ni en C:\litellm. Va en una carpeta por usuario porque la tarea programada lo ejecuta con tu cuenta y otro usuario del equipo no debe poder reemplazarlo. Cambia la ruta con -VenvDir en ambos scripts.

# Windows: crea %LOCALAPPDATA%\bipolar-code\venv e instala todo
powershell -ExecutionPolicy Bypass -File scripts\setup-venv.ps1
# Linux/macOS
python -m venv backend/.venv && backend/.venv/bin/pip install -r backend/requirements.txt -r backend/requirements-litellm.txt

Activa el venv antes de arrancar el backend: $env:LOCALAPPDATA\bipolar-code\venv\Scripts\Activate.ps1 (Windows) o source backend/.venv/bin/activate (Linux/macOS).

# Backend (con el venv activado)
cd backend
uvicorn app.main:app --reload --port 8000

# Frontend (dev, proxy a :8000)
cd frontend
npm install
npm run dev        # http://localhost:5173

# Tests
cd backend && pytest
cd frontend && npm test

Configuración (.env)

El backend lee .env del directorio de configuración (C:\litellm\ / ~/.litellm/, override con LITELLM_CONFIG_DIR). Variables principales:

Variable Para qué
UI_API_KEY API key del gateway (se autogenera si falta)
LITELLM_MASTER_KEY Clave aleatoria para la autenticación interna entre bipolar y LiteLLM (se autogenera si falta)
ANTHROPIC_API_KEY Provider Anthropic real
GITHUB_OAUTH_TOKEN Auto-refresh del token de Copilot
NVIDIA_NIM_API_KEY, OPENROUTER_API_KEY, DEEPSEEK_API_KEY Providers cloud
HF_TOKEN Descargas de modelos gated en Hugging Face
SEMANTIC_COMPRESSION true activa la compresión de contexto
TELEGRAM_BOT_TOKEN, TELEGRAM_ALLOWED_CHAT_IDS Bot de Telegram
RATE_LIMIT_RPM, ALLOWED_ORIGINS Endurecimiento de red
TRUSTED_PROXIES Proxies inversos (IPs o CIDR, separados por coma) cuyo X-Forwarded-For se respeta en el rate limit; vacío = ninguno
CONTROL_PLANE_ALLOWED_CIDRS Redes CIDR (separadas por coma) que pueden usar /api/*; reemplaza al default (loopback, LAN privada, link-local y Tailscale)

Ver backend/.env.example para la lista completa.

Stack

  • Frontend: React 18 + Vite + TypeScript + Tailwind CSS + TanStack Query
  • Backend: Python FastAPI + structlog + httpx + pydantic-settings
  • Inferencia local: llama.cpp (llama-server, backend Vulkan) gestionado por la app
  • Providers cloud vía proxy: LiteLLM

License

MIT

About

Web UI for managing LiteLLM proxy backends, models and API usage

Resources

Stars

4 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages