ComandeskHelp Inicio

Runner local

Estado: guia operativa inicial

Fecha: 2026-05-29

Para que sirve

El runner local permite ejecutar tareas de Komandesk en una maquina concreta del usuario cuando el trabajo necesita acceso a archivos, repositorios, plantillas, credenciales locales o modelos locales.

No es acceso remoto automatico al disco desde SaaS. El disco local solo es accesible si el usuario instala, autoriza y mantiene vivo el runner en esa maquina.

Cuando usarlo

Usa runner local si:

  • el proyecto vive en una carpeta local;
  • el agente debe leer o modificar archivos que no estan en el servidor;
  • el usuario trabaja con modelos locales;
  • hay herramientas instaladas solo en esa maquina;
  • no conviene subir el repo o los assets a un servidor.

Usa repo/remoto si:

  • el trabajo puede hacerse desde Git;
  • el equipo prefiere branch, commit y PR como frontera;
  • no quieres depender del ordenador del usuario.

Usa SaaS worker si:

  • la tarea no necesita disco local;
  • las credenciales estan en la boveda del workspace;
  • el resultado puede revisarse en Komandesk.

Flujo de alta

  1. Crear o abrir el proyecto.
  2. Ir a Readiness y pulsar Configurar despliegues.
  3. Elegir el preset Runner local.
  4. Guardar un target local_machine vinculado al proyecto.
  5. Crear o comprobar credenciales necesarias.
  6. Instalar y arrancar el runner local en la maquina autorizada.
  7. Confirmar que el cockpit muestra Runner vivo.
  8. Crear un preflight de primera ejecucion en modo Runner local.
  9. Ejecutar una tarea pequena.
  10. Cerrar con evidencia, tiempo y siguiente paso.

Variables minimas del runner

El runner necesita:

  • URL de la API de Komandesk.
  • Token con alcance minimo para el workspace/proyecto.
  • Identificador de worker.
  • Lista de agentes o runtimes disponibles.
  • Ruta de trabajo permitida si va a tocar disco.
  • Modelos disponibles si usa runtimes locales.

Ejemplo conceptual:


OPS_API_BASE=https://ops.example.com/api

OPS_WORKSPACE_IDS=1

OPS_RUNNER_TOKEN=ops_runner_xxx

OPS_RUNNER_ID=macbook-aj-local

OPS_RUNNER_ALLOWED_PATHS=/Users/user/proyectos/cliente

SUPPORTED_AGENT_SLUGS=opencode,codex

SUPPORTED_MODELS=gpt-5,gpt-5-mini,local-qwen-coder

npm run runner:local:doctor

npm run runner:local

El launcher tambien mantiene compatibilidad con OPS_SERVICE_TOKEN/WORKER_ID para workers internos, pero el modo local debe preferir OPS_RUNNER_TOKEN y OPS_RUNNER_ALLOWED_PATHS.

Si el token del runner esta acotado a uno o varios workspaces, define OPS_WORKSPACE_IDS.

Esto evita llamadas de descubrimiento innecesarias y deja claro que cola debe revisar el runner.

Flujo corto para piloto de fin de semana

Este flujo es para uso asistido, no para cliente final sin soporte.

  1. Abrir el cockpit del proyecto y localizar Readiness de ejecucion.
  2. En Runner local, indicar la ruta permitida y crear la vinculacion.
  3. Copiar el comando antes de refrescar; el token solo se muestra una vez.
  4. Crear la tarea Preflight runner local desde el mismo panel.
  5. Ejecutar el comando en la maquina autorizada.

Flujo equivalente por API:

  1. Crear el runner desde Komandesk y copiar el token visible una sola vez.
  2. Exportar OPS_API_BASE, OPS_RUNNER_TOKEN, OPS_RUNNER_ID y OPS_RUNNER_ALLOWED_PATHS.
  3. Declarar SUPPORTED_AGENT_SLUGS, por ejemplo opencode,codex.
  4. Ejecutar el doctor:

npm run runner:local:doctor
  1. Si aun no hay token, validar solo la maquina:

npm run runner:local:doctor -- --offline
  1. No arrancar el runner si el doctor marca FAIL.
  2. Cuando el doctor marque PASS, arrancar el proceso:

npm run runner:local

El doctor comprueba:

  • URL de API y token de runner;
  • identificador de runner;
  • rutas permitidas y si existen como directorio;
  • runtimes locales declarados en SUPPORTED_AGENT_SLUGS;
  • autenticacion basica detectable para opencode, codex y claudecode;
  • herramientas auxiliares git, node y npm;
  • heartbeat contra POST /api/local-runners/heartbeat cuando no se usa --offline.

El doctor no imprime el token y no debe usarse para guardar credenciales personales.

Vinculacion Fase 3

La vinculacion base usa local_runner_bindings y tokens API revocables.

Flujo operativo:

  1. Un admin crea el runner desde POST /api/local-runners.
  2. OPS devuelve un token visible una sola vez.
  3. El usuario instala/configura el runner local con ese token.
  4. El runner envia POST /api/local-runners/heartbeat.
  5. OPS actualiza worker_heartbeats con el runner_id, agentes y modelos declarados.

Contrato tecnico interno: docs/architecture/local-runner-contract.md.

Readiness esperado

En el cockpit del proyecto deben verse estos estados:

  • Destino: al menos un target local_machine vinculado.
  • Runner vivo: heartbeat reciente del worker.
  • Credenciales: credenciales necesarias activas.
  • Agentes/perfiles: runtime elegido disponible.

Si hay target local pero no hay heartbeat, el proyecto no debe considerarse listo para runner local.

Primer preflight

La primera tarea debe ser pequena y reversible.

Checklist recomendado:

  • confirmar ruta de trabajo;
  • confirmar que project_path y working_folder quedan dentro de OPS_RUNNER_ALLOWED_PATHS;
  • listar archivos principales sin modificarlos;
  • validar que el modelo/runtime responde;
  • comprobar que no se escriben secretos en logs;
  • registrar evidencia;
  • registrar tiempo. El launcher registra automaticamente tiempo ai de runtime cuando completa o falla una ejecucion; revisa la nota antes de cerrar.

No empezar con deploy, migraciones, borrados o cambios masivos.

Bloqueos que deben parar la prueba

  • OPS_RUNNER_ALLOWED_PATHS vacio.
  • Ruta inexistente o no autorizada.
  • Ningun runtime listo.
  • OPS_RUNNER_TOKEN ausente en modo online.
  • Heartbeat rechazado por Komandesk.
  • Runtime requerido en SUPPORTED_AGENT_SLUGS no instalado o no autenticado.

Si aparece cualquiera de estos bloqueos, crear o actualizar una tarea de setup y registrar tiempo antes de intentar ejecutar trabajo real.

Modelos locales

Los modelos locales pertenecen al runner, no al SaaS.

El runner debe declarar que modelos puede usar. Komandesk puede coordinar la tarea, pero no debe prometer disponibilidad de un modelo local si el runner no lo anuncia o si el usuario no lo tiene instalado.

Seguridad

Reglas minimas:

  • token con el menor alcance posible;
  • ruta local limitada;
  • en modo local, usar primero las sesiones/credenciales instaladas en la maquina del usuario;
  • entregar credenciales del workspace al runner solo mediante delegacion explicita y auditable;
  • no devolver secretos al navegador;
  • no ejecutar tareas sensibles sin gate humano;
  • no cerrar sin evidencia;
  • revocar token si el dispositivo se pierde;
  • marcar como bloqueada cualquier tarea que requiera una ruta no autorizada.

Limites actuales

  • El runner local no esta empaquetado todavia como instalador final.
  • La asociacion entre heartbeat y target local aun es operativa, no una vinculacion criptografica por dispositivo.
  • El primer uso debe ser asistido.
  • La automatizacion sin supervision debe esperar hasta que haya historial de preflights correctos.
  • El doctor mejora el primer uso, pero no sustituye al instalador ni al daemon.

Criterio para venderlo

Se puede vender como:

> Ejecucion local supervisada para proyectos que necesitan acceso a archivos o modelos del usuario.

No se debe vender como:

> El SaaS entra en tu ordenador y ejecuta cualquier cosa solo.