ComandeskHelp Inicio

SaaS Multitenant Operating Contract

Estado: vigente desde 2026-05-06.

Este documento fija decisiones de arquitectura para que OPS pueda evolucionar como SaaS multitenant sin romper el modelo operativo de workspaces, agentes, modelos, credenciales y automatizaciones.

Principios

  1. La configuracion explicita gana a los defaults.
  2. Los defaults de producto deben ser seguros, baratos y reversibles.
  3. Los fallbacks deben ser visibles, auditables y documentados.
  4. Ningun runtime, proveedor o modelo debe quedar hardcodeado como unica opcion.
  5. El sistema debe bloquear con una razon clara antes que ejecutar con una capacidad incorrecta.
  6. Las decisiones operativas deben estar documentadas en el portal oficial de OPS.

Multitenancy

OPS es un SaaS multitenant. Toda entidad operativa nueva debe tener alcance de workspace cuando afecte a tareas, credenciales, targets, perfiles, agentes, plantillas, limites o ejecuciones.

Reglas:

  • Una tarea pertenece a un workspace_id.
  • Una plantilla recurrente pertenece a un workspace_id.
  • Un perfil de ejecucion pertenece a un workspace_id.
  • Una credencial pertenece a un workspace_id y puede ser personal o workspace.
  • Un deployment target pertenece a un workspace_id.
  • Los workers deben anunciar para que workspaces aceptan trabajo, aunque al inicio exista un unico workspace interno.

No se debe introducir estado global que cambie el comportamiento de todos los workspaces sin una politica explicita.

Agentes, Runtimes, Proveedores Y Modelos

Los conceptos se separan asi:

  • agente: unidad configurable de ejecucion dentro de OPS, por ejemplo opencode, codex, hermes, claudecode o un agente futuro.
  • runtime: binario, proceso o servicio que ejecuta realmente, por ejemplo opencode, codex, hermes, claude, un worker HTTP o un runner local.
  • proveedor: origen del modelo o credencial, por ejemplo openai, minimax, anthropic, google, ollama, lmstudio, openrouter o proveedor propio.
  • modelo: identificador que el runtime entiende, por ejemplo openai/gpt-5.4-mini, minimax/..., local/qwen....

OPS no debe asumir que solo existen unos pocos modelos. La UI puede sugerir modelos conocidos, pero debe permitir introducir modelos nuevos mientras el agente/proveedor los soporte.

Autenticacion Y Credenciales

La autenticacion debe ser configurable por workspace y por worker:

  • credencial de workspace: secreto cifrado en OPS, resuelto en runtime y filtrado por workspace_id;
  • credencial personal: solo para flujos autorizados donde el usuario propietario participa;
  • credencial global de worker: variable de entorno del servicio, valida para workers dedicados o entornos internos;
  • sesion local: login/OAuth guardado en el host, util para operacion simple pero menos portable.

El launcher debe resolver credenciales de la tarea antes de decidir si un runtime esta autenticado. Esto evita que un OAuth local caducado bloquee una tarea que trae OPENAI_API_KEY, MINIMAX_API_KEY u otra clave desde el vault del workspace.

Las tareas no deben heredar credenciales de otro workspace. Los workers multitenant deben evolucionar hacia pools aislados, cuotas y limites por workspace; los workers dedicados pueden usar variables globales cuando el aislamiento lo permita.

Politica De Preferencia

La preferencia actual de producto para OPS interno es:

  1. OpenCode como runtime general preferente cuando el proveedor/modelo esta configurado.
  2. Codex solo si esta autenticado y el worker lo anuncia como usable.
  3. ClaudeCode solo si esta autenticado o tiene API key valida.
  4. Modelos locales o proveedores contratados, como Minimax, cuando esten configurados como capacidades reales.
  5. Hermes como opcion valida si se selecciona o configura explicitamente, y como ultimo recurso si una politica de fallback lo permite.

Hermes no esta prohibido. Lo prohibido es caer en Hermes de forma silenciosa cuando la tarea, plantilla o workspace pedia otra cosa.

Fallbacks

Un fallback valido debe cumplir:

  • estar definido en configuracion o metadata, no escondido en codigo;
  • dejar rastro en contexto, comentario, output o auditoria;
  • respetar el workspace;
  • respetar credenciales y gates;
  • no traducir modelos de forma enganosa.

Ejemplo no aceptable:


minimax2.7 -> openai/gpt-5.4-mini

Si se usa OpenAI como sustituto temporal de Minimax, debe verse como override operativo, no como alias silencioso.

Workers

El API/UI no debe asumir que los agentes corren en el mismo VPS que OPS.

Un worker debe anunciar capacidades reales:


{

  "worker_id": "worker-eu-01",

  "workspaces": ["ops-internal"],

  "agents": ["opencode"],

  "models": ["openai/gpt-5.4-mini"],

  "providers": ["openai"],

  "max_concurrency": 2,

  "current_load": 0,

  "region": "eu"

}

Modos futuros admitidos:

  • workers gestionados por OPS;
  • workers dedicados por workspace;
  • workers especializados en proveedores o modelos locales;
  • bring-your-own-worker para clientes que quieran ejecutar agentes en su propia infraestructura.

Para 1000 usuarios concurrentes no es valido un unico VPS ejecutando todos los agentes. El modelo debe permitir pool de workers, limites por workspace y asignacion por capacidad.

Estados

Estados visibles:

  • inbox: entrada sin decidir.
  • next: lista, planificada o pendiente de lanzamiento manual.
  • doing: trabajo activo o seguimiento.
  • waiting: esperando input externo.
  • review: resultado listo para validar.
  • done: completada.
  • archived: fuera del flujo activo, conservada por historico.

Estados tecnicos:

  • queued: esperando worker.
  • dispatching: worker ejecutando.

queued y dispatching pueden verse en diagnostico, pero no deben convertirse en columnas mentales principales para usuarios finales.

Archived

archived significa que la tarea ya no participa en la operacion normal.

Usos correctos:

  • duplicados;
  • tareas obsoletas;
  • ideas descartadas;
  • instancias recurrentes descartadas;
  • tareas migradas a otra tarea;
  • historico que no debe contar como completado.

done significa trabajo completado. archived significa fuera de flujo.

Dispatch Triggers

Las tareas automatizables pueden entrar a cola de tres formas:

  • inmediata: se crea y pasa a queued;
  • planificada: se crea o permanece en next hasta fecha/regla;
  • manual: se lanza con Dispatch now.

El boton Dispatch now debe seguir existiendo para lanzar manualmente tareas automatizables que deliberadamente no entran a cola al crearse.

Bloqueos E Interrupciones

Una tarea automatizable bloqueada debe poder resolverse en una sola accion:

  1. el usuario escribe el comentario/respuesta;
  2. OPS guarda el comentario;
  3. OPS quita blocked;
  4. si se elige reencolar, OPS llama a dispatch y pasa a queued;
  5. si falta Human Gate, OPS deja la tarea desbloqueada pero no ejecuta.

Debe existir tambien la opcion de guardar sin ejecutar.

Mover una tarea a doing no debe relanzar automatizacion. Solo dispatch encola.

Health Y Diagnostico

El health debe detectar desalineaciones:

  • plantilla pide agente/modelo sin worker compatible;
  • worker anuncia agente pero el runtime no esta autenticado;
  • proveedor esperado no tiene credencial;
  • tarea recurrente bloquea la siguiente instancia;
  • dispatch esta activo pero solo hay capacidades no deseadas;
  • produccion no esta ejecutando la misma version que el repo.

Un health que dice ok solo porque hay heartbeat fresco no es suficiente.

Deploy Y Documentacion

El portal oficial de documentacion OPS es la fuente operativa. Los cambios de comportamiento deben actualizar:

  • documentacion fuente en docs/;
  • build estatico en public/help;
  • portal Syntax si aplica.

Commit y push no equivalen a deploy cuando produccion es una copia en /var/www/ops y no un checkout Git.

Criterio Anti-Regresion

Antes de cambiar dispatch, agentes, modelos, credenciales o plantillas, comprobar:

  1. no se rompe workspace_id;
  2. no se introduce fallback silencioso;
  3. no se reduce la configurabilidad de agentes/modelos;
  4. no se asume un unico VPS como executor permanente;
  5. no se ocultan fallos de auth;
  6. no se mezclan estados visibles con estados tecnicos;
  7. se actualiza el portal oficial;
  8. hay prueba end-to-end o smoke documentado.