TermDesk

Un cliente de escritorio multiplataforma SSH + SFTP + VNC + RDP — terminales multipestaña, transferencias de archivos en streaming y escritorios remotos (VNC sobre SSH, además de RDP nativo), en una sola ventana.

Estado: en producción — terminal SSH, SFTP, VNC sobre SSH, RDP nativo, acceso a agentes MCP, gestor de túneles SSH, automatización de flotas, terminales locales con elección de programa de terminal (shell de inicio de sesión / tmux / Zellij / screen / shells alternativos), Prompt Book + Routines programadas, ajustes, paleta de comandos y empaquetado.

✨ Características

• 🖥️ Hosts flexibles — crea hosts solo SSH, solo VNC o combinados en el momento de crearlos. SSH y VNC son opcionales de forma independiente. Los hosts VNC puros admiten conexiones TCP directas o por túnel SSH (con un error claro si intentas tunelizar sin credenciales SSH). Las acciones de la interfaz, la paleta de comandos y los botones de prueba se adaptan según el tipo de host.

• 🖥️ Terminal SSH multipestaña — xterm.js (WebGL) con búsqueda, copiar/pegar y redimensionado; muchas sesiones paralelas al mismo host o a hosts distintos. La salida temprana se almacena en búfer hasta que la terminal se conecta, para que no se pierdan los MOTD/banners.

• 📁 SFTP con cola de transferencia en streaming — explorador de archivos remoto, arrastrar y soltar (subida recursiva de carpetas), streaming fragmento a fragmento con memoria constante, cancelar/reintentar, edición in situ con subida automática al guardar.

• 🔒 VNC sobre SSH — noVNC renderizado en la aplicación, alimentado a través de un puente WebSocket de loopback protegido por tokens de un solo uso de 30 s; el transporte predeterminado es un túnel SSH forwardOut, por lo que el puerto 5900 nunca queda expuesto. El modo directo también es compatible con hosts solo VNC.

• 🖥️ RDP — conéctate a hosts Windows/RDP desde la aplicación mediante un cliente IronRDP WASM alimentado a través de un proxy RDCleanPath en proceso (con la misma forma que el puente VNC: token de un solo uso de 30 s, verificación de origen y terminación TLS), con fijación de certificado de servidor de confianza en el primer uso.

• 🔐 Bóveda cifrada — hosts, grupos, snippets y hosts conocidos en SQLite; las contraseñas/frases de contraseña se cifran con safeStorage respaldado por el llavero del sistema en el momento en que llegan al proceso principal.

• 🛡️ Verificación de clave de host — diálogo de aprobación de huella SHA256 en la primera conexión, bloqueo total ante un cambio de clave del mismo tipo, y una advertencia contundente y distinta de «posible hombre en el medio» cuando un host conocido presenta una clave/tipo que nunca se ha confiado para él.

• 🪜 ProxyJump — cadenas de múltiples saltos (user@jump:port,next) mediante forwardOut encadenado.

• 🔌 Gestor de túneles SSH — define, persiste e inicia/detiene reenvíos de puerto locales (-L) y proxies SOCKS5 dinámicos (-D) desde un panel lateral, con un punto de estado en vivo + rendimiento. Reutiliza la conexión de una terminal abierta cuando es posible; sin acciones destructivas, limitado al propietario y registrado. Consulta docs/TUNNELS.md.

• 🪟 Paneles divididos — ve dos sesiones una al lado de la otra o apiladas (Alt-clic en una pestaña o en la barra de herramientas de división), con un divisor arrastrable. Ideal combinado con la automatización multi-host para una cuadrícula de monitorización en vivo.

• 💻 Terminales locales — pestañas de shell node-pty en tu propia máquina, con directorios de trabajo guardados — sin necesidad de SSH. La ruta remota predeterminada por host se respeta al conectar.

• 🧩 Elige tu programa de terminal — elige qué se ejecuta cuando se abre una terminal (Ajustes → General): tu shell de inicio de sesión predeterminado, un multiplexor (tmux, Zellij, GNU Screen — persisten entre reinicios/desconexiones) o un shell alternativo (bash, zsh, fish, PowerShell, Nushell). Solo se pueden seleccionar los programas detectados en tu máquina; la elección se aplica tanto a las terminales locales como a las sesiones SSH (se ejecuta en el remoto si está presente; si no, un shell simple).

• 🚀 Abrir en terminal externa — entrega el directorio actual a tu terminal GUI favorita — Ghostty, Warp, iTerm2, kitty, Alacritty, WezTerm, GNOME Terminal, Konsole, Windows Terminal — detectadas en tu máquina, con un valor predeterminado guardado (Ajustes → General), desde ⌘K o un botón de un clic en cualquier pestaña de terminal local.

• ⚡ Automatización de flotas — ejecuta un snippet o comando en todo un grupo de hosts SSH a la vez, con salida en streaming en vivo por host.

• 🕘 Registro de actividad — una línea temporal local de conexiones/desconexiones, aperturas de SFTP/VNC y ejecuciones de automatización. Solo metadatos: los tokens de comando que contienen secretos se redactan y las entradas se purgan después de 90 días.

• 🎨 Esquemas de color de terminal — Dracula, Solarized Dark, Gruvbox, One Dark y Nord integrados (además del predeterminado), según tu preferencia.

• 🧱 Barra lateral personalizable — muestra u oculta cada sección de la barra lateral izquierda (Hosts, Terminales locales, Espacios de trabajo, Túneles, Snippets, Prompt Book, Routines) desde Ajustes → General o el botón Personalizar de la barra lateral. Tu elección persiste; todo es visible por defecto.

• 🧩 Prompt Book — prompts reutilizables y con plantillas para agentes de IA. Los prompts son texto plano con marcadores de posición {{variable}} (opcionalmente {{name:default}} / {{name|description}}); al ejecutar uno se piden los valores, se muestra una vista previa en vivo y se envía el texto renderizado a la terminal activa (SSH o local) o se lanza en un agente de IA — Claude Code, Aider, OpenCode, Codex o Gemini — en un directorio que elijas. El uso de plantillas es sustitución pura (sin eval) y el prompt se pasa como un único argumento entre comillas, por lo que los metacaracteres de shell que contenga son inertes.

• 🔁 Routines — trabajos guardados de «ejecutar este prompt con este agente en este directorio», que se ejecutan bajo demanda o según un horario (intervalo / diario / cron), cada uno con su propio historial de ejecuciones. Las Routines se disparan mientras TermDesk está abierto, y una ejecución que se perdió mientras la aplicación estaba cerrada se pone al día una vez en el siguiente arranque, en lugar de ejecutar todas las ejecuciones perdidas de golpe. La autonomía sin supervisión es opcional y está desactivada por defecto; los resúmenes de ejecución almacenados tienen los secretos redactados.

• 📋 Snippets — comandos guardados que se envían a la sesión activa.

• ⌨️ Paleta de comandos — búsqueda difusa de hosts con ⌘/Ctrl+K + todos los comandos (terminales, SFTP, VNC, automatización, registros); pulsa ? para la chuleta de atajos.

• ⚙️ Ajustes — tema (oscuro / claro / Sistema, siguiendo al SO), fuente de terminal + esquema de color, comportamiento de pegar con clic derecho, keepalive de SSH; JSON plano, nunca secretos.

• 🤖 Acceso de agentes de IA (MCP) — permite que Claude, Cursor, Grok o cualquier cliente MCP use TermDesk: listar hosts, ejecutar comandos, desplegarse por una flota. El agente recibe manos, nunca llaves — las credenciales permanecen en el proceso principal, cada acción requiere aceptación por host + aprobación + se muestra en vivo en un registro de Actividad de IA. Desactivado por defecto. Consulta docs/MCP-INTEGRATION.md.

• 🏠 Local-first — tus hosts, claves e historial nunca salen de tu máquina; sin cuenta en la nube obligatoria, sin telemetría.

Related MCP server: SentryFrogg MCP Server

🏗 Arquitectura

Toda la lógica SSH/SFTP/VNC vive en el proceso principal. El renderizador está completamente aislado (contextIsolation: true, nodeIntegration: false, sandbox: true) y solo se comunica con él a través de un contrato IPC tipado y validado con Zod (src/shared/ipc.ts).

flowchart LR
    subgraph R["Renderer (sandboxed, no Node)"]
        UI["React 19 UI<br/>zustand stores"]
        XT["xterm.js<br/>terminal"]
        NV["noVNC<br/>RFB client"]
    end

    subgraph M["Main process"]
        IPC["Typed IPC<br/>Zod-validated contracts"]
        SM["SessionManager<br/>(ssh2: shell, agent,<br/>keys, ProxyJump)"]
        SF["SftpManager +<br/>TransferManager<br/>(streaming queue)"]
        WB["ws-bridge<br/>127.0.0.1, random port,<br/>single-use 30s tokens"]
        VA[("Vault<br/>better-sqlite3 + Drizzle<br/>secrets via safeStorage")]
    end

    RH[("Remote host<br/>sshd · sftp · vncserver")]

    UI <-->|"invoke/handle"| IPC
    XT <-->|"ssh:data:#lt;sessionId#gt; stream"| IPC
    IPC <--> SM
    IPC <--> SF
    SM --- VA
    SF --- SM
    NV -->|"ws://127.0.0.1:#lt;port#gt;/#lt;token#gt;"| WB
    WB -->|"variant B (default):<br/>ssh2 forwardOut → :5900"| SM
    WB -.->|"variant A (opt-in):<br/>direct TCP → :5900"| RH
    SM <-->|"SSH"| RH

Dos excepciones deliberadas a «los secretos permanecen en el proceso principal»: la contraseña VNC almacenada (para el handshake de credenciales RFB) y la contraseña RDP almacenada (para el cliente IronRDP) se descifran en el proceso principal y se devuelven al renderizador. Ninguna de las dos está actualmente vinculada a una pestaña abierta ni limitada en velocidad — consulta Limitaciones conocidas.

🚀 Inicio rápido

TermDesk se ejecuta actualmente desde el código fuente. konraddzbik/termdesk no tiene etiquetas ni GitHub Releases, por lo que todavía no hay nada que descargar desde la página de Releases — consulta INSTALL.md.

Necesitas Node.js >=22.12.0 y npm 10+, además de un toolchain de C/C++ (Xcode Command Line Tools / build-essential / Visual Studio C++ build tools) para que los módulos nativos puedan compilarse. En Linux también necesitas un llavero del sistema desbloqueado (gnome-libsecret o kwallet) — TermDesk falla de forma segura (fail-closed) en lugar de usar el respaldo inseguro basic_text de Electron, así que sin uno no puedes guardar una contraseña de host (SECURITY.md).

npm install        # also applies the better-sqlite3 patch + rebuilds native deps
npm run dev        # electron-vite dev server + Electron window, HMR

Primera ejecución: npm install && npm run dev abre una aplicación utilizable — no hay comprobación de licencia, ni asientos ni cuenta. Consulta CONTRIBUTING.md para la configuración completa de desarrollo, incluido el paso de ABI de better-sqlite3 que necesitas antes de que npm test funcione.

npm run dist produce un instalador sin firmar para el SO anfitrión (dist/TermDesk-<version>-arm64.dmg en macOS con Apple Silicon, además de un .dmg x64 compilado de forma cruzada). No publica nada. Consulta INSTALL.md para la configuración desde el código fuente, los nombres de los artefactos locales y cómo se crearía una futura GitHub Release.

🧪 Entorno de pruebas de desarrollo

Un único contenedor Docker proporciona SSH + TigerVNC para pruebas locales — no se necesitan servidores reales:

npm run test:keys                                  # throwaway SSH keys (untracked)
docker compose -f docker-compose.test.yml up -d

Bancos de pruebas de humo E2E

Cinco suites end-to-end autocontenidas se ejecutan dentro de la aplicación Electron real (las cuatro primeras contra el contenedor Docker; la suite MCP no necesita servicios externos). Cada una imprime un marcador *_OK al terminar con éxito:

✅ Pruebas

npm test                # unit + integration suite (vitest) — all green on main
npm run test:coverage   # v8 line coverage report into coverage/

Vitest ejecuta las pruebas del renderer bajo jsdom (Testing Library) y todo lo demás bajo node. La cobertura se concentra donde importa: la lógica pura tiene una cobertura alta, mientras que el pegamento de procesos y las carcasas de UI están cubiertos por los cinco smokes e2e en lugar de pruebas unitarias (los porcentajes a continuación son orientativos, no fijos — ejecuta npm run test:coverage para ver las cifras actuales):

• Alta (líneas): shared 97.1 % —el contrato IPC de Zod del que depende todo proceso—, renderer/lib 97.5 %, main/store 81.4 % (db, hosts-repo, settings y snippets-repo al 100 % o cerca), ssh-util 100 %, el analizador de ~/.ssh/config y su resolvedor de Include en los altos 90.

• Baja, y cubierta por los smokes en su lugar: el pegamento de los handlers de main/ipc 9.8 %, session-manager y sftp-manager/transfer-manager 0 %, vnc-manager y las carcasas de UI (SftpTab, TerminalView, VncTab, el layout y los paneles laterales) baja o cero. Son pegamento de procesos y carcasas de Electron/DOM; los harnesses de TERMDESK_SMOKE los ejercitan de extremo a extremo contra un servidor real. Los puntos de entrada y los archivos *-smoke.ts están excluidos de la cobertura por configuración.

Build + typecheck + lint están limpios, y un lanzamiento de desarrollo con ventana registra cero líneas de error.

⌨️ Atajos de teclado

⚙️ Configuración

Tema (oscuro, claro o Sistema —siguiendo el prefers-color-scheme del SO—), tamaño/familia de fuente de la terminal, intervalo de keepalive de SSH — almacenados como JSON plano en userData/settings.json (nunca secretos).

📡 Detalles de las funcionalidades

Terminal SSH

• Toda la lógica de ssh2 vive en el proceso principal (src/main/ssh/session-manager.ts); el renderer solo ve una API de streams tipada. La salida se transmite por ssh:data:<sessionId>; la salida temprana se almacena en búfer hasta que la terminal se conecta.

• Autenticación: contraseña del vault (con respaldo keyboard-interactive), clave privada (+ frase de contraseña cifrada) o agente SSH (SSH_AUTH_SOCK, pipe de OpenSSH en Windows). Los secretos solo se descifran en el momento de la conexión.

• Claves de host: la primera conexión muestra un diálogo de aprobación de huella SHA256 y persiste en la tabla known_hosts; una discrepancia bloquea la conexión de forma tajante.

• Cadenas ProxyJump (user@jump:port,next) mediante forwardOut encadenado; keepalive de 15 s.

SFTP

• Las sesiones SFTP reutilizan la conexión SSH activa de una terminal abierta al mismo host (sin un segundo inicio de sesión) y recurren a una conexión dedicada sin shell.

• Las transferencias se transmiten fragmento a fragmento (memoria constante — 1 GB verificado por debajo de 300 MB de RSS) y se pueden cancelar/reintentar; soltar carpetas las sube recursivamente conservando la estructura.

• La edición in situ descarga a un archivo temporal, abre el editor del SO y sube automáticamente al guardar.

VNC

• noVNC se renderiza en el renderer; habla WebSocket con un puente del proceso principal vinculado a 127.0.0.1 en un puerto aleatorio. Cada conexión requiere un token de un solo uso de 30 s — otros procesos locales no pueden usar el puente (de ahí ws://127.0.0.1:* en la CSP).

• El transporte predeterminado es un canal SSH forwardOut (variante B — el puerto 5900 nunca se expone), que reutiliza una conexión de terminal activa al host cuando existe; TCP plano (variante A) es opcional por host.

• Las contraseñas VNC y RDP almacenadas se descifran en main y se devuelven al renderer para sus respectivos clientes — las dos excepciones documentadas a «los secretos permanecen en main».

• Barra de herramientas: alternar escalado local / redimensionado remoto, pegar del portapapeles, Ctrl+Alt+Supr, pantalla completa, reconexión (cada reconexión genera un token + túnel nuevos).

Vault

• Los hosts, grupos, snippets y known_hosts viven en SQLite (better-sqlite3 + Drizzle) en el directorio userData de la aplicación.

• Las contraseñas/frases de contraseña se cifran con safeStorage (clave del llavero del SO) en el proceso principal en el momento en que llegan; solo los blobs de texto cifrado tocan la base de datos, y los secretos nunca se envían de vuelta al renderer.

• La importación de ~/.ssh/config analiza Host/HostName/Port/User/IdentityFile/ProxyJump, resuelve las directivas Include (rutas con tilde/relativas/absolutas y globs, con protecciones de ciclo/profundidad/tamaño) y fusiona los valores predeterminados de Host */comodines en hosts concretos usando la regla de OpenSSH de que el primer valor obtenido prevalece.

🔐 Lista de verificación de seguridad

• contextIsolation: true, nodeIntegration: false, sandbox: true — el renderer y el preload nunca tocan Node.

• CSP estricta mediante meta etiqueta: script-src 'self', sin unsafe-eval, sin módulos remotos; connect-src solo permite 'self' y WebSockets de loopback (el puente VNC protegido por token). La relajación solo para desarrollo ocurre a través de un plugin de Vite que falla ruidosamente ante desviaciones.

• webSecurity: true; navegación con verificación de origen; window.open denegado (https: externo → navegador del sistema); <webview> bloqueado; las solicitudes de permisos se deniegan por defecto.

• Cada payload de IPC se valida con Zod (src/shared/ipc.ts es el contrato único); los resultados de invoke están tipados de extremo a extremo mediante IpcInvokeMap.

• Los secretos (contraseñas SSH/VNC, frases de contraseña de claves) se cifran con safeStorage en el proceso principal en el momento en que llegan; solo se persiste el texto cifrado; el descifrado ocurre en el momento de la conexión y las referencias se descartan de inmediato. Verificado por TERMDESK_SMOKE=vault. Dos excepciones documentadas: las contraseñas VNC y RDP cruzan al renderer para sus clientes de protocolo (consulta Limitaciones conocidas).

• Los errores que cruzan el IPC se sanitizan (solo la primera línea, sin stacks/rutas); los secretos nunca se registran.

• Las sesiones, los manejadores SFTP, las transferencias y las solicitudes de clave de host están acotados al WebContents propietario que los creó y se destruyen cuando este se destruye.

• Claves de host: aprobación de huella SHA256 en la primera conexión, bloqueo tajante ante discrepancia — para el destino final y cada salto ProxyJump.

• El registro de actividad contiene solo metadatos: nombre de usuario del SO, tokens de comando con secretos redactados, purga a los 90 días.

• Contraseña maestra opcional (segunda capa de cifrado derivada de Argon2id) — diferida, registrada como mejora futura.

Consulta SECURITY.md para el modelo de seguridad completo, las limitaciones conocidas y la política de divulgación de vulnerabilidades.

📂 Estructura del proyecto

src/
  main/                  # Electron main process — all SSH/SFTP/VNC logic lives here
    ipc/                 # IPC handlers per domain (ssh, sftp, vnc, hosts, …)
    ssh/                 # session-manager, ssh-config-parser, ssh-util (+ smoke)
    sftp/                # sftp-manager, transfer-manager, edit-watch (+ smoke)
    vnc/                 # ws-bridge, vnc-manager (+ smoke)
    store/               # Drizzle + better-sqlite3, secrets (safeStorage), settings
  preload/               # contextBridge — typed, minimal API surface (window.api)
  renderer/              # React UI (no Node access)
    components/{layout,hosts,terminal,sftp,vnc,snippets,ui}/
    hooks/  stores/  lib/
  shared/                # IPC channel contracts + Zod schemas shared by all processes

🗺 Limitaciones conocidas / hoja de ruta

• Contraseña maestra — capa de cifrado secundaria opcional derivada de Argon2id sobre el vault; diferida.

• Prueba smoke con Playwright (lanzar la app → añadir host → conexión simulada) — diferida; los cinco harnesses de TERMDESK_SMOKE cubren e2e hoy.

• Importación de ~/.ssh/config — los bloques Match y la expansión de tokens (%h/%p) todavía se omiten; la importación de inventario de proveedores cloud (AWS/GCP) no está implementada.

Consulta SECURITY.md para la hoja de ruta de endurecimiento.

🔧 Notas sobre módulos nativos

• better-sqlite3 necesita un parche de código fuente para compilar contra el V8 de Electron (aún no hay prebuilds upstream) — se aplica automáticamente mediante patch-package en npm install (patches/better-sqlite3+12.10.0.patch).

• cpu-features (dependencia nativa opcional de ssh2) se sobrescribe a noop2 en package.json para evitar una compilación nativa innecesaria; ssh2 recurre a su ruta de JS puro.

🤝 Contribuciones

Las issues y las pull requests son bienvenidas. El plan de entrega para la instalación externa, los paquetes y la configuración del colaborador está en docs/OSS-DELIVERY-PLAN.md. CONTRIBUTING.md contiene la configuración de desarrollo —incluidas las dos trampas de módulos nativos que de otro modo te costarán una tarde—, los invariantes que el código nuevo debe mantener y la lista de verificación previa al PR. Las contribuciones son MIT inbound=outbound: sin CLA, sin cesión de derechos de autor.

La participación se rige por el Código de Conducta. Los problemas de seguridad se canalizan a través del canal privado en SECURITY.md, nunca mediante una issue pública.

📄 Licencia

El código fuente de este repositorio se publica bajo la Licencia MIT — consulta LICENSE. Puedes usarlo, modificarlo y redistribuirlo, incluso comercialmente, siempre que el aviso de copyright y el texto de la licencia lo acompañen.

Cuando existan instaladores precompilados en la página de Releases, estarán además cubiertos por EULA.txt, que rige esos binarios. Actualmente no hay GitHub Releases, por lo que una compilación que hagas tú mismo a partir de este código fuente se rige únicamente por LICENSE.

No hay verificación de licencia, activación de asientos ni cuenta en este cliente: el subsistema de licencias comerciales se eliminó cuando se publicó el código fuente, así que lo que compiles desde este repositorio es la aplicación completa.

Ese límite se aplica en el código, no solo se describe aquí: el aviso de EULA del primer arranque se compila únicamente en los builds de release del propio proyecto, por lo que el npm run dist de un fork, un paquete de distribución o tu propio instalador nunca lo muestran.

Las dependencias de terceros conservan sus propias licencias, enumeradas en THIRD-PARTY-NOTICES.md. Una conlleva una obligación que merece la pena mencionar: @novnc/novnc es MPL-2.0 y este repositorio lo parchea (patches/@novnc+novnc+1.7.0.patch), por lo que esa modificación se publica aquí bajo MPL-2.0 junto con el resto del código fuente.