¿Qué es?

Desarrollo

Easy-Web-Vibecoding es un workspace web auto-hospedado diseñado para desarrolladores que trabajan con Claude Code, Codex, OpenCode y shells tradicionales. Proporciona persistencia de sesiones mediante tmux, paneles divididos, herramientas de archivos y monitorización GPU. La interfaz se llama CC Terminal y conecta herramientas de línea de comandos existentes a través de tmux + FastAPI + xterm.js al navegador.

El proyecto no almacena ni gestiona API keys de modelos — los usuarios deben autenticarse individualmente en cada servicio (Claude Code, Codex o OpenCode). Esta arquitectura de seguridad centralizada minimiza riesgos de exposición de credenciales y permite a los desarrolladores gestionar sus propias claves de API según sus necesidades específicas.

Para quién

• Desarrolladores que usan Claude Code, Codex o OpenCode como herramientas principales de desarrollo
• Equipes que necesitan persistencia de sesiones en terminal web para trabajo colaborativo
• Usuarios que prefieren no almacenar API keys centralizadas por razones de seguridad
• Profesionales que requieren monitorización GPU en tiempo real durante sesiones de desarrollo
• Desarrolladores que trabajan con shells tradicionales y necesitan acceso web a sus herramientas

Casos de uso

• Automatización de flujos de trabajo de desarrollo mediante integración con Claude Code
• Herramientas de desarrollo con persistencia de sesiones para mantener contextos largos
• Monitorización GPU en tiempo real durante entrenamiento o inferencia de modelos
• Conversión de prototipos a código frontend real (Easy-Vibe) con acceso desde navegador
• Acceso remoto a entornos de desarrollo sin instalar clientes locales pesados
• Colaboración en tiempo real mediante paneles divididos compartidos

Funciones

• Persistencia de sesiones tmux: tareas sobreviven al cierre del navegador o reinicio del backend web
• Panels divididos con routing independiente por pane — cada panel mantiene su propio contexto
• Herramientas de archivos integradas para navegación y edición básica
• Monitorización GPU en tiempo real durante ejecución de modelos
• Soporte para xterm256 y truecolor con ajuste automático de contraste
• Autenticación con tokens firmados (nonce-bearing) que expiran después de 30 días
• Compatibilidad con Bearer authentication para API clients externos
• Verificación del foreground command y alternate-screen state para fullscreen Codex

Arquitectura

Backend: FastAPI + Python | Frontend: JavaScript/TypeScript | Terminal: xterm.js + tmux | WebSocket para comunicación real-time. El backend verifica el foreground command y alternate-screen state para manejar correctamente fullscreen Codex.

La arquitectura utiliza WebSocket para mantener conexiones persistentes entre el frontend y el backend, permitiendo comunicación bidireccional en tiempo real. FastAPI gestiona las rutas del API y proporciona endpoints para autenticación, gestión de sesiones y operaciones de terminal.

Requisitos reales

• Python 3.x con FastAPI instalado en el servidor backend
• Node.js (opcional, recomendado para tests de navegador y desarrollo frontend)
• tmux instalado en servidor — requisito obligatorio para persistencia de sesiones
• C compiler (cc) para integración tests y compilación de fixtures
• WebSocket server compatible con soporte para conexiones persistentes
• Linux o Unix-like OS para compatibilidad completa con tmux

Instalación/despliegue

Clonar repositorio y ejecutar según documentación oficial. Actualizar checkout a release v0.1.3+ para fixes de terminal history scrolling. Reiniciar Web backend tras actualizar (solo refresh no carga Python code). Antes de producción: revisar persistencia de datos, secrets, copias de seguridad y proxy HTTPS.

Comandos de instalación recomendados:

git clone https://github.com/DarranLiu/Easy-Web-Vibecoding
cd Easy-Web-Vibecoding
git checkout v0.1.3
pip install -r requirements.txt
python -m uvicorn main:app --reload

Para despliegue con Docker, consultar documentación oficial en el repositorio GitHub.

Persistencia

Las sesiones tmux permanecen activas al cerrar el navegador o reiniciar el backend web. No se pierden tareas en ejecución. Verificar que el container no posea tmux server o agent processes antes de reiniciar.

Importante: Antes de reiniciar un servicio o contenedor, confirmar que no posee el tmux server ni los procesos de agentes. No eliminar ni recrear un contenedor que contenga las únicas copias de tareas en ejecución.

Red/puertos

WebSocket para comunicación real-time con frontend. Puerto específico según despliegue (consultar documentación oficial). No expone directamente API keys de modelos — la autenticación se gestiona a nivel de aplicación.

El backend utiliza WebSocket para mantener conexiones persistentes, permitiendo que el frontend reciba actualizaciones en tiempo real y envíe comandos al terminal remoto sin necesidad de polling constante.

Seguridad

• Tokens firmados con nonce-bearing session proof (v0.1.1+)
• Expira después de 30 días — reduce ventana de ataque
• Bearer authentication compatible para API clients
• Revalida working directory antes de launch — previene ejecución en directorios incorrectos
• Rejects unsafe names y NUL bytes — evita inyecciones de nombre de archivo
• Private permissions y O_NOFOLLOW para archivos creados — seguridad por defecto
• Persiste sesiones sin almacenar credenciales sensibles

Actualización/backup

Actualizar checkout a release v0.1.3+ y reiniciar Web backend. No delete o recreate container que contenga running tasks. Backup de sesiones tmux antes de cambios mayores.

Procedimiento recomendado para actualización:

1. Actualizar repositorio a la última versión estable
2. Reiniciar el backend web usando método de despliegue existente
3. Refrescar navegador — solo refresh no carga Python code nuevo
4. Verificar que WebSocket se reconecta correctamente
5. Backup de sesiones tmux antes de cambios mayores

Ventajas

• Persistencia real de sesiones tmux — tareas sobreviven al cierre del navegador
• No almacena API keys de modelos — arquitectura segura por defecto
• Soporte multi-pane con routing independiente por pane
• Fixes de contraste xterm 4.5:1 (v0.1.2+) — texto legible en todos los temas
• Terminal history scrolling confiable (v0.1.3+) — incluso con fullscreen Codex
• Autenticación firmada con expiración automática de tokens

Limitaciones

• No recrea messages que aplicación ya discarded — mensajes eliminados no se recuperan
• No envía prompts, Enter o model API requests — solo interfaz de terminal
• Custom wrappers/key bindings pueden necesitar adaptación específica
• Dim placeholder text mantiene xterm lower contrast target — algunos placeholders menos legibles
• Requiere tmux instalado en servidor — no funciona sin esta dependencia

Alternativas reales

• Claude Code standalone (sin persistencia tmux) — más simple pero sin sesiones persistentes
• Codex/VSCode con extensiones de terminal web — alternativa comercial con integración VSCode
• OpenCode con configuraciones alternativas — enfoque diferente a la persistencia de sesiones
• Terminal.app con SSH — acceso remoto tradicional sin interfaz web integrada

Releases

• v0.1.3 (27 sep 2026): Terminal History Scrolling — fixes scrolling issues con fullscreen Codex, PageUp/PageDown bindings para navegación por páginas en lugar de scroll pixel-precise
• v0.1.2 (23 sep 2026): Readable Terminal Input in Dark/Light Mode — xterm contrast adjustment 4.5:1 para texto legible en todos los temas, incluyendo light text on light backgrounds y dark text on dark backgrounds
• v0.1.1 (21 sep 2026): Session and file-boundary hardening — signed tokens con nonce-bearing, path containment contra CC_WEB_ROOTS, rejects unsafe names y NUL bytes, private permissions y O_NOFOLLOW para archivos creados

FAQ