Plan hibrido SaaS + runner local: Komandesk vendible

Fecha: 2026-05-28

Estado: plan operativo para Komandesk

Proyecto: Komandesk

Tesis

Komandesk debe venderse como plano de control para proyectos ejecutables, no como un agente magico.

La arquitectura correcta es hibrida:

• SaaS como plano de control: workspaces, proyectos, scope, planes, tareas, specs, permisos, auditoria, cola, dispatch, memoria y metricas.
• Runner local como plano de ejecucion: acceso a disco autorizado, repos locales, CLIs instalados, sesiones del usuario, herramientas privadas y modelos locales.
• Workers remotos o repo/remoto como alternativa cuando el trabajo no necesita disco local.

Esta separacion resuelve la friccion central: un SaaS puro no puede prometer acceso al disco del usuario. Un runner local autorizado si puede trabajar en el entorno del usuario, siempre que declare capacidades, rutas permitidas y deje trazabilidad.

Viabilidad de usar agentes locales con suscripciones del usuario

No es fantasia. Es viable con condiciones.

Hecho comprobado en esta maquina:

• codex existe localmente y responde como codex-cli 0.133.0.
• opencode existe localmente y responde como 1.2.25.

Fuentes consultadas el 2026-05-28:

• OpenAI Codex CLI: https://developers.openai.com/codex/cli
• OpenCode Providers: https://opencode.ai/docs/providers/

Lectura practica:

• Codex CLI corre localmente, puede leer, cambiar y ejecutar codigo en el directorio seleccionado, y puede autenticarse con cuenta ChatGPT o API key. OpenAI indica que planes ChatGPT Plus, Pro, Business, Edu y Enterprise incluyen Codex.
• OpenCode soporta multiples proveedores, modelos locales, credenciales con /connect, OpenCode Go/Zen, API keys y autenticacion ChatGPT Plus/Pro para OpenAI.

Por tanto, un runner local puede lanzar runtimes instalados como codex, opencode, claude, hermes, ollama o similares si:

• el usuario los instalo en su maquina;
• el usuario los autentico bajo su propia cuenta o API key;
• el runtime permite uso no interactivo o suficientemente automatizable;
• la tarea corre dentro de rutas autorizadas;
• Komandesk no captura ni revende credenciales personales;
• el resultado vuelve con evidencia, logs filtrados, tiempo y estado.

Lo que no debe prometerse:

• usar la suscripcion personal del usuario desde el servidor SaaS;
• guardar usuario/password de ChatGPT u otros proveedores en Komandesk;
• saltarse limites, terminos o rate limits del proveedor;
• ejecutar cambios locales sin consentimiento, sandbox o scope de ruta.

La promesa vendible seria:

> Conecta tu maquina como runner local y Komandesk coordinara tareas que se ejecutan con tus herramientas, tus sesiones y tus modelos autorizados.

Dos escenarios de producto

Escenario A: uso personal/local-first

Objetivo: potencia maxima para usuario tecnico.

• Komandesk puede estar en SaaS o local.
• El runner local es protagonista.
• El usuario aprovecha Codex, OpenCode, modelos locales, repos y CLIs propios.
• Las credenciales pueden vivir en la maquina o en vault del workspace.
• El producto debe priorizar velocidad, control y trazabilidad.

Riesgo:

• demasiado poder sin guardrails puede crear errores caros.

Respuesta:

• gates humanos en acciones sensibles;
• ruta permitida por proyecto;
• preflight antes de primera ejecucion;
• evidencia obligatoria antes de cerrar.

Escenario B: SaaS vendible/equipo

Objetivo: producto entendible, soportable y cobrable.

• SaaS gestiona usuarios, workspaces, proyectos, permisos y auditoria.
• Workers remotos ejecutan tareas sin datos locales.
• Runner local se ofrece como conector instalado por cliente cuando hace falta acceso a disco/modelos locales.
• Repositorios por proyecto permiten un tercer camino reproducible.

Riesgo:

• vender autonomia antes de que haya readiness real.

Respuesta:

• onboarding guiado por modo de ejecucion;
• readiness por proyecto;
• limites claros de lo que hace SaaS, runner local y repo/remoto;
• primera ejecucion siempre supervisada.

Cuellos de botella actuales

1. Demasiados controles visibles en vistas principales.

Solucion: dejar busqueda, orden inteligente y accesos rapidos; mover filtros secundarios a "mas filtros" o preferencias.

1. Contexto de proyecto todavia disperso.

Solucion: crear memoria de proyecto con scope, plan activo, specs, decisiones, conversaciones resumidas, repos, targets y runners.

1. Asistente IA demasiado generico.

Solucion: convertirlo en asistente contextual por proyecto/tarea, con historial recuperable, modelo visible y memoria resumida.

1. Ejecucion local no empaquetada.

Solucion: MVP de runner local instalable con token de vinculacion, heartbeat, rutas permitidas y adapters para runtimes.

1. Modelos y runtimes mezclados conceptualmente.

Solucion: separar profile, agente, runtime, proveedor, modelo y credencial. El usuario elige "tipo de trabajo"; infra resuelve runtime/modelo.

1. Automatizaciones recurrentes fragiles.

Solucion: cada recurrente debe tener proyecto, owner, output esperado, fallback, evidencia, watchdog y alerta de sistema si falla.

1. QA y cierre no uniformes.

Solucion: todo cierre de IA requiere evidencia minima, tiempo registrado y criterio de verificacion segun tipo de tarea.

1. SaaS puro tiene promesas imposibles.

Solucion: posicionamiento honesto: SaaS coordina; runner local ejecuta local; repo/remoto ejecuta reproducible.

Arquitectura objetivo

Plano de control SaaS

Responsabilidades:

• autenticar usuarios y workspaces;
• mantener proyectos, planes, specs y tareas;
• conservar memoria y conversaciones por proyecto;
• decidir readiness;
• encolar tareas;
• auditar cambios;
• almacenar evidencias no sensibles;
• mostrar salud de runners/workers;
• gestionar vault de credenciales cuando aplique.

No debe:

• leer disco local directamente;
• ejecutar comandos locales sin runner;
• guardar credenciales personales de CLIs interactivos;
• ocultar que runtime/modelo ejecuto cada tarea.

Plano de ejecucion local

Responsabilidades:

• correr en maquina autorizada;
• anunciar heartbeat y capacidades;
• limitar rutas de trabajo;
• lanzar runtimes instalados;
• usar sesiones/API keys que el usuario ya configuro;
• devolver resultado, diff, logs filtrados, artefactos y tiempo;
• bloquear si falta permiso, ruta, runtime o modelo.

Adapters iniciales:

• codex: CLI local de OpenAI Codex.
• opencode: CLI local multiproveedor.
• ollama/local model: modelos locales cuando existan.
• shell controlado: comandos permitidos para preflight y checks.

Repo/remoto

Responsabilidades:

• crear/enlazar repo por proyecto;
• branch/worktree por ejecucion;
• commit/PR como evidencia;
• soportar GitHub primero, sin cerrar puerta a GitLab, Forgejo/Gitea y Git generico.

Modelo de asistente IA

El asistente debe dejar de ser solo chat general. Debe tener memoria por proyecto.

Entidades recomendadas:

• project_conversations: hilos por proyecto, tarea o decision.
• project_memory: resumen vivo con decisiones, limites, links, repos y riesgos.
• assistant_runs: cada respuesta con modelo, runtime, fuentes usadas y coste/tiempo estimado.
• model_profiles: perfiles visibles como "rapido", "razonamiento", "codigo", "revision", "local".

Reglas:

• el asistente siempre debe saber workspace/proyecto/tarea activa;
• si no hay proyecto, debe pedir o proponer clasificacion;
• las conversaciones importantes se resumen al cerrar;
• no debe mezclar decisiones de un proyecto con otro;
• el modelo usado debe ser visible y configurable por perfil.

Fases

Fase 1: Simplificar cartera de proyectos

Objetivo: encontrar y decidir rapido sin llenar la UI de filtros.

Entregables:

• busqueda como accion principal;
• chips rapidos: prioridad, recientes, bloqueados, archivados;
• filtros avanzados plegados;
• departamento/workspace visible solo cuando aporta decision;
• nombres cortos y descripcion breve poblados en proyectos clave.

Estimacion: 8-14 h.

Criterio de cierre:

• un usuario con 25-30 proyectos puede encontrar Flowtitude, Expofrutas o Komandesk en menos de 10 segundos.

Fase 2: Memoria y asistente por proyecto

Objetivo: que la IA recuerde contexto sin depender de chat infinito.

Entregables:

• modelo de conversaciones por proyecto/tarea;
• resumen de memoria por proyecto;
• selector visible de modelo/perfil;
• asistente abre con contexto del proyecto activo;
• historial recuperable desde cockpit.

Estado 2026-05-28:

• DB/API preparada para memoria, conversaciones y assistant_runs.
• Asistente con contexto del proyecto activo e historial guardable.
• Selector de intencion IA (rapido, razonamiento, codigo, revision, local) conectado a defaults de tarea y execution_contract.

Estimacion: 16-28 h.

Criterio de cierre:

• al abrir un proyecto se puede ver que se decidio, por que, que esta bloqueado y que modelo/runner intervino.

Fase 3: Runner local MVP

Objetivo: ejecutar tareas en maquina del usuario con permisos claros.

Entregables:

• token de vinculacion por workspace/proyecto;
• worker local con heartbeat;
• declaracion de runtimes disponibles;
• allowlist de rutas;
• preflight de ruta/runtime/modelo;
• adapter inicial opencode;
• adapter inicial codex si soporta modo no interactivo estable en el entorno;
• logs filtrados y evidencia sincronizada.

Estado 2026-05-29:

• Contrato base local_runner_bindings definido.
• Endpoints base GET/POST/PATCH/DELETE /api/local-runners.
• Heartbeat POST /api/local-runners/heartbeat conectado a worker_heartbeats.
• Token de runner creado como API token revocable con scopes minimos.
• Launcher local conectado a OPS_RUNNER_TOKEN, allowlist de rutas y adapters iniciales opencode/codex.
• Doctor/preflight npm run runner:local:doctor creado para validar API, token, rutas, runtimes, herramientas auxiliares y heartbeat.
• Modo offline npm run runner:local:doctor -- --offline disponible para preparar la maquina antes de crear el token.

Estimacion: 24-48 h.

Criterio de cierre:

• una tarea pequena puede ejecutarse localmente, tocar un repo autorizado y volver con evidencia, tiempo y estado.

Trabajo pendiente inmediato:

• pairing guiado desde UI con comando copiable;
• piloto end-to-end sobre repo autorizado;
• instalador o script bootstrap por sistema operativo;
• daemon/servicio persistente;
• rotacion de token y revocacion mas visibles.

Fase 4: Catalogo de modelos, perfiles y credenciales

Objetivo: que el usuario elija capacidad, no combinaciones tecnicas confusas.

Entregables:

• catalogo: profile -> agente -> runtime -> proveedor -> modelo;
• soporte BYOK y BYOS, bring your own key/subscription;
• validacion de credenciales por runtime;
• modelos locales declarados por runner;
• coste/tiempo estimado por perfil;
• fallback explicito, nunca silencioso.

Estado 2026-05-28:

• API GET /api/security/runtime-catalog creada para explicar profile -> agente -> runtime -> proveedor -> modelo -> credencial/runner.
• Vista tecnica en Gestion -> Credenciales muestra estado por agente, credenciales usables, runners frescos, modelos, proveedores y perfiles enlazados.
• Politica BYOK/BYOS visible: workspace/account como automatizable, personal-only no automatizable, BYOS sujeto a runner local y preflight.
• Documento tecnico: docs/architecture/runtime-model-credential-catalog.md.

Estimacion: 16-32 h.

Criterio de cierre:

• se puede explicar por que una tarea usa opencode + OpenAI, codex + ChatGPT, ollama local o worker remoto.

Fase 5: Fiabilidad, QA y automatizaciones encadenadas

Objetivo: que las automatizaciones dejen de parecer magia fragil.

Entregables:

• recurrentes con proyecto obligatorio o excepcion explicita;
• watchdog de recurrentes y dispatch;
• alertas de sistema solo para fallos reales;
• reintentos con limite;
• evidencia obligatoria;
• QA por tipo de tarea;
• dashboard de salud por proyecto.

Estado 2026-05-28:

• Dispatch stale abre/reabre alerta de sistema al mover una tarea atascada a waiting.
• Scheduler de recurrentes abre alertas para RRULE invalida, error de scheduler o instancia activa bloqueante.
• Si una recurrente requiere correccion, el scheduler crea o reutiliza una tarea scheduler-watchdog con tag recurring-watchdog.
• Cierre IA valida QA por tipo de tarea y exige tiempo registrado antes de done.

Estimacion: 24-40 h.

Criterio de cierre:

• si una recurrente falla, el usuario ve que fallo, por que, donde y que tarea se creo o bloqueo.

Fase 6: Empaquetado SaaS vendible

Objetivo: convertir la arquitectura en producto explicable.

Entregables:

• onboarding por modo: SaaS worker, runner local o repo/remoto;
• instalador o script de runner;
• permisos y revocacion de dispositivo;
• recetas de casos de uso;
• planes de pricing orientativos;
• beta checklist;
• soporte de logs sin secretos.

Estado 2026-05-28:

• Readiness de proyecto crea tareas Onboarding piloto por modo: SaaS worker, runner local o repo/remoto.
• Cada modo declara limite de promesa, checklist y primera ejecucion pequena.
• Documento publico: docs/product/onboarding-execution-modes.md.
• Documento comercial: docs/product/beta-pricing-2026-05-28.md.

Estimacion: 32-64 h.

Criterio de cierre:

• se puede incorporar un cliente piloto sin explicaciones improvisadas ni promesas falsas.

Tareas iniciales propuestas

1. HYB F1 UI portfolio: simplificar filtros visibles y agrupar avanzados. Estimacion: 6 h.
2. HYB F1 Datos portfolio: poblar nombres cortos y descripciones. Estimacion: 4 h.
3. HYB F2 Modelo memoria proyecto: diseno DB/API. Estimacion: 6 h.
4. HYB F2 UI asistente por proyecto: historial y contexto activo. Estimacion: 8 h.
5. HYB F2 Perfiles de modelo: selector y defaults por tarea. Estimacion: 6 h.
6. HYB F3 Runner local contract: token, heartbeat y capacidades. Estimacion: 8 h.
7. HYB F3 Runner local MVP: proceso worker y ruta autorizada. Estimacion: 12 h.
8. HYB F3 Adapter opencode: ejecucion, logs y evidencia. Estimacion: 8 h.
9. HYB F3 Adapter codex: prueba no interactiva y limites. Estimacion: 8 h.
10. HYB F4 Catalogo runtime/modelo/credencial. Estimacion: 10 h.
11. HYB F4 BYOK/BYOS policy y UI. Estimacion: 8 h.
12. HYB F5 Watchdog recurrentes/dispatch con alertas sistema. Estimacion: 10 h.
13. HYB F5 QA y evidencia por tipo de tarea. Estimacion: 12 h.
14. HYB F6 Onboarding SaaS/runner/repo. Estimacion: 12 h.
15. HYB F6 Beta vendible y pricing inicial. Estimacion: 8 h.

Prioridad recomendada

Orden recomendado:

1. Fase 1, porque reduce ruido y mejora uso inmediato.
2. Fase 2, porque sin memoria el asistente seguira generando ruido.
3. Fase 3, porque resuelve la promesa rota del acceso local.
4. Fase 5 en paralelo parcial, porque la confianza depende de automatizaciones fiables.
5. Fase 4 despues de tener runner real, para no modelar en abstracto.
6. Fase 6 cuando el piloto interno sea estable.

Decision

Construir Komandesk como producto hibrido:

• SaaS coordina, audita y vende claridad.
• Runner local ejecuta cuando el trabajo necesita la maquina del usuario.
• Repo/remoto cubre equipos que prefieren Git como frontera.
• El asistente recuerda por proyecto y no inventa contexto.
• Los modelos son configurables, pero el producto vende resultados verificables, no nombres de modelos.