01-overview.md
Visión general · NetBench
NetBench es un laboratorio de redes en el navegador para quien empieza como administrador de redes y sistemas. Se dibuja una topología con cables y Wi-Fi, se configuran direcciones IPv4 e IPv6, se escribe en la terminal de cada equipo y se ve cada paquete con el motivo exacto por el que llegó o se perdió. Un instructor, Eve (el botón Agent de la interfaz), explica, arregla y construye laboratorios leyendo el mismo simulador.
No es Packet Tracer ni un catálogo de CCIE. Ocho tipos de equipo, tres perfiles de switch, doble pila y caídas con su motivo.
Esa es la regla del proyecto: un catálogo pequeño que funciona de verdad antes que uno grande que finge. Lo que no está (BGP, MPLS, VXLAN, 802.1X) se rechaza con un error claro, y lo que se aproxima (la criptografía de SSH, la radio del Wi-Fi, OSPF punto a punto) lleva la etiqueta simulado.
Tiene cuatro partes:
- El motor (
packages/engine): un simulador de eventos discretos en TypeScript puro. Reenvía tramas y paquetes, ejecuta la terminal de cada equipo y comprueba los objetivos de cada laboratorio. - La API (
apps/api): NestJS. Mantiene un motor por sesión abierta en un proceso de Node que no se apaga, y guarda cuentas y laboratorios en Postgres. - La web (
apps/web): Angular 22 sin Zone.js y Tailwind 4. El lienzo, la terminal, el inspector de paquetes y el cajón de Eve. - Eve (
apps/eve-agent): un agente de eve desplegado en Vercel, con herramientas que llaman a la API.
Qué lo hace distinto
El motor es la única fuente de verdad. La web nunca decide si un paquete llega: pinta lo que el motor dice. Eve tampoco: sus herramientas leen el estado, la ruta de un paquete y el resultado de las comprobaciones del mismo motor, así que no puede inventarse una topología ni dar por buena una red rota.
| Lo decide | Qué |
|---|---|
| El motor | Reenvío, ARP y NDP, VLAN, rutas, OSPF, DHCP, NAT, cortafuegos, asociación Wi-Fi, el motivo de cada caída |
| La web | Cómo se dibuja, qué se enseña según el modo, los atajos que escriben comandos reales en la terminal |
| Eve | Explicar y proponer, siempre a partir de lo que devuelven sus herramientas |
| La persona | Qué cambia en su red; los cambios de Eve pasan por un token que emite la API |
Enlaces
- Demo: netbench-www-criscode2022s-projects.vercel.app
- API: netbench-api.cristiancode.dev/api/health
- GitHub: Criscode2022/netbench
Stack
| Capa | Tecnología |
|---|---|
| Motor | TypeScript 5.9 sin dependencias de ejecución, módulos ES |
| API | NestJS 11 sobre Express, ws para el socket local, jsonwebtoken, bcryptjs, pg |
| Web | Angular 22.1, signals y sin Zone.js, Tailwind CSS 4.3, TypeScript 6.0 |
| Instructor | eve 0.47 en Vercel, AI Gateway con una cadena de modelos de varios proveedores |
| Datos | Postgres en Neon: usuarios y laboratorios guardados |
| Pruebas | Vitest 3 y Supertest; evals de eve |
| Despliegue | Web y Eve en Vercel; la API en un Mac propio, a través de una plataforma de hosting propia y Cloudflare |
En cifras
| Tipos de equipo | 8, y el switch con 3 perfiles |
| Laboratorios incluidos | 48: 22 modelos que funcionan y 26 ejercicios rotos con solución oficial |
| Idiomas de la interfaz | 5: inglés, español, francés, alemán y portugués |
| Herramientas de Eve | 10, con 3 subagentes y 7 habilidades |
| Tests del motor | 64 |
| Tests de la API | 37 |
| Evals de Eve | 7 |
| Código | unas 7.700 líneas en el motor, 1.200 en la API, 14.600 en la web |
Por dónde seguir
- Producto y features: qué puede hacer quien lo usa.
- Arquitectura y El motor: cómo está hecho.
- Eve: el instructor y sus límites.
- Laboratorios: el temario.
- Puesta en marcha y despliegue: cómo arrancarlo.
02-product.md
Producto y features
Para quién
Para quien empieza en redes y sistemas: sabe qué es una IP, ha oído hablar de VLAN y de OSPF, y necesita equivocarse muchas veces en un sitio donde equivocarse no rompe nada. El objetivo no es memorizar comandos, es entender por qué un paquete no llega.
Un recorrido
- Se abre la web y arranca el primer laboratorio, First IPv4 ping with DHCP, sin cuenta. Una tarjeta dice el objetivo y una lista enseña lo que hay que conseguir: «PC1 pings 10.0.0.20».
- Se pulsa sobre PC1. El inspector enseña sus puertos, su dirección, su puerta de enlace y unas pistas que salen del estado real del motor.
- En la terminal de PC1 se escribe
ping -c 3 10.0.0.20. La respuesta es la de Linux, con los tiempos del simulador, y el panel de paquetes se llena: DHCP, ARP, el eco ICMP y la respuesta, salto a salto. - Check ejecuta las comprobaciones del laboratorio. Si pasan, propone el siguiente. Si no, dice cuál falló y por qué, con la frase que devolvió el motor.
- En un ejercicio roto, Ask Agent why abre a Eve con el contexto de la red, y Eve lee la ruta del paquete antes de proponer el arreglo más pequeño.
Equipos y cables
| Equipo | Puertos | Terminal |
|---|---|---|
| Workstation (PC) | eth0, wlan0 | Linux |
| Server | eth0, eth1 | Linux |
| Switch | Gi0/1 a Gi0/8 | Ninguna (no gestionable) o tipo Cisco |
| Router | Gi0/0 a Gi0/3 | Tipo Cisco |
| Firewall | eth0 a eth3 | Linux con nft |
| Access Point | Gi0/1, wlan0 | Tipo Cisco |
| WLC | Gi0/1 | Tipo Cisco |
| Cloud (Internet) | eth0 | Un extremo que contesta a 8.8.8.8 |
El switch es un único tipo con tres perfiles: no gestionable (aprende MAC y reenvía, sin CLI), gestionable L2 (VLAN de acceso y troncales, VLAN nativa, RSTP-lite, SVI de gestión) y multicapa (lo anterior más ip routing, puertos enrutados, rutas estáticas, pools DHCP y ip helper-address). Se cambia desde la paleta, con una pulsación larga en el móvil o desde los detalles de un switch ya colocado, y los cables se quedan.
Los cables son Ethernet (auto-MDIX, siempre enlaza), directo, cruzado y fibra. Directo y cruzado siguen la regla de CCNA de equipos iguales y distintos. El cable equivocado se queda enchufado pero sin enlace, con el estado Wrong cable. La fibra necesita SFP, así que un PC no la acepta.
Modos de la interfaz
| Modo | Cuándo | Qué enseña |
|---|---|---|
| Simple | Por defecto | Ethernet entre equipos, solo los puertos usados, IPv4. Lo justo para el primer día |
| Advanced | Interruptor de la cabecera | Tipos de cable, la rejilla de puertos en cada tarjeta, IPv6, MAC y la configuración en ejecución |
| Focus | Escritorio, Shift+F | Solo el lienzo, con una barra flotante. Eve y los detalles se abren como paneles laterales sin salir del modo |
| Basic (móvil) | Teléfono, por defecto | Dos pestañas, Canvas y Agent (Eve). Botón + Add, y al tocar un equipo una hoja inferior con sus datos |
Herramientas para aprender
Todas leen el motor; ninguna predice el reenvío por su cuenta.
- Check con el motivo exacto de cada comprobación, «Next lab» al pasar y «Ask Agent why» al fallar. Los paquetes de la comprobación se repiten salto a salto sobre el lienzo.
- Pistas en el inspector, con arreglo de un clic: encender el puerto, cambiar el cable equivocado, añadir una IP o DHCP, poner o cambiar la puerta de enlace, unirse al Wi-Fi.
- Troubleshoot: toma la última caída de la ruta de un paquete y la traduce a capa, explicación, dónde mirar, comandos para verificar y un arreglo cuando lo hay.
- Reach: ping o traza desde un equipo, con la cadena de saltos; Watch la repite cada 5 segundos hasta que funciona.
- Inspector de paquetes: filtro, solo caídas, captura de un equipo, y «Show on canvas» para ver el camino.
- Puntos de control: hasta 12, guardados por laboratorio, con un diff de la configuración y restaurar.
- Deshacer y rehacer (40 pasos) los cambios del laboratorio.
- Editor de laboratorio: nombre, objetivo y comprobaciones de una copia propia.
- Informe en Markdown: equipos, direcciones, cables, comprobaciones y últimas caídas.
- Paleta de comandos (
Ctrl+K) y atajos de teclado (?). - Terminal con historial (↑/↓), autocompletado con Tab y comandos rápidos. Cada botón de la interfaz que cambia un equipo escribe los comandos reales en su terminal, para que se vea qué se hizo.
Guardar y compartir
- Sin cuenta: el laboratorio se guarda en el navegador y se recupera al recargar. Si la sesión del servidor sigue viva (menos de 12 horas), se vuelve a ella con sus tablas ARP y su terminal.
- Con cuenta (correo y contraseña): «Save a copy» y «My labs» guardan en Postgres.
- Enlace para compartir: el laboratorio entero va en la URL (
#lab=…), sin servidor. - JSON: copiar, descargar y subir, con el esquema de
packages/engine/schema/lab.schema.json.
Idiomas
La interfaz está en inglés, español, francés, alemán y portugués. La terminal y los mensajes del motor siguen en inglés, como en un equipo de verdad.
Lo que no hace
- No hay BGP, MPLS, VXLAN, 802.1X, NSSA ni enlaces virtuales de OSPF. Se rechazan en la terminal, en el constructor y en Eve.
- OSPF es solo área 0. STP es un RSTP-lite determinista, sin prioridades ni roles.
- El Wi-Fi es un BSS simplificado: SSID, canal, PSK y asociación, y después IP normal. No hay radio.
- SSH es TCP al puerto 22 más un login simulado; no hay criptografía.
- No hay cable de consola ni enlaces serie.
03-architecture.md
Arquitectura
Las piezas
Navegador (Angular) --REST, cada 1,5 s el estado--> API Nest --> Engine (uno por sesión)
|
Cajón de Eve --NDJSON--> Eve en Vercel --HTTP--> /api/eve/tools/*
|
Postgres (Neon): usuarios y laboratorios
| Pieza | Dónde corre | Por qué ahí |
|---|---|---|
| Web (Angular) | Vercel, estática | Son ficheros; un CDN basta |
| Eve | Vercel (eve deploy) | eve usa el AI Gateway de Vercel con OIDC, sin claves en el código |
| API + motor | Un proceso de Node en un Mac propio, publicado como netbench-api.cristiancode.dev | El motor guarda cada laboratorio en memoria y lo hace avanzar en el tiempo; no cabe en una función de 10 segundos |
| Postgres | Neon | Cuentas y laboratorios guardados |
El motor es la fuente de verdad
packages/engine no sabe nada de HTTP ni de Angular. Expone una clase Engine con lo que hace falta para enseñar redes:
| Método | Qué hace |
|---|---|
exec(deviceId, line) | Ejecuta una línea en la terminal de un equipo y devuelve salida, prompt, error y los eventos de paquete que produjo |
getPath(src, dst, proto, family) | La ruta de un paquete salto a salto. Si no llega, el último evento es la caída con su motivo; nunca hay una caída silenciosa |
check() | Las comprobaciones del laboratorio: ping, SSH, asociación Wi-Fi, concesión DHCP, vecindad OSPF |
getState() | Equipos, interfaces con su par y su estado, enlaces y los últimos 80 paquetes |
toLab() | El laboratorio vivo como JSON, para guardarlo o compartirlo |
La API, la web y Eve usan esos mismos métodos. Por eso el motivo de una caída es idéntico en el inspector de paquetes, en Troubleshoot y en lo que lee Eve con get_path: hay un test que lo comprueba.
Una sesión
POST /api/sessionscon unlabIddel temario o un laboratorio entero. La API crea unEngine, ejecuta las líneas de arranque de cada equipo y devuelvesessionIdy el estado.- La web pinta el estado. Cada cambio del usuario (cable, equipo, mover) va por
POST /sessions/:id/edit; cada comando, porPOST /sessions/:id/cli. - Mientras la sesión está abierta, la web lee el estado cada 1,5 segundos y pasa al lienzo los paquetes que no ha visto. En local, en vez de eso, hay un WebSocket en
/wsque empuja el estado cada segundo. - La sesión vive en memoria. Si la API se reinicia, la siguiente llamada devuelve
404 session not found, y la web reabre el último laboratorio guardado con la mismalabKey, sin que el usuario haga nada.
Por qué en producción no hay socket
La API se publica a través de una plataforma de hosting propia: Cloudflare recibe la petición y la manda por Tailscale Funnel a un proceso del Mac. Ese camino es HTTP y no deja pasar WebSockets. La web lo sabe por configuración (WS es null fuera de localhost) y lee el estado en vez de esperar a que se lo empujen. El cliente envía el comando por HTTP igualmente cuando el socket no está, así que el resultado es el mismo con una petición más cada 1,5 segundos. La API deja que el navegador guarde el preflight de CORS 10 minutos, para que cada lectura sea una sola petición. Ver Decisiones.
Eve dentro de la arquitectura
Eve no habla con el motor directamente. Sus herramientas son llamadas HTTP a /api/eve/tools/*, que resuelven la sesión del navegador por su labKey. Las que cambian algo (apply_device_config, apply_lab_patch, build_lab) necesitan un confirmToken que la API emite con POST /api/eve/tools/confirm y que solo vale una vez, más una idempotencyKey para que un reintento no aplique dos veces el mismo cambio. Ver Eve.
Qué pasa si algo cae
| Cae | Qué sigue funcionando |
|---|---|
| La API | La web carga y enseña el último laboratorio guardado en el navegador; los comandos fallan con «Cannot reach the lab API» y el pie lo dice |
| Postgres | Invitados y laboratorios en memoria; iniciar sesión y «My labs» fallan |
| Eve o el AI Gateway | Todo menos el cajón de Eve, que enseña el error y reintenta |
| Ese Mac | La web y Eve; la API no, porque vive en él |
04-monorepo.md
Monorepo
Un repositorio con workspaces de npm. Node 24 (eve no arranca con menos) y un npm install en la raíz.
netbench/
packages/engine/ @netbench/engine: el simulador (Vitest)
apps/api/ @netbench/api: NestJS, REST y WebSocket (Vitest + Supertest)
apps/web/ @netbench/web: Angular 22 + Tailwind 4
apps/eve-agent/ @netbench/eve-agent: el agente de eve
docs/ esta documentación
sql/schema.sql las tablas de Postgres
HANDOFF.md el traspaso para otro agente de código
packages/engine
TypeScript puro, sin dependencias de ejecución. package.json apunta a src/index.ts, así que la API lo importa sin compilar (con tsx) y los tests también.
| Fichero | Líneas | Qué tiene |
|---|---|---|
engine.ts | 3.356 | El reenvío por eventos discretos, la CLI, ping, ruta y comprobaciones |
labs-models.ts, labs-exercises.ts, labs-shared.ts, labs.ts | Los 48 laboratorios y su registro | |
build.ts | labFromSpec: de una frase en inglés a una topología | |
patch.ts, validate.ts | Validar y aplicar un LabPatch; validar un laboratorio entero | |
types.ts | Tipos de equipo, puertos, cables, laboratorio, comprobaciones, paquetes | |
devices.ts, cables.ts, ip.ts, commands.ts | Crear equipos, reglas de cables, utilidades IPv4/IPv6, la ayuda de cada tipo | |
schema/lab.schema.json | El esquema JSON de un laboratorio |
apps/api
| Fichero | Qué tiene |
|---|---|
main.ts | Arranque: base de datos, aplicación, socket, PORT y HOST |
create-app.ts | CORS, el proxy /eve opcional y el WebSocket /ws |
http.ts | Los controladores: salud, autenticación, laboratorios, sesiones, herramientas de Eve, comandos |
sim.service.ts | Las sesiones en memoria, el límite de llamadas, los confirmToken y la repetición idempotente |
store.ts, db.ts | Usuarios y laboratorios: un mapa en memoria delante de Postgres |
rate-limit.filter.ts | El 429 con Retry-After |
apps/web
Angular con componentes standalone y plantillas en ficheros aparte. 16 ficheros de TypeScript y 10 plantillas.
| Fichero | Qué tiene |
|---|---|
workspace.ts, workspace.html | El lienzo, los modos, el inspector, Check, Reach, pistas, deshacer, el arranque y la recuperación de sesión |
api.ts | El cliente HTTP, el sondeo del estado o el socket, el guardado de invitado |
eve-client.ts | La sesión de Eve, el stream NDJSON, las preguntas y aprobaciones |
terminal.ts, packets.ts, lab-picker.ts, mine-picker.ts, cheat-sheet.ts, toasts.ts | Los componentes del muelle y la cabecera |
lab-history.ts, lab-library.ts | Deshacer y rehacer; los laboratorios propios |
i18n/ | Un diccionario por idioma; el tipo de las claves sale del inglés |
vercel.json | Salida dist/web/browser y la reescritura de la SPA |
apps/eve-agent
| Carpeta | Qué tiene |
|---|---|
agent/agent.ts, agent/lib/model.ts | El agente y su cadena de modelos |
agent/tools/ | Las 10 herramientas |
agent/subagents/ | explainer, fixer, builder |
agent/skills/ | 7 habilidades en Markdown |
agent/lib/ | Aprobaciones, guardas de entrada, el cliente de la API, el esquema de laboratorio |
evals/ | 7 evals |
Scripts de la raíz
| Script | Qué hace |
|---|---|
npm run dev | API en :3001, web en :4200 y Eve en :4010 a la vez |
npm test | Tests del motor y de la API |
npm run deploy:eve | Despliega Eve en Vercel |
05-api.md
API
NestJS 11 con el prefijo global /api. Producción: https://netbench-api.cristiancode.dev/api. En local: http://127.0.0.1:3001/api, y la web de desarrollo la alcanza en /api por el proxy de Angular.
CORS acepta cualquier origen (origin: true), expone Retry-After y deja guardar el preflight 10 minutos. El cuerpo es JSON.
Salud
| Ruta | Respuesta |
|---|---|
GET /health | ok, version (el commit desplegado), uptimeSec, eveTools: true, idempotency: true |
version y eveTools existen para que Eve distinga una API caída de una API antigua: una versión sin eveTools no tiene las rutas que Eve necesita.
Cuentas
| Ruta | Qué hace |
|---|---|
POST /auth/register | { email, password } → { token, user } |
POST /auth/login | Igual, con una cuenta existente |
POST /auth/guest | Un token de invitado, sin guardar nada |
GET /auth/me | El usuario del token |
Ver Cuentas e invitados.
Laboratorios
| Ruta | Qué hace |
|---|---|
GET /labs/builtin | El temario: id, nombre, objetivo, tipo, nivel, temas, número de pistas y de comprobaciones. Sin topología ni solución |
GET /labs/builtin/:id | Un laboratorio del temario, sin la solución |
GET /labs/builtin/:id/solution | Pistas y parche oficial de un ejercicio (un modelo responde 404) |
GET /labs/builtin/:id/exercises | Los ejercicios de un modelo |
GET /labs, POST /labs, GET /labs/:id, PUT /labs/:id, DELETE /labs/:id | Los laboratorios guardados de la cuenta; un invitado recibe 401 |
Sesiones
Una sesión es un Engine vivo en la memoria de la API. Se crea con POST /sessions y { labId } o { lab }, más una labKey opcional del navegador.
| Ruta | Qué hace |
|---|---|
GET /sessions/:id/state | El estado: equipos, interfaces, enlaces y los últimos 80 paquetes |
POST /sessions/:id/cli | { deviceId, line } → salida, prompt, error, eventos y estado |
POST /sessions/:id/check | Las comprobaciones del laboratorio con su motivo |
POST /sessions/:id/ping, /path | Un ping o la ruta de un paquete |
POST /sessions/:id/cancel | Corta un ping en curso (^C) |
POST /sessions/:id/edit | { patch?, move? }: equipos, cables y posiciones. Es el usuario, así que no pide token |
POST /sessions/:id/solution | Aplica la solución oficial de un ejercicio |
POST /sessions/:id/save | El laboratorio vivo como JSON, para el navegador o la cuenta |
POST /sessions/:id/confirm | Emite un confirmToken para un propósito |
POST /sessions/:id/patch, /config, /build | Cambios de Eve; exigen confirmToken (403 sin él) |
POST /sessions/:id/highlight | Resalta equipos en el lienzo |
Una sesión que no existe es 404 session not found, nunca un 500. La web lo usa para reabrir el laboratorio tras un reinicio.
Herramientas de Eve
POST /eve/tools/<nombre>, con labId que puede ser el id de la sesión, el del laboratorio o la labKey del navegador (gana la sesión más reciente).
| Herramienta | Cambia algo | Qué hace |
|---|---|---|
confirm | Emite el confirmToken de un propósito | |
get_lab_state | El estado de la sesión | |
get_device | Un equipo con su configuración | |
get_path | La ruta de un paquete, con la caída y su motivo | |
run_check | Las comprobaciones | |
list_commands | Los comandos de un tipo de equipo y perfil | |
highlight_devices | Resalta equipos en el lienzo | |
apply_device_config | ✔ | Ejecuta comandos en un equipo |
apply_lab_patch | ✔ | Aplica un LabPatch |
build_lab | ✔ | Construye un laboratorio desde una frase o un JSON entero |
Las tres que cambian algo aceptan idempotencyKey (en el cuerpo o en la cabecera Idempotency-Key). Si llega repetida en 10 minutos, la API devuelve la primera respuesta con replayed: true en vez de aplicar dos veces; la misma clave con otro propósito es 409.
Comandos
GET /commands/:kind devuelve la lista de comandos de un tipo de equipo, la misma que enseña la chuleta de la web y la que usa Eve. Ver Comandos.
Límites
- 120 comandos o llamadas de herramienta por minuto y sesión (
NB_RATE_LIMIT). Al pasarse: 429 conRetry-AfteryretryAfteren el cuerpo. Leer el estado yconfirmno cuentan. - Un laboratorio de Eve tiene como mucho 40 equipos y 80 cables.
- BGP, MPLS, VXLAN y 802.1X en una frase del constructor son 400.
WebSocket (solo en local)
GET /ws?sessionId=…, fuera de /api. El servidor empuja { type: 'state' } cada segundo y responde a { type: 'cli', deviceId, line } y { type: 'cancel' }. Una sesión desconocida se cierra con el código 4404. En producción no se usa: ver Arquitectura.
06-auth.md
Cuentas e invitados
Sin cuenta por defecto
Quien abre la web no tiene que registrarse. La web pide POST /api/auth/guest y recibe un token de invitado. Con él puede abrir sesiones, escribir comandos y usar a Eve. Lo que no puede es guardar en el servidor: el laboratorio se guarda en el navegador (localStorage.nb_guest_lab) y se recupera al recargar.
Con cuenta
- Registro y entrada con correo y contraseña. La contraseña se guarda con bcrypt (coste 10); el correo, en minúsculas y único.
- Token: un JWT firmado con
JWT_SECRET, válido 7 días, consub,emailyguest. La web lo guarda enlocalStorage.nb_tokeny lo descarta al arrancar si caducó. - Al entrar, el laboratorio de invitado pasa a la cuenta con «Save a copy». «My labs» lista los guardados.
Qué comprueba la API
| Ruta | Sin token | Invitado | Cuenta |
|---|---|---|---|
| Temario, salud, comandos | ✔ | ✔ | ✔ |
| Sesiones y herramientas de Eve | ✔ | ✔ | ✔ |
GET /auth/me | 401 | ✔ | ✔ |
Laboratorios guardados (/labs) | 401 | 401 | ✔, solo los suyos |
Una sesión se identifica por un UUID aleatorio, y la labKey del navegador también es aleatoria. No hay más control sobre quién usa una sesión: lo que hay en ella es un laboratorio, no datos de nadie.
Los cambios de Eve
Eve no tiene cuenta. Sus cambios necesitan un confirmToken de un solo uso que la API emite para un propósito (apply_device_config, apply_lab_patch o build_lab). Eve lo pide justo antes de cada cambio y nunca acepta uno que venga del modelo. Ver Eve.
Lo que se quitó
Había un inicio de sesión con enlace mágico, POST /auth/magic, pensado para mandar un enlace por correo. Como nunca se configuró el envío, la ruta devolvía el token en la respuesta: cualquiera que supiera el correo de una cuenta podía entrar en ella. Nada lo usaba (ni la web, ni Eve, ni los tests), así que se quitó el 18 de noviembre de 2026. La tabla magic_tokens que ya existía en Neon se dejó como estaba, sin uso.
Secretos
| Variable | Dónde | Sin ella |
|---|---|---|
JWT_SECRET | Las variables del proyecto en la plataforma de hosting | La API firma con un valor de desarrollo; nunca en producción |
DATABASE_URL | Igual | Usuarios y laboratorios solo en memoria |
Ninguno está en el repositorio. El .env.example lleva valores de ejemplo.
07-data-model.md
Modelo de datos
Hay tres sitios con datos, y solo uno es una base de datos.
| Dónde | Qué | Cuánto dura |
|---|---|---|
| La memoria de la API | Las sesiones: un Engine por laboratorio abierto, con sus tablas ARP, MAC, rutas y paquetes | Hasta que la API se reinicia |
| Postgres (Neon) | Usuarios y laboratorios guardados | Siempre |
| El navegador | El laboratorio de invitado, la sesión abierta, preferencias, puntos de control | Lo que dure ese navegador |
Postgres
sql/schema.sql. La API lo aplica al arrancar si tiene DATABASE_URL (CREATE TABLE IF NOT EXISTS, así que no borra nada).
users (id TEXT PRIMARY KEY, email TEXT UNIQUE NOT NULL, password_hash TEXT,
guest BOOLEAN NOT NULL DEFAULT FALSE, created_at TIMESTAMPTZ NOT NULL DEFAULT now())
labs (id TEXT PRIMARY KEY, user_id TEXT REFERENCES users(id) ON DELETE CASCADE,
name TEXT NOT NULL, json JSONB NOT NULL, startup JSONB, running JSONB,
activity JSONB NOT NULL DEFAULT '[]', updated_at TIMESTAMPTZ NOT NULL DEFAULT now())
store.ts tiene un mapa en memoria delante de cada tabla, pero no se fía de él: al iniciar sesión, al listar y al abrir un laboratorio hace SELECT, y espera a que cada escritura termine. Así, tras un reinicio, una cuenta y sus laboratorios siguen ahí. Hay un test que vacía la memoria y comprueba que todo se lee de la base de datos.
Neon conserva además una tabla magic_tokens del inicio de sesión que se quitó. No se usa; ver Cuentas e invitados.
Un laboratorio
Un laboratorio es un JSON con schemaVersion: 1, validado por validateLab y descrito en packages/engine/schema/lab.schema.json.
| Campo | Qué es |
|---|---|
id, name, goal, description | Identidad y texto. Los del temario son lab-*, model-* y ex-*; las copias propias, nb-* |
kind, level, topics | model o exercise; beginner a expert; etiquetas como vlan u ospf |
modelId, solution | Solo en ejercicios: el modelo que funciona, y las pistas y el parche que lo arreglan |
devices | kind, name, x, y, switchProfile en los switches, las líneas startup que lo configuran al arrancar y las post, que corren cuando todos arrancaron (unirse al Wi-Fi, dhclient) |
links | Los dos extremos (PC1:eth0) y el tipo de cable |
checks | Lo que tiene que funcionar: ping, ssh, wifi-associated, dhcp-bound, ospf-full |
differsNote | En qué se diferencia del equipo real |
La configuración no se guarda como estado: se guarda como comandos. Un equipo es su lista de líneas de arranque, y el motor las ejecuta al abrir. Así un laboratorio guardado se puede leer, comparar y reproducir, y un parche de Eve es lo mismo que lo que escribiría una persona.
Un parche
LabPatch es el cambio que aplican Eve y la solución de un ejercicio:
{
addDevices?: { type, name, switchProfile?, x?, y? }[];
removeDeviceIds?: string[];
addLinks?: { a: 'PC1:eth0', b: 'SW1:Gi0/1', cable?: 'ethernet' | 'straight' | 'crossover' | 'fiber' }[];
removeLinks?: string[];
configs?: { device: string; commands: string[] }[];
setSwitchProfiles?: { device: string; switchProfile: 'unmanaged' | 'managed-l2' | 'multilayer' }[];
}
Un tipo de equipo desconocido, un puerto que no existe o un puerto ya ocupado se rechazan antes de tocar nada.
Un paquete
Cada evento del motor lleva id, tiempo, origen y destino (equipo e interfaz), MAC, VLAN o SSID, IP, protocolo, puertos, TTL, el motivo y, si se perdió, drop: true. Los que salen de una aproximación llevan simulated: true. El estado guarda los últimos 80.
En el navegador
| Clave | Qué guarda |
|---|---|
nb_token | El JWT |
nb_guest_lab | El laboratorio de invitado ({ v: 1, at, lab }) |
nb_autosave | { id, sessionId, at }: la sesión a la que volver si tiene menos de 12 horas |
nb_my_labs | Los laboratorios propios de este navegador |
nb_passed | Los laboratorios cuyo Check pasó |
nb_ckpt | Los puntos de control (12 como mucho) |
nb_basic, nb_advanced, nb_focus | Los modos |
nb_eve_open, nb_eve_auto | El cajón de Eve abierto y la aprobación automática |
nb_locale | El idioma |
nb_view, nb_dock_h, nb_welcome | Opciones de vista, altura del muelle, la bienvenida vista |
08-deploy.md
Puesta en marcha y despliegue
En local
Node 24.
cp .env.example .env # JWT_SECRET; DATABASE_URL es opcional
npm install
npm test # motor y API
npm run login:vercel # una vez: la misma cuenta de Vercel que Eve en producción
npm run link:eve # una vez: escribe el OIDC del AI Gateway en apps/eve-agent/.env.local
npm run dev # API :3001, web :4200, Eve :4010
- Web: http://localhost:4200. En localhost usa
/apiy el WebSocket por el proxy de Angular (proxy.conf.json). - API: http://localhost:3001/api/health.
- Eve local usa el mismo AI Gateway que producción y llama a la API de
:3001. El token OIDC caduca en unas 24 horas:npm run link:eveotra vez. - Sin
DATABASE_URL, cuentas y laboratorios viven en memoria.
Producción
| Pieza | Dónde | Cómo se despliega |
|---|---|---|
| Web | Vercel, proyecto netbench-www | Cada push a main |
| Eve | Vercel, proyecto netbench-eve | Cada push a main; a mano con npm run deploy:eve |
| API | Una plataforma de hosting propia, en un Mac, proyecto netbench-api, publicado en https://netbench-api.cristiancode.dev | Cada push a main |
| Base de datos | Neon, proyecto netbench | sql/schema.sql, aplicado por la API al arrancar |
La API en la plataforma de hosting
La plataforma clona el repositorio, instala, pasa los tests y deja el proceso corriendo en un puerto local. Cloudflare Pages (hp-netbench-api.pages.dev) recibe las peticiones del dominio y las manda por Tailscale Funnel al Mac.
| Ajuste | Valor |
|---|---|
| Rama | main, despliegue automático |
| Tipo | backend, servido por Cloudflare |
| Node | 24 |
| Instalación | npm ci --no-audit --no-fund --workspace @netbench/engine --workspace @netbench/api --include-workspace-root |
| Build | npm test -w @netbench/engine && npm test -w @netbench/api |
| Arranque | npm run start -w @netbench/api |
| Variables (secretas) | DATABASE_URL, JWT_SECRET |
- El build son los tests. La API no se compila (corre con
tsx), así que el paso de build es la puerta: si un test falla, ese commit no se despliega y sigue sirviendo el anterior. - Solo se instalan el motor y la API, no Angular ni eve.
- La plataforma pone
PORTyHOST=127.0.0.1, y la API escucha ahí; en un contenedor, sinHOST, escucha en0.0.0.0. /api/healthdevuelve el commit desplegado comoversion(deHOSTING_COMMIT_SHA).- Sin WebSockets por ese camino: la web lee el estado por HTTP. Ver Arquitectura.
Comprobar un despliegue
curl -s https://netbench-api.cristiancode.dev/api/health
# {"ok":true,…,"version":"<commit de 12 caracteres>","eveTools":true,"idempotency":true}
curl -s https://netbench-eve-criscode2022s-projects.vercel.app/eve/v1/health
# {"ok":true,"status":"ready",…}
Después, en https://netbench-www-criscode2022s-projects.vercel.app/: el pie dice Connected, un ping desde PC1 en el primer laboratorio responde y Check pasa.
Con Docker, en cualquier otro sitio
apps/api/Dockerfile (contexto: la raíz del repositorio) construye la API sobre node:24-slim. start.sh arranca también eve en 127.0.0.1:4010 detrás de /eve, aunque la web usa siempre el Eve de Vercel. Variables: PORT, JWT_SECRET, DATABASE_URL. apps/web/Dockerfile sirve la web con nginx.
Historia del despliegue
- Septiembre de 2026: la API vivía en Railway, en un plan de prueba, y Railway no se enteraba de los pushes (la app de GitHub había perdido acceso), así que cada despliegue era una llamada a mano a su API.
- Noviembre de 2026: el servicio de Railway ya no existía («Application not found») y la demo se quedó sin API. El 18 de noviembre la API pasó a una plataforma de hosting propia, en un Mac, con despliegue en cada push, y la web pasó a leer el estado por HTTP.
09-decisions.md
Decisiones
Pocos equipos, y que funcionen
Un simulador para aprender no gana por tener más protocolos, gana por no mentir. NetBench tiene ocho tipos de equipo y ningún protocolo de los que solo se ven en una certificación avanzada. Lo que falta se rechaza con un error, en la terminal, en el constructor y en Eve, en vez de aceptarse a medias. Lo que se aproxima lo dice: cada evento que sale de una aproximación lleva simulated y la interfaz lo enseña como tal.
El coste es que alguien que busque BGP se va. A cambio, lo que hay se puede creer.
El motor decide, la interfaz pinta
La web podría haber calculado si dos equipos se ven: tiene la topología. No lo hace. Todo lo que dice si algo funciona sale del motor: el resultado de un ping, la ruta, el motivo de una caída, las pistas del inspector. Si la web adivinara, en algún momento diría «funciona» donde el motor dice que no, y el alumno aprendería lo contrario de lo que pasa.
Las pistas siguen la misma regla: leen hechos del motor (un puerto apagado, un cable equivocado, una dirección fuera de la subred) y nunca predicen el reenvío.
Cada botón escribe un comando
Añadir una IP, poner la puerta de enlace o encender un puerto desde el inspector no cambia el estado por detrás: escribe en la terminal de ese equipo los comandos que haría una persona (ip addr add, ip link set up, o enable, conf t, interface, no shutdown). Así la interfaz enseña el comando en vez de esconderlo, y lo guardado es siempre una lista de comandos que se puede leer.
El motor en un proceso que no se apaga
El motor guarda cada laboratorio en memoria (tablas ARP, MAC, vecinos OSPF, concesiones DHCP) y lo hace avanzar en el tiempo. Una función sin servidor que vive 10 segundos y no recuerda nada entre llamadas lo obligaría a reconstruir la red en cada comando. Por eso la API es un proceso de Node de larga vida, y la web y Eve van aparte en Vercel.
Eve no puede cambiar nada sin token
Eve es un modelo de lenguaje, y un modelo puede equivocarse o ser engañado. Sus herramientas de lectura son libres; las que cambian la red necesitan un confirmToken que emite la API, de un solo uso y para un propósito. Eve lo pide justo antes de cada cambio y nunca acepta uno que diga el modelo. Por defecto la aprobación es automática, para que la demo sea fluida; con EVE_APPROVAL=always o el interruptor del cajón, cada cambio espera a que la persona lo apruebe.
Modelos de varios proveedores
La cadena de modelos de Eve mezcla proveedores a propósito: si uno cae, el siguiente no cae por la misma razón. El AI Gateway prueba la cadena dentro de una llamada, y un hook de eve avanza de modelo entre llamadas y lo recuerda por sesión. Ver Eve.
Modelos y ejercicios por pares
Cada concepto tiene un laboratorio que funciona (modelo) y uno o más rotos (ejercicios) que apuntan a él. El modelo enseña cómo es; el ejercicio, cómo se rompe. Cada ejercicio trae pistas progresivas y un parche oficial, y un test comprueba que el modelo pasa, que el ejercicio falla y que el parche lo arregla. Ver Laboratorios.
Sin cuenta para empezar
Pedir registro antes de tocar nada echa a la mitad de la gente. El invitado tiene todo menos guardar en el servidor, y su laboratorio vive en el navegador.
La API en un Mac propio, sin WebSocket
Cuando Railway dejó de servir la API, había tres caminos: pagar Railway, rehacer el motor para que corriera en el navegador, o publicar la API desde una plataforma de hosting propia, en un Mac, que ya publica otros servidores en *.cristiancode.dev. Se eligió la última: no cuesta nada, despliega en cada push y pasa los tests antes de cada despliegue.
Ese camino pasa por Cloudflare y Tailscale Funnel y no deja pasar WebSockets. En vez de añadirlos a la plataforma, la web lee el estado por HTTP cada 1,5 segundos cuando no hay socket. Es más robusto en general (un proxy de empresa también corta WebSockets), el cliente ya mandaba los comandos por HTTP cuando el socket no estaba, y la lectura del estado no cuenta para el límite de llamadas. El precio es una petición por segundo y medio mientras la pestaña está visible, y que la API depende de que el Mac esté encendido.
La sesión vive en memoria
Guardar cada sesión en la base de datos haría que un reinicio no se notara, pero cada comando escribiría. En vez de eso, la sesión está en memoria y la web guarda el laboratorio en el navegador cada vez que cambia. Si la API se reinicia, la web reabre el laboratorio desde ahí con la misma labKey, y Eve sigue encontrándolo.
10-challenges-results.md
Retos y resultados
Retos
Los cables desaparecían en el móvil
El lienzo era un SVG del tamaño de la pantalla. En un teléfono de 390 px, al desplazar o hacer zoom, los cables que salían de ese rectángulo se recortaban y parecía que no estaban. El SVG ahora mide 4000 × 3000 o más y se mueve con la misma transformación que las tarjetas.
Un tercer PC no tenía enlace
El primer laboratorio solo encendía Gi0/1 y Gi0/2 del switch. Un PC nuevo en Gi0/3 quedaba en un puerto apagado y el ping fallaba sin que el alumno hubiera hecho nada mal. Ahora addLink enciende los dos extremos de un cable nuevo, como haría quien lo conecta.
Angular sin Zone.js y los gestos de Safari
Sin Zone.js, la vista se actualiza cuando cambia un signal desde Angular. Los gestos de pellizco de Safari (gesturechange) llegan por un addEventListener nativo, fuera de Angular, y el zoom cambiaba el signal sin repintar. Esos manejadores llaman a detectChanges() a mano.
ip route se leía como Linux
En un router, ip route 0.0.0.0 0.0.0.0 … empezaba igual que el ip de Linux y caía en el analizador equivocado. El analizador de Cisco va primero en los equipos tipo Cisco.
La API de Railway se quedó antigua
La app de GitHub de Railway perdió acceso al repositorio y los pushes dejaron de desplegar. Además, la imagen usaba Node 22 y eve exige 24, así que cada build fallaba. Eve llamaba a rutas que la API desplegada no tenía, y el error era un 404 confuso. Se arregló la imagen, se desplegó a mano, y Eve aprendió a distinguir una API caída de una API antigua (version y eveTools en /api/health, y la herramienta api_status).
Railway desapareció
En noviembre el servicio ya no existía y la demo se quedó sin API. Se movió a una plataforma de hosting propia. Como ese camino no deja pasar WebSockets, la web pasó a leer el estado por HTTP. Ver Decisiones.
Un inicio de sesión que regalaba cuentas
Al revisar la API antes de volver a publicarla apareció POST /auth/magic: como no había envío de correo, devolvía el token de inicio de sesión en la respuesta, y con el correo de una cuenta bastaba para entrar en ella. Nada lo usaba, así que se quitó. Ver Cuentas e invitados.
Un test que fallaba la mitad de las veces
«eve tools resolve a browser labKey to the newest session» abría dos sesiones seguidas con la misma labKey y esperaba la segunda. A veces las dos tenían el mismo milisegundo, y la API se quedaba con la primera: Eve habría leído un laboratorio que el navegador ya había cambiado. El empate ahora lo gana la sesión más nueva. Importaba más desde que los tests son la puerta del despliegue.
Resultados
- 48 laboratorios comprobados en cada ejecución de los tests: los 22 modelos pasan tal cual, los 26 ejercicios fallan tal cual y pasan con su parche, y aplicarlo dos veces no rompe nada.
- El mismo motivo en todas partes: un test comprueba que la caída de
get_pathes la misma que enseña el inspector de paquetes. - 101 tests (64 del motor, 37 de la API) en unos 3 segundos, y 7 evals de Eve.
tsc --noEmitpasa limpio en el motor y en la API. - Desplegado en cada push, con los tests como puerta, desde el 18 de noviembre de 2026.
- Cinco idiomas en la interfaz.
Pendiente
- La web no tiene tests automáticos; se prueba con el build de producción y a mano en el navegador, a 390 × 844 y a 1280 × 800.
- No hay CI propia: los tests corren en cada despliegue de la API, pero un commit que solo toca la web no los pasa. Ver Testing · CI.
- La API depende de que ese Mac esté encendido.
11-angular-skill.md
Angular
La web está en Angular 22.1 y TypeScript 6.0, sin Zone.js, con Tailwind CSS 4.3 y sin librería de componentes. Todo el estado va en signals: 68 signal y 41 computed en los 16 ficheros de TypeScript.
Qué usa de Angular
| API | Dónde | Para |
|---|---|---|
| Sin Zone.js | Toda la aplicación | Los signals avisan a la vista; nada parchea los eventos del navegador |
| Componentes standalone | Todos | Cada componente importa lo que usa |
Plantillas en ficheros aparte (templateUrl) | Todos | La lógica y el HTML se leen por separado |
ChangeDetectionStrategy.OnPush | 8 componentes | Solo se repintan cuando cambia una entrada o un signal |
signal, computed | Workspace, Api, EveClient, el resto | Estado local y derivado; basicMode(), focusMode(), showEve() deciden qué se pinta en cada modo |
input, output | nb-terminal, nb-packets, nb-lab-picker, nb-mine-picker, nb-cheat-sheet, nb-flag | Entradas como signals y eventos sin EventEmitter |
inject() | Servicios y componentes | Inyección sin constructor |
viewChild | nb-terminal | La salida y el campo de texto, sin decoradores |
@if, @for, @switch | Todas las plantillas | Control de flujo nativo; workspace.html tiene 249 bloques |
ng-template con NgTemplateOutlet | workspace.html | El mismo panel de equipo en el inspector de escritorio y en la hoja del móvil |
Pipe | i18n.ts, eve-markdown.ts | La traducción en las plantillas; la negrita y el código de las respuestas de Eve, escapadas antes de pasar por [innerHTML] |
provideRouter | app.config.ts | Una ruta, '' → Workspace |
Decisiones de la web
- Un componente grande a propósito.
Workspacelleva el lienzo, los modos y las herramientas de aprendizaje porque comparten casi todo el estado. Lo que se reutiliza o tiene vida propia (terminal, paquetes, selector de laboratorios, chuleta, avisos) son componentes aparte. - Una sola fuente para cada modo.
showEve(),showInspect(),showCanvas()yshowTerm()deciden qué se ve en escritorio, en móvil y en Focus. Un panel nuevo se añade ahí, no con un@ifsuelto. - El SVG del lienzo es grande (4000 × 3000 o más) y se mueve con la misma transformación que las tarjetas, para que un cable no se recorte en un teléfono.
- Gestos nativos. El pellizco de Safari llega por
addEventListenery llama adetectChanges(), porque sin Zone.js Angular no se entera solo. - La terminal no usa
ngModel. Escribe en un signal con[value]y(input), porquengModelaplica los cambios programáticos más tarde y rompía el autocompletado con Tab y el historial. - La cabecera cabe en 390 px. En un teléfono solo quedan el selector de laboratorio, Check y el menú (o el interruptor de Basic); Mis laboratorios, Guardar y Rehacer van en el menú ⋯ o solo en escritorio. Un botón de más ensancha la página entera a lo que mida la cabecera, y el móvil la encoge.
- Sin regex ni funciones flecha en plantillas: Angular no las acepta, así que van a métodos del componente.
- Tailwind 4 con tokens.
styles.cssdefine los colores (ink-*,brand-*,ok,warn,danger,eve) en@themey las clases de componente (.btn,.chip,.field,.led,.card).
Idiomas
i18n/ tiene un diccionario por idioma: inglés, español, francés, alemán y portugués, 758 claves cada uno. El tipo de las claves sale del inglés (MessageKey), así que un idioma al que le falta una clave no compila. El idioma elegido se guarda en localStorage.nb_locale.
Comunicación con la API
Api (api.ts) es un servicio con signals: state, sessionId, online y live. En localhost abre un WebSocket; en producción lee el estado cada 1,5 segundos y solo pasa al lienzo los paquetes nuevos. Si la API dice que una sesión ya no existe, json() la reabre desde el último laboratorio guardado y repite la petición.
Build
ng build con @angular/build. El paquete inicial pesa unos 960 kB (208 kB comprimido). Vercel publica dist/web/browser con una reescritura a index.html para la SPA.
17-engine.md
El motor
packages/engine es un simulador de eventos discretos en TypeScript puro. No hay tiempo real: cada trama es un evento con su instante, y el motor los procesa en orden hasta que la red se calma. Por eso un ping de tres paquetes responde al momento con tiempos verosímiles, y un test que manda cien tramas tarda milisegundos.
Qué simula
| Capa | Qué hay |
|---|---|
| L1 | Cables Ethernet (auto-MDIX), directo, cruzado y fibra, con las reglas de equipos iguales y distintos de CCNA. Un cable equivocado queda enchufado sin enlace (Wrong cable). Un puerto acepta un solo cable. Un puerto solo está arriba si está encendido y tiene par (o asociación de radio) |
| L2 | Aprendizaje de MAC por VLAN, puertos de acceso y troncales 802.1Q, VLAN nativa, lista de VLAN permitidas, RSTP-lite que bloquea un puerto si el grafo de una VLAN tiene un ciclo, y un aviso de bucle en switches no gestionables |
| L3 | ARP y NDP, rutas conectadas, estáticas y OSPFv2 área 0, ICMP e ICMPv6, TTL y hop limit, router-on-a-stick con subinterfaces, SVI y puertos enrutados en el switch multicapa |
| Servicios | DHCPv4 con pools, exclusiones y relay (ip helper-address), SLAAC con RA y RDNSS, DNS A y AAAA, SSH como TCP/22 más un login simulado |
| Seguridad | ACL estándar y de IPv6, el cortafuegos con zonas, políticas y nft, NAT con sobrecarga (PAT) hacia Internet |
| Wi-Fi | Un BSS simplificado: SSID, PSK, canal (solo cuenta que coincida) y asociación; después, un enlace de radio que lleva IP como un cable. El WLC es un CAPWAP ligero con salida local del tráfico |
Lo que se aproxima
Las aproximaciones llevan simulated: true en cada evento y la interfaz las marca:
- SSH: alcanza el puerto 22 por la ruta y abre una shell remota; no hay criptografía.
- Radio: no hay potencia, interferencias ni itinerancia. El canal solo decide si dos AP con el mismo SSID son el mismo BSS.
- OSPF: un solo área y redes punto a punto simplificadas. Los hellos están en el registro de paquetes, marcados como simulados.
- STP: RSTP-lite determinista, sin prioridades ni roles.
El motivo de cada caída
Ningún paquete desaparece en silencio. Cuando el motor no puede seguir, el último evento lleva drop: true y una frase que dice dónde y por qué:
| Ejemplo | Capa |
|---|---|
Interface Gi0/2 is administratively down | L1, puerto apagado |
No cable on eth0 | L1 |
Wrong cable (estado del puerto) | L1, directo donde iba cruzado o al revés |
VLAN mismatch on SW1 Gi0/2 | L2 |
No subinterface for VLAN 20 on R1 Gi0/0 | L2/L3, router-on-a-stick incompleto |
RSTP-lite blocking SW2 Gi0/3 | L2, puerto bloqueado por un ciclo |
ARP timeout for 10.0.1.254 at PC2 | L3, puerta de enlace que no existe |
No route to 10.9.9.10 on R2 | L3 |
TTL expired at R1 | L3 |
ACL drop: deny tcp 10.2.2.10 → 10.9.9.10 … | Seguridad |
not associated | Wi-Fi |
getPath sintetiza un evento de caída si la ruta se corta sin uno, para que nunca haya una respuesta vacía. La web (Troubleshoot) traduce esas frases a capa, explicación y comandos para verificar, y Eve las lee con get_path. Un test comprueba que el motivo es el mismo en el inspector y en get_path.
Los equipos se configuran con comandos
Un equipo no tiene un estado que se guarde: tiene una lista de líneas de arranque (startup) y otra que corre cuando todos arrancaron (post: unirse al Wi-Fi, dhclient). Abrir un laboratorio es ejecutarlas. Un parche de Eve, la solución de un ejercicio y un botón de la interfaz son, al final, comandos en la terminal de un equipo.
Los equipos tipo Cisco empiezan en modo usuario: hacen falta enable y configure terminal. Los puertos de un router o de un switch gestionable empiezan apagados hasta no shutdown, como en un equipo real; al cablear un puerto nuevo, el motor enciende los dos extremos.
El constructor
labFromSpec(spec) convierte una frase en inglés en un laboratorio. Es lo que usa build_lab cuando Eve no manda un JSON entero:
- «A dual-stack office with a switch, a router, an AP, a server and two PCs» da la plantilla de oficina.
- «Two VLANs, one router, wifi on VLAN 20, Linux server on VLAN 10, PC must ping the server via the router» cuenta un PC suelto, pone cada papel en su VLAN y añade la comprobación de ping.
- Hasta 12 PCs repartidos en varios switches con troncal; una oficina de 50 se recorta a lo que cabe en el lienzo y sigue haciendo ping.
- BGP, MPLS, VXLAN o 802.1X en la frase son un 400.
Comprobaciones
| Tipo | Pasa cuando |
|---|---|
ping | El eco y la respuesta llegan, en IPv4 o IPv6 |
ssh | La conexión se permite, o se deniega si eso es lo esperado |
wifi-associated | El cliente está asociado al SSID |
dhcp-bound | El cliente tiene concesión |
ospf-full | Dos routers son vecinos en estado FULL |
Cada resultado lleva el motivo, y los paquetes que generó se pueden ver salto a salto.
18-eve.md
Eve, el instructor
Eve es un agente de eve 0.47 desplegado en Vercel. En la interfaz es el botón Agent: un cajón lateral en escritorio y una pestaña en el móvil. Explica por qué algo falla, lo arregla con el cambio más pequeño o construye un laboratorio desde una frase.
La regla
Eve lee el motor: no se inventa una topología ni da por buena una red rota. Antes de responder llama a sus herramientas (get_lab_state, get_path, run_check), y lo que dice sale de lo que devuelven. Si la API no responde, lo dice con api_status en vez de adivinar.
Qué recibe
Cada mensaje de la web lleva delante un bloque [NetBench context] con la topología entera (equipos, direcciones, puertas de enlace, estado de los puertos, hasta 40 equipos), el último Check, las últimas caídas y la última traza, más la labKey del navegador. Con ella sus herramientas encuentran la sesión aunque la API se haya reiniciado.
Herramientas
| Herramienta | Cambia algo | Para |
|---|---|---|
get_lab_state | El estado de la sesión | |
get_device | Un equipo y su configuración | |
get_path | La ruta de un paquete y su caída | |
run_check | Las comprobaciones | |
list_commands | Los comandos de un tipo de equipo | |
highlight_devices | Señalar equipos en el lienzo | |
api_status | La salud y la versión de la API, si una labId sigue viva, el modelo en uso | |
apply_device_config | ✔ | Comandos en un equipo |
apply_lab_patch | ✔ | Equipos y cables |
build_lab | ✔ | Un laboratorio desde una frase o un JSON (40 equipos y 80 cables como mucho) |
Subagentes y habilidades
| Subagente | Hace |
|---|---|
explainer | Solo lee. Un veredicto de una o dos frases, la ruta o la configuración que lo prueba, y el siguiente comando que escribir |
fixer | Lee el contexto, corre run_check y get_path del par que falla, aplica el cambio más pequeño y vuelve a comprobar |
builder | Construye con los ocho tipos de equipo, elige el perfil de cada switch y sigue un plan de direcciones |
Las 7 habilidades (agent/skills/) son notas en Markdown que Eve carga según el tema: cómo hablar, el perfil del alumno, IPv4 e IPv6, VLAN, OSPF área 0, Wi-Fi con PSK y cortafuegos con ACL.
Cambios con permiso
- Antes de cada cambio, la herramienta pide a la API un
confirmTokenpara ese propósito (POST /api/eve/tools/confirm). Nunca acepta uno que diga el modelo. - Manda el cambio con el token y una
idempotencyKeynueva. Si la llamada se corta y se repite, la API devuelve la primera respuesta en vez de aplicar dos veces. - La aprobación humana es configurable con
EVE_APPROVAL:auto(por defecto),dangerous(pide permiso para reemplazar el laboratorio, borrar equipos o apagar puertos),onceoalways. En la web, el interruptor Auto-approve del cajón hace lo mismo. - Antes de llamar a la API,
guards.tsdescarta entradas que no tienen sentido: unalabIdde ejemplo, comandos vacíos o fuera de alcance, parches vacíos, cables mal escritos. Un error del modelo no cuesta un viaje a la red.
Los modelos
eve pide el modelo al AI Gateway de Vercel con OIDC; no hay claves de proveedores en el código. La cadena mezcla proveedores para que una caída no los tumbe a todos:
| Orden | Modelo |
|---|---|
| Principal | minimax/minimax-m3.1-flash |
| Respaldos | openai/gpt-5-mini, google/gemini-2.5-flash, zai/glm-4.7-flash, alibaba/qwen3.5-flash, mistral/mistral-small |
Hay dos niveles de respaldo. Dentro de una llamada, el Gateway prueba el resto de la cadena. Entre llamadas, un hook de eve avanza de modelo cuando un paso falla y lo recuerda por sesión; el principal se vuelve a probar a los 15 minutos. EVE_MODEL y EVE_FALLBACK_MODELS cambian la cadena sin tocar código.
Todos los modelos de la cadena están en el plan gratuito del AI Gateway. Esto importa: el 18 de noviembre de 2026 Eve no respondía a nada porque los seis modelos de la cadena anterior habían salido del plan gratuito, y el Gateway los rechazaba con gateway-free-tier-model-restricted. Antes de cambiar un modelo hay que mirar availableToFreeTier en la lista de modelos del Gateway, o comprar créditos.
Cómo se recupera
- La API falla:
nest.tsreintenta dos veces con espera creciente ante errores de red, tiempo agotado, 429 y 5xx, y respetaRetry-After. Cada error lleva un tipo (route-missing,stale-session,rate-limit…) y una instrucción para el modelo.route-missingsignifica que la API desplegada es más antigua que Eve. - El modelo falla: la web reintenta el turno hasta 3 veces (2, 5 y 12 segundos) en la misma sesión de eve, para no perder el historial ni la rotación de modelos.
- El stream se corta: la web se reconecta desde el último evento hasta 6 veces, sin duplicar mensajes.
Evals
Siete conversaciones con un modelo de verdad comprueban que Eve nombra la causa correcta y no construye lo que no existe. Ver Testing · Eve y navegador.
Límites
- El cajón entiende negrita, código y bloques de código (
eve-markdown.ts, que escapa todo antes); una tabla o un título saldrían como texto, así que las instrucciones de Eve le piden no usarlos. - Eve en producción depende del plan gratuito del AI Gateway, con su límite de peticiones por modelo.
19-curriculum.md
Laboratorios
El temario tiene 48 laboratorios en dos grupos:
- 22 modelos: redes completas que pasan Check tal cual. Enseñan cómo es una red que funciona.
- 26 ejercicios: redes rotas o incompletas. Cada uno apunta a su modelo, trae pistas progresivas y un parche oficial que hace pasar Check.
El selector los ordena por nivel y marca los que ya pasaron. «Next lab» lleva al siguiente.
Modelos
| Nivel | Laboratorio |
|---|---|
| Principiante | First IPv4 ping with DHCP · Unmanaged switch: plug and play · Two subnets through a router |
| Intermedio | Two routers, static routes · VLANs + router-on-a-stick · Two switches, one trunk, two VLANs · Managed L2: VLAN trunk and management SVI · DHCPv4 from the router · IPv6 SLAAC + ping6 |
| Avanzado | OSPF area 0, two routers · OSPF across three routers · Out to the Internet with NAT overload · Wi-Fi: associate, DHCP, ping the wired server · Wi-Fi with a controller (WLC + CAPWAP) · Firewall: SSH from the jump host only · Multilayer switch: inter-VLAN routing · Multilayer switch: local DHCP |
| Experto | Office: three departments, two switches · Campus: OSPF core + firewalled server room · Multilayer switch: remote DHCP relay · Dual-stack across two routers · Capstone: dual-stack office |
Ejercicios
| Nivel | Laboratorio |
|---|---|
| Principiante | Plug in the cable · Unmanaged switch: fix the hosts · Give PC2 an address · Turn the port on · Find the fault: wrong subnet mask · Find the fault: wrong default gateway |
| Intermedio | PC in the wrong VLAN · The trunk forgot a VLAN · Managed L2: VLAN missing from trunk · Sub-interface tagged with the wrong VLAN · DHCP hands out the wrong network · No IPv6 addresses on the PCs |
| Avanzado | Multilayer switch: enable routing · Multilayer switch: repair DHCP pool · Two routers, static routes · Static route with the wrong next hop · OSPF across three routers · OSPF neighbour never appears · Out to the Internet with NAT · NAT rule present, nothing translated · Nobody can join the Wi-Fi · The firewall locks out the jump host · Wi-Fi with a controller (WLC) |
| Experto | Office outage: three faults, one ticket · Campus: the server room is unreachable · Multilayer switch: missing DHCP relay |
Los switches, por pares
Cada perfil de switch tiene un modelo y un ejercicio:
| Modelo | Ejercicio |
|---|---|
model-unmanaged-switch | ex-unmanaged-host-fault |
model-managed-l2-switch | ex-managed-l2-trunk |
model-multilayer-intervlan | ex-multilayer-ip-routing |
model-multilayer-dhcp | ex-multilayer-dhcp-pool |
model-multilayer-dhcp-relay | ex-multilayer-dhcp-helper |
Cómo es un ejercicio
Find the fault: wrong default gateway: PC1 (10.0.0.10) tiene que hacer ping a PC2 (10.0.1.20) a través de R1. Check falla con «ARP timeout for 10.0.1.254 at PC2»: la petición llega, pero PC2 manda la respuesta a una puerta de enlace que no existe. Las tres pistas van de lo general a lo concreto:
- Troubleshoot the check: the request reaches PC2, so look at what PC2 does with the reply.
- On PC2 run ip route. Which gateway does the default route use? Which address does R1 have on PC2’s side?
- On PC2: ip route replace default via 10.0.1.1
El parche oficial es esa misma línea en PC2. Eve, el 18 de noviembre, llegó sola a lo mismo leyendo la ruta del paquete.
Las reglas del temario
Los tests del motor las comprueban en cada ejecución (ver Testing · motor):
- ids únicos y estables;
- todo laboratorio valida y todas sus líneas de arranque se aceptan;
- cada modelo pasa Check tal cual y no trae solución;
- cada ejercicio falla tal cual, apunta a un modelo que existe, trae resumen, pistas y parche, y pasa con él;
- aplicar el parche dos veces no rompe nada;
- el temario que ve la web no incluye la topología ni la solución; las pistas se piden aparte.
Laboratorios propios
Cualquier laboratorio se puede copiar («Save a copy»), editar (nombre, objetivo y comprobaciones), descargar como JSON y compartir con un enlace. Las copias tienen ids nb-*, así que nunca pisan uno del temario.
20-commands.md
Comandos
Cada equipo tiene su terminal. help enseña los comandos de ese tipo, y la chuleta de la web (Command reference) los lista con un buscador; un clic los escribe en la terminal. Un comando desconocido, o uno que ese equipo no tendría, falla con un error en vez de ignorarse. La lista sale de packages/engine/src/commands.ts, la misma que devuelve GET /api/commands/:kind y que usa Eve.
Linux (workstation, server)
| Comando | Qué hace |
|---|---|
ip addr [add|del ADDR/P dev IF] | Ver, añadir o quitar una dirección IPv4 o IPv6 |
ip addr flush dev IF | Quitar todas las de una interfaz |
ip link set IF up|down | Encender o apagar |
ip route [add|del|replace default via GW] | Ver, añadir, quitar o cambiar una ruta; add rechaza una segunda por defecto, como Linux |
ping [-c N], ping6 | Eco ICMP e ICMPv6 |
traceroute, traceroute6 | Traza (simulada) |
dhclient [IF] | Cliente DHCPv4 |
nmcli wifi connect SSID password PSK | Asociarse al Wi-Fi y, normalmente, pedir DHCP |
iw dev wlan0 link | Estado de la asociación |
dig, nslookup, resolvectl | DNS |
systemctl start ssh, ssh user@HOST | Servidor y cliente SSH (camino y puerto 22, sin criptografía) |
ss, hostname, cat /etc/hosts, tcpdump -c 10, reboot | Sockets, nombre, hosts, últimas tramas, recargar el arranque |
Switch
Tipo Cisco: se empieza en modo usuario, enable y configure terminal.
| Perfil | Comandos |
|---|---|
| No gestionable | Ninguno: es un puente L2 sin configuración |
| Gestionable L2 | vlan N, interface Gi0/N | VlanN, switchport mode access|trunk, switchport access vlan N, switchport trunk allowed vlan …, switchport trunk native vlan N, ip address (SVI de gestión), ip default-gateway, no shutdown, show run|vlan|mac|int|trunk, write |
| Multicapa | Lo anterior más ip routing, no switchport (puerto enrutado), ip route, ipv6 route, ip dhcp pool, ip dhcp excluded-address, ip helper-address |
Router
| Comando | Qué hace |
|---|---|
interface Gi0/N[.VLAN], encapsulation dot1Q N | Interfaz enrutada o subinterfaz 802.1Q (router-on-a-stick) |
ip address, no ip address, ipv6 address, no shutdown | Direcciones |
ipv6 nd prefix CIDR, no ipv6 nd suppress-ra | Anuncios de router para SLAAC |
ip route NET MASK NH, no ip route …, ipv6 route | Rutas estáticas (0.0.0.0 0.0.0.0 es la ruta por defecto) |
router ospf 1, router-id, network A.B.C.D WILD area 0 | OSPFv2, solo área 0 |
ip nat inside|outside, ip access-list standard NAME, ip nat inside source list NAME interface IF overload | NAT con sobrecarga |
ip dhcp pool NAME, network, default-router, dns-server | Servidor DHCPv4 |
ipv6 access-list NAME | ACL de IPv6 |
show run|ip route|ipv6 route|ip ospf neighbor|ip ospf database | Ver |
Firewall
zone lan|wan|wifi IF, policy SRC DST allow|deny [tcp PORT], nft add rule … (nftables simplificado, IPv4 e IPv6), masquerade wan (SNAT), show run|rules, y además ip addr y ping como un host.
Wi-Fi
| Equipo | Comandos |
|---|---|
| Access Point | ssid NAME, vlan N (un SSID, una VLAN), wpa2-psk PSK, channel N, capwap controller A.B.C.D, interface wlan0|Gi0/1 con shutdown/no shutdown, show ssid|interface |
| WLC | wlan create SSID vlan N, wpa2 psk PSK, show ap summary|wlan |
Internet
show run y ping. Contesta a 8.8.8.8.
Lo que no existe
BGP, MPLS, VXLAN, 802.1X, NSSA, enlaces virtuales de OSPF, cable de consola y enlaces serie. Escribirlos da un error, y el constructor y Eve los rechazan.