WorkspaceGuard

WorkspaceGuard

Instalación • Inicio rápido • Referencia CLI • Comparación • Preguntas frecuentes

Medición de uso por espacio de trabajo y límites de cuota con cierre forzado para una única implementación compartida de asistente de IA autoalojado (Odysseus o un backend compatible).

Ejecuta Odysseus (o un asistente autoalojado compatible) para tu hogar o equipo pequeño y no hay forma de ver quién envió cuántos mensajes este mes, ni de impedir que el uso de una persona agote el presupuesto de API de todos los demás. WorkspaceGuard es un sidecar que añade esa capa: recuentos de mensajes por espacio de trabajo, un límite mensual opcional que cierra el acceso al alcanzarse, y un informe CLI (o JSON) que un administrador u otro agente puede leer.

npx workspaceguard-cli usage
-> alex   [alex@example.com]: 812 messages this period, cap 1000 (81%)
-> jordan [jordan@example.com]: 203 messages this period, cap unlimited

Instalación

npm install -g workspaceguard-cli

O ejecútalo sin instalarlo:

npx workspaceguard-cli usage

El paquete es workspaceguard-cli; el comando que instala es workspaceguard. Un port genuino e independiente a Python con la misma superficie CLI y las mismas formas de --json se publica por separado como workspaceguard-cli en PyPI (pip install workspaceguard-cli, ver python/).

Inicio rápido

# Register the workspaces sharing one deployment (identity = the header value
# your reverse proxy sets after authenticating, e.g. Cloudflare Access).
workspaceguard add-workspace alex --identity alex@example.com
workspaceguard add-workspace jordan --identity jordan@example.com

# Optional: cap alex at 1000 messages/month. Omit for unlimited (the default).
workspaceguard set-cap alex 1000

# See usage for every workspace.
workspaceguard usage

Salida real de una instalación nueva:

-> alex [alex@example.com]: 0 messages this period, cap 1000 (0%)
-> jordan [jordan@example.com]: 0 messages this period, cap unlimited

Características

• Recuento de mensajes por espacio de trabajo. Cada solicitud a través del punto de entrada chat() del sidecar incrementa un contador por espacio de trabajo y por mes (src/core/usage.ts), aislado para que el uso de un espacio de trabajo nunca se filtre al de otro.
• Aplicación de cuota con cierre forzado. Un espacio de trabajo que alcanza su límite recibe un QuotaExceededError antes de que se llame al backend. Si el almacén de uso está corrupto o es ilegible, WorkspaceGuard bloquea las solicitudes en lugar de restablecer silenciosamente el recuento de todos a cero (ver CHANGELOG.md).
• --json nativo para agentes en cada comando. workspaceguard usage --json devuelve una salida estructurada que un orquestador puede analizar directamente, sin extracción de pantalla.
• Bóveda AES-256-GCM con rotación real de claves. workspaceguard rotate-key <id> vuelve a cifrar los secretos de un espacio de trabajo con una clave nueva e invalida el texto cifrado anterior.
• Un interruptor de circuito auto-reparable. Las llamadas al backend abren el circuito tras 3 fallos consecutivos, luego reintentan mediante una sonda semiabierta y vuelven a cerrarlo al tener éxito, en lugar de quedarse disparado para siempre.
• Un único punto de control, no comprobaciones dispersas. chat() en src/core/isolation-guard.ts es el único lugar por el que fluye cada solicitud: resolver el espacio de trabajo, comprobar la cuota, llamar al backend, registrar el uso.
• Dos distribuciones independientes y probadas. El paquete TypeScript (npm) y el port de Python (PyPI) implementan el mismo diseño con suites de pruebas separadas: 41/41 pruebas de TypeScript superadas y 50/50 pruebas de Python superadas al momento de escribir esto.

Referencia CLI

Cada comando acepta --json para una salida estructurada y nativa para agentes en lugar del texto legible por humanos que se muestra a continuación.

Comando	Qué hace
workspaceguard init	Inicializa el directorio de datos y la bóveda para esta implementación.
workspaceguard add-workspace <id> --identity <value>	Registra un espacio de trabajo, idempotente en llamadas repetidas para el mismo id. --identity se analiza posicionalmente y debe seguir inmediatamente a <id>; no es una bandera independiente.
workspaceguard status [--json]	Lista los espacios de trabajo configurados.
workspaceguard usage [--json]	Recuento de mensajes por espacio de trabajo, límite y porcentaje usado del mes actual.
workspaceguard set-cap <id> <count|none>	Establece o elimina el límite mensual de mensajes de un espacio de trabajo.
workspaceguard rotate-key <id>	Rota la clave de cifrado de la bóveda de un espacio de trabajo (invalida el texto cifrado anterior).
workspaceguard scan [--json]	Escaneo de configuración de aislamiento (stub de andamiaje, heredado de la compilación original; hoy siempre devuelve una lista de hallazgos vacía).
workspaceguard -h, --help	Imprime la lista de comandos anterior y sale con 0.
workspaceguard -V, --version	Imprime la versión del paquete instalado y sale con 0.

Opciones globales

Opción	Qué hace
--data-dir <path>	Directorio de datos para configuración, bóveda y datos de uso. Tiene prioridad sobre WORKSPACEGUARD_DATA_DIR.
--force	Solo init: regenera la clave maestra incluso si un archivo de clave existente en el directorio de datos resuelto parece corrupto o truncado.
--json	Salida estructurada y nativa para agentes en lugar de texto legible por humanos.

[!WARNING] --force invalida permanentemente todo lo que ya esté cifrado con la clave maestra anterior. Úsalo solo cuando se confirme que el archivo de clave existente es irrecuperable.

Resolución del directorio de datos, en orden: bandera --data-dir, luego variable de entorno WORKSPACEGUARD_DATA_DIR, luego ~/.workspaceguard. Antes se usaba por defecto el directorio de trabajo actual sin anulación posible: ejecutar init desde el shell equivocado podía escribir silenciosamente una clave de cifrado activa en un directorio no relacionado. init sobre una clave existente y válida es idempotente (carga y reutiliza esa clave); init sobre un archivo de clave que existe pero no se decodifica como clave válida se niega a sobrescribirlo sin --force.

$ workspaceguard usage --json
{"ok":true,"usage":[{"workspaceId":"alex","identity":"alex@example.com","monthlyMessageCap":1000,"percentUsed":81,"period":"2026-07","messageCount":812,"estimatedBytes":48213}]}

El modo --json es lo que hace que esto sea nativo para agentes y no solo cómodo para humanos: un orquestador o agente de monitoreo puede llamar a workspaceguard usage --json y analizar el resultado directamente en lugar de extraer la salida del terminal.

API de biblioteca

import { createWorkspaceGuard, MockAdapter, QuotaExceededError } from "workspaceguard-cli";

const guard = await createWorkspaceGuard({ dataDir: "./data", backend: new MockAdapter() });
await guard.addWorkspace("alex", "alex@example.com");
await guard.setCap("alex", 1000);

try {
  await guard.chat("alex@example.com", "hello");
} catch (err) {
  if (err instanceof QuotaExceededError) {
    // alex is over their monthly cap
  }
}

const report = await guard.usageReport();

El port de Python expone la misma forma: from workspaceguard import create_workspace_guard, MockAdapter, QuotaExceededError.

Servidor MCP

La distribución Python de WorkspaceGuard incluye un servidor Model Context Protocol, de modo que un agente compatible con MCP (Claude Desktop, Claude Code, un orquestador) puede llamar a WorkspaceGuard directamente como herramienta en lugar de invocar la CLI y analizar texto.

pip install "workspaceguard-cli[mcp]"

Expone una herramienta, run, un envoltorio genérico de subprocesos: pásale la misma lista de argumentos que pasarías en la línea de comandos, y ejecuta el binario workspaceguard instalado, analiza el JSON resultante y lo devuelve. Cada modo de fallo (binario ausente, error de lanzamiento, tiempo de espera agotado, salida distinta de cero, salida no analizable) regresa como un dict {"error": ...} simple en lugar de lanzar una excepción, de modo que una llamada incorrecta no puede tumbar el servidor.

run(args=["usage", "--json"])
# -> {"ok": true, "usage": [{"workspaceId": "alex", "identity": "alex@example.com", "monthlyMessageCap": 1000, "percentUsed": 0, "period": "2026-08", "messageCount": 0, "estimatedBytes": 0}]}

Para registrarlo con un cliente compatible con MCP como Claude Desktop, añádelo a la configuración de servidores del cliente:

{
  "mcpServers": {
    "workspaceguard": {
      "command": "workspaceguard-mcp"
    }
  }
}

Esto asume que workspaceguard-mcp ya está en PATH (instalado mediante el extra mcp anterior). Si lo instalaste en otro lugar, reemplaza "command" con la ruta completa al script de consola.

Comparación

WorkspaceGuard es un sidecar, no un producto competidor. Se sitúa delante de una implementación de Odysseus (o un backend compatible) y añade la única capa que ese backend no proporciona.

Capacidad	WorkspaceGuard	Odysseus (nativo)
Aislamiento por usuario (historial de chat, memoria, claves API)	No se reimplementa; se considera ya resuelto	Sí, integrado por defecto
Recuento de mensajes por espacio de trabajo	Sí	No
Límites de cuota mensuales, con cierre forzado	Sí	No
Informe de uso CLI / --json	Sí	No
Licencia	MIT	AGPL-3.0

Qué es WorkspaceGuard y por qué existe

Este proyecto se propuso originalmente añadir aislamiento de espacios de trabajo por usuario (historial de chat, memoria y claves API separados) a una plataforma de chat de IA autoalojada. Un estudio de viabilidad descubrió que Odysseus ya aplica la propiedad por usuario en el historial de chat, la memoria y los tokens de API por defecto, por lo que construir una capa de aislamiento competidora habría duplicado un trabajo que Odysseus ya hace correctamente.

WorkspaceGuard conserva en cambio su motor de aislamiento probado (separación de espacios de nombres, una bóveda AES-256-GCM con rotación real de claves, resolución de identidad con cierre forzado, un interruptor de circuito auto-reparable) como sustrato de resolución de identidad, y construye la capa que Odysseus no proporciona: medición de uso y aplicación de cuotas por espacio de trabajo.

Nivel gratuito (este repositorio, MIT): recuento de mensajes por espacio de trabajo, aplicación de límites mensuales, informe de uso CLI/JSON. No está en este repositorio: un panel de facturación alojado multitenant es un producto separado de código cerrado, mencionado aquí solo como elemento de hoja de ruta y nunca fusionado en este código base MIT.

Arquitectura

• src/core/isolation-guard.ts -- el único punto de control (chat()) por el que fluye cada solicitud: resolver el espacio de trabajo, comprobar la cuota, llamar al backend, registrar el uso.
• src/core/usage.ts -- el motor de medición de uso que añade este proyecto: contadores por espacio de trabajo y por mes con reinicio automático de período, y aplicación de QuotaExceededError.
• src/core/vault.ts, src/core/namespace.ts, src/core/circuit-breaker.ts -- el código original del motor de aislamiento, conservado como sustrato de identidad y límite de espacio de trabajo del que lee la capa de medición.
• src/adapters/ -- la interfaz BackendAdapter. MockAdapter es la única implementación hoy; aún no se ha construido un adaptador HTTP real de Odysseus.

El comportamiento específico del backend nunca entra directamente en src/core/. Todo pasa por BackendAdapter.

Límite de confianza

WorkspaceGuard confía en una cabecera de identidad ascendente (por defecto: Cf-Access-Authenticated-User-Email) para resolver el espacio de trabajo.

[!WARNING] Este servicio nunca debe ser accesible directamente desde la red. Ejecútalo solo detrás de un proxy de confianza que establezca esa cabecera (Cloudflare Access, Tailscale, etc.). Este límite está documentado, no aplicado por código.

Qué es real y qué aún no está construido

• Real y probado: medición de uso, aplicación de cuotas, el motor de aislamiento original (bóveda, separación de espacios de nombres, interruptor de circuito) y la CLI con modo --json, verificado por 41/41 pruebas de TypeScript superadas y 50/50 pruebas de Python superadas.
• Aún no construido: un adaptador HTTP real de Odysseus (solo existe MockAdapter hoy) y un panel de facturación alojado multitenant (deliberadamente fuera del alcance de este repositorio MIT).

Documentación

• docs/getting-started.md
• docs/concepts.md
• docs/integrations/ci.md
• docs/integrations/backends.md

Preguntas frecuentes

P: ¿Qué hace realmente WorkspaceGuard? R: Añade medición de uso y aplicación de cuotas por espacio de trabajo delante de una única implementación compartida de asistente de IA autoalojado. Cuenta los mensajes por espacio de trabajo y por mes, te permite establecer un límite opcional que cierra el acceso al alcanzarse, y te da a ti (o a un agente) un informe workspaceguard usage. No añade aislamiento de historial de chat, memoria ni claves API por sí mismo; eso ya existe por defecto en la plataforma objetivo (ver "Qué es WorkspaceGuard" arriba), y el propio código de aislamiento de WorkspaceGuard (src/core/vault.ts, src/core/namespace.ts) se conserva solo como sustrato de resolución de identidad del que lee la capa de medición.

P: ¿Cuál es el diferenciador real de WorkspaceGuard? R: Alcance reducido bien ejecutado: no es una plataforma de facturación completa, ni una reimplementación del aislamiento que el backend ya tiene. Cada solicitud fluye por un único punto de control (chat() en src/core/isolation-guard.ts), la aplicación de cuotas cierra el acceso ante un almacén de uso corrupto en lugar de restablecer silenciosamente el uso de todos a cero (ver CHANGELOG.md), y cada comando admite --json para salida nativa para agentes.

P: ¿Cómo se compara WorkspaceGuard con Odysseus? R: No es un producto competidor. WorkspaceGuard es un sidecar que se sitúa delante de una implementación de Odysseus (o un backend compatible); no reemplaza nada de lo que Odysseus ya hace. Consulta la tabla de comparación anterior para ver el reparto específico de capacidades.

P: ¿En qué plataformas se ejecuta WorkspaceGuard? R: El paquete npm (workspaceguard-cli) requiere Node.js 20 o superior (engines.node en package.json). El port de Python en python/ requiere Python 3.9 a 3.13 (ver los clasificadores en python/pyproject.toml). Ninguna distribución incluye un binario específico de plataforma, por lo que ambos se ejecutan dondequiera que lo haga su runtime respectivo (Linux, macOS, Windows). P: ¿Es WorkspaceGuard una CLI, una biblioteca o ambas? R: Ambas, en ambas distribuciones. La CLI (workspaceguard <command>) cubre init, add-workspace, status, usage, set-cap, rotate-key, y scan. La misma funcionalidad es importable directamente (createWorkspaceGuard desde el paquete de TypeScript, create_workspace_guard desde el paquete de Python) para cualquier cosa que quiera llamarla desde código en lugar de ejecutarla por línea de comandos.

P: ¿Cuál es una limitación real actual que debería saber antes de confiar en esto? R: El único adaptador de backend implementado hoy es MockAdapter, un adaptador en memoria usado para pruebas y experimentación local. Aún no se ha construido un adaptador HTTP real de Odysseus (ver docs/integrations/backends.md), por lo que WorkspaceGuard aún no reenvía tráfico de chat en vivo a un despliegue real de Odysseus. La lógica de medición y cuotas es real y está probada; el puente de red hacia un backend en vivo es la pieza que sigue pendiente.

P: ¿Necesita WorkspaceGuard sus propias claves de API o guarda alguna de mis credenciales de proveedor de IA? R: No. El único adaptador de backend que existe actualmente (MockAdapter) está en memoria y no llama a ninguna API externa. Todo el comportamiento específico del backend está aislado detrás de la interfaz BackendAdapter (src/adapters/), por lo que el código propio de WorkspaceGuard nunca necesita ver las credenciales del proveedor directamente.

P: ¿WorkspaceGuard es gratuito para uso comercial? R: Sí. Este repositorio tiene licencia MIT completa, sin doble licencia ni bloqueo de características. El panel de control de facturación alojado y multi-tenant mencionado anteriormente es un producto separado, de código cerrado, descrito solo como un elemento de la hoja de ruta; ningún código del panel de control de facturación vive en, o se retiene de, este código base MIT.

Contribución y seguridad

Consulte CONTRIBUTING.md y SECURITY.md. Los cambios notables se registran en CHANGELOG.md.

Licencia

MIT.