Playbook UC2 Gateway-Web Session

01

Objetivo

Crear una sesión Claude Code desde la UI web (gateway-web) que ejecuta en el workspace container remoto. La sesión debe arrancar, mostrar output en la UI y responder a prompts. Esto verifica el camino completo: UI → gateway-server (workspace) → cli-launcher → Claude Code → output NDJSON → UI.

drag to pan · scroll to zoom · double-click to fit

02

F1 — Abrir gateway-web

2 min

Cargar la UI y conectarse al workspace

Abrir http://localhost:5173 (dev local) o la URL desplegada gateway-web carga sin errores de consola
En el selector de slot, elegir 'Remote' e ingresar https://lab1-helsinki.api.mks2508.systems Se conecta al gateway-server del workspace
Verificar que aparece 'Connected' o el indicador de conexión La UI estableció WS con el gateway-server

gateway-web — desarrollo local

# Arrancar gateway-web en modo dev:
$ cd apps/gateway-web
$ bun run dev

# → Vite dev server en http://localhost:5173

# En la UI:
# 1. Slot selector → Remote
# 2. URL: https://lab1-helsinki.api.mks2508.systems
# 3. Provider: MiniMax
# 4. Channels: OFF (UC2 es sesión simple, sin channels)
# 5. Click "New Session"

03

F2 — Crear sesión

3 min

Crear sesión y verificar output

Seleccionar provider 'MiniMax' en el dropdown de la UI La UI envía providerMode: 'minimax' en el POST
Toggle Channels = OFF (para UC2 no necesitamos channels) Sesión básica sin a2a
Click 'New Session' → aparece una nueva sesión en la lista El POST /api/sessions devolvió 200 + sessionId
La sesión muestra estado 'running' y un chat input El cli-launcher spawneó Claude Code y el WS bridge está activo
Escribir 'di hola' en el chat → aparece respuesta en la UI Ciclo completo: UI → gateway-server → Claude CLI → output → UI

Body del POST /api/sessions

Qué envía gateway-web al workspace

# POST https://lab1-helsinki.api.mks2508.systems/api/sessions
$ curl -s -X POST https://lab1-helsinki.api.mks2508.systems/api/sessions \
    -H "Content-Type: application/json" \
    -d '{
      "providerMode": "minimax",
      "cwd": "/workspace",
      "channels": false
    }' | jq .
→ {
→   "session": {
→     "sessionId": "a1b2c3d4-...",
→     "state": "running",
→     "model": "claude-sonnet-4-20250514",
→     "cwd": "/workspace",
→     "createdAt": "2026-06-20T..."
→   }
→ }

04

F3 — Verificar en el workspace

3 min

SSH al workspace para verificar procesos

ssh developer@lab1-helsinki.api.mks2508.systems → acceso Acceso SSH al workspace container
ps aux | grep claude → proceso Claude Code corriendo El cli-launcher spawneó un proceso Claude CLI
ls ~/.mks-harness/sessions/ → directorio de la sesión El sessionConfigDir fue creado con .claude.json aislado
cat ~/.mks-harness/sessions/<sid>/.claude.json → mcpServers config Configuración de sesión persistida
tail -f /var/log/supervisor/gateway.log → logs del cli-launcher El log muestra Spawning CLI for session <sid>

Posibles fallos UC2

Fallo de conexión: si gateway-web no puede conectar al workspace, verificar CORS (el gateway-server debe aceptar el origen de gateway-web) y que el workspace es accesible desde el navegador
Sesión no arranca: revisar supervisorctl status gateway en el workspace. Si el gateway-server no está corriendo, el POST /api/sessions fallará
Sin output en UI: el WS bridge entre gateway-web y gateway-server puede estar desconectado. Verificar la consola del navegador (Network → WS)
Error de provider: si el providerMode no es reconocido, el cli-launcher usará el default. Verificar que el provider dir existe en el workspace

05

F4 — Verificación final

Debe pasar3 checks

gateway-web carga y se conecta al workspace WS establecido con gateway-server
POST /api/sessions → 200 + sessionId Sesión creada correctamente
Respuesta del modelo visible en la UI Output NDJSON bridge funciona

Puede fallar (esperable)1 check

La UI muestra error si el workspace no tiene el provider configurado Verificar API keys en el workspace container

Si falla → crítico1 check

El workspace no acepta conexiones desde el navegador Revisar CORS, firewall, health del gateway-server