home
  • Español
  • English
  • Português
  • Como trabalho
  • star Projetos Destacados
  • Experiência
  • mail Contato
arrow_back Voltar ao projeto Início

Documentação do projeto

Documentação · NetBench

15 ficheiros markdown (produto, arquitetura, API, auth, dados, deploy…).

Nesta página Visión general 0% expand_more
Visión general Qué lo hace distinto Enlaces Stack En cifras Por dónde seguir Producto y features Para quién Un recorrido Equipos y cables Modos de la interfaz Herramientas para aprender Guardar y compartir Idiomas Lo que no hace Arquitectura Las piezas El motor es la fuente de verdad Una sesión Por qué en producción no hay socket Eve dentro de la arquitectura Qué pasa si algo cae Monorepo packages/engine apps/api apps/web apps/eve-agent Scripts de la raíz API Salud Cuentas Laboratorios Sesiones Herramientas de Eve Comandos Límites WebSocket (solo en local) Cuentas e invitados Sin cuenta por defecto Con cuenta Qué comprueba la API Los cambios de Eve Lo que se quitó Secretos Modelo de datos Postgres Un laboratorio Un parche Un paquete En el navegador Puesta en marcha y despliegue En local Producción La API en la plataforma de hosting Comprobar un despliegue Con Docker, en cualquier otro sitio Historia del despliegue Decisiones Pocos equipos, y que funcionen El motor decide, la interfaz pinta Cada botón escribe un comando El motor en un proceso que no se apaga Eve no puede cambiar nada sin token Modelos de varios proveedores Modelos y ejercicios por pares Sin cuenta para empezar La API en un Mac propio, sin WebSocket La sesión vive en memoria Retos y resultados Retos Los cables desaparecían en el móvil Un tercer PC no tenía enlace Angular sin Zone.js y los gestos de Safari ip route se leía como Linux La API de Railway se quedó antigua Railway desapareció Un inicio de sesión que regalaba cuentas Un test que fallaba la mitad de las veces Resultados Pendiente Angular Qué usa de Angular Decisiones de la web Idiomas Comunicación con la API Build El motor Qué simula Lo que se aproxima El motivo de cada caída Los equipos se configuran con comandos El constructor Comprobaciones Eve, el instructor La regla Qué recibe Herramientas Subagentes y habilidades Cambios con permiso Los modelos Cómo se recupera Evals Límites Laboratorios Modelos Ejercicios Los switches, por pares Cómo es un ejercicio Las reglas del temario Laboratorios propios Comandos Linux (workstation, server) Switch Router Firewall Wi-Fi Internet Lo que no existe

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 decideQué
El motorReenvío, ARP y NDP, VLAN, rutas, OSPF, DHCP, NAT, cortafuegos, asociación Wi-Fi, el motivo de cada caída
La webCómo se dibuja, qué se enseña según el modo, los atajos que escriben comandos reales en la terminal
EveExplicar y proponer, siempre a partir de lo que devuelven sus herramientas
La personaQué 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

CapaTecnología
MotorTypeScript 5.9 sin dependencias de ejecución, módulos ES
APINestJS 11 sobre Express, ws para el socket local, jsonwebtoken, bcryptjs, pg
WebAngular 22.1, signals y sin Zone.js, Tailwind CSS 4.3, TypeScript 6.0
Instructoreve 0.47 en Vercel, AI Gateway con una cadena de modelos de varios proveedores
DatosPostgres en Neon: usuarios y laboratorios guardados
PruebasVitest 3 y Supertest; evals de eve
DespliegueWeb 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 equipo8, y el switch con 3 perfiles
Laboratorios incluidos48: 22 modelos que funcionan y 26 ejercicios rotos con solución oficial
Idiomas de la interfaz5: inglés, español, francés, alemán y portugués
Herramientas de Eve10, con 3 subagentes y 7 habilidades
Tests del motor64
Tests de la API37
Evals de Eve7
Códigounas 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

  1. 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».
  2. 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.
  3. 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.
  4. 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.
  5. 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

EquipoPuertosTerminal
Workstation (PC)eth0, wlan0Linux
Servereth0, eth1Linux
SwitchGi0/1 a Gi0/8Ninguna (no gestionable) o tipo Cisco
RouterGi0/0 a Gi0/3Tipo Cisco
Firewalleth0 a eth3Linux con nft
Access PointGi0/1, wlan0Tipo Cisco
WLCGi0/1Tipo Cisco
Cloud (Internet)eth0Un 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

ModoCuándoQué enseña
SimplePor defectoEthernet entre equipos, solo los puertos usados, IPv4. Lo justo para el primer día
AdvancedInterruptor de la cabeceraTipos de cable, la rejilla de puertos en cada tarjeta, IPv6, MAC y la configuración en ejecución
FocusEscritorio, Shift+FSolo 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 defectoDos 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
PiezaDónde correPor qué ahí
Web (Angular)Vercel, estáticaSon ficheros; un CDN basta
EveVercel (eve deploy)eve usa el AI Gateway de Vercel con OIDC, sin claves en el código
API + motorUn proceso de Node en un Mac propio, publicado como netbench-api.cristiancode.devEl motor guarda cada laboratorio en memoria y lo hace avanzar en el tiempo; no cabe en una función de 10 segundos
PostgresNeonCuentas 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étodoQué 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

  1. POST /api/sessions con un labId del temario o un laboratorio entero. La API crea un Engine, ejecuta las líneas de arranque de cada equipo y devuelve sessionId y el estado.
  2. La web pinta el estado. Cada cambio del usuario (cable, equipo, mover) va por POST /sessions/:id/edit; cada comando, por POST /sessions/:id/cli.
  3. 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 /ws que empuja el estado cada segundo.
  4. 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 misma labKey, 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

CaeQué sigue funcionando
La APILa 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
PostgresInvitados y laboratorios en memoria; iniciar sesión y «My labs» fallan
Eve o el AI GatewayTodo menos el cajón de Eve, que enseña el error y reintenta
Ese MacLa 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.

FicheroLíneasQué tiene
engine.ts3.356El reenvío por eventos discretos, la CLI, ping, ruta y comprobaciones
labs-models.ts, labs-exercises.ts, labs-shared.ts, labs.tsLos 48 laboratorios y su registro
build.tslabFromSpec: de una frase en inglés a una topología
patch.ts, validate.tsValidar y aplicar un LabPatch; validar un laboratorio entero
types.tsTipos de equipo, puertos, cables, laboratorio, comprobaciones, paquetes
devices.ts, cables.ts, ip.ts, commands.tsCrear equipos, reglas de cables, utilidades IPv4/IPv6, la ayuda de cada tipo
schema/lab.schema.jsonEl esquema JSON de un laboratorio

apps/api

FicheroQué tiene
main.tsArranque: base de datos, aplicación, socket, PORT y HOST
create-app.tsCORS, el proxy /eve opcional y el WebSocket /ws
http.tsLos controladores: salud, autenticación, laboratorios, sesiones, herramientas de Eve, comandos
sim.service.tsLas sesiones en memoria, el límite de llamadas, los confirmToken y la repetición idempotente
store.ts, db.tsUsuarios y laboratorios: un mapa en memoria delante de Postgres
rate-limit.filter.tsEl 429 con Retry-After

apps/web

Angular con componentes standalone y plantillas en ficheros aparte. 16 ficheros de TypeScript y 10 plantillas.

FicheroQué tiene
workspace.ts, workspace.htmlEl lienzo, los modos, el inspector, Check, Reach, pistas, deshacer, el arranque y la recuperación de sesión
api.tsEl cliente HTTP, el sondeo del estado o el socket, el guardado de invitado
eve-client.tsLa 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.tsLos componentes del muelle y la cabecera
lab-history.ts, lab-library.tsDeshacer y rehacer; los laboratorios propios
i18n/Un diccionario por idioma; el tipo de las claves sale del inglés
vercel.jsonSalida dist/web/browser y la reescritura de la SPA

apps/eve-agent

CarpetaQué tiene
agent/agent.ts, agent/lib/model.tsEl 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

ScriptQué hace
npm run devAPI en :3001, web en :4200 y Eve en :4010 a la vez
npm testTests del motor y de la API
npm run deploy:eveDespliega 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

RutaRespuesta
GET /healthok, 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

RutaQué hace
POST /auth/register{ email, password } → { token, user }
POST /auth/loginIgual, con una cuenta existente
POST /auth/guestUn token de invitado, sin guardar nada
GET /auth/meEl usuario del token

Ver Cuentas e invitados.

Laboratorios

RutaQué hace
GET /labs/builtinEl temario: id, nombre, objetivo, tipo, nivel, temas, número de pistas y de comprobaciones. Sin topología ni solución
GET /labs/builtin/:idUn laboratorio del temario, sin la solución
GET /labs/builtin/:id/solutionPistas y parche oficial de un ejercicio (un modelo responde 404)
GET /labs/builtin/:id/exercisesLos ejercicios de un modelo
GET /labs, POST /labs, GET /labs/:id, PUT /labs/:id, DELETE /labs/:idLos 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.

RutaQué hace
GET /sessions/:id/stateEl estado: equipos, interfaces, enlaces y los últimos 80 paquetes
POST /sessions/:id/cli{ deviceId, line } → salida, prompt, error, eventos y estado
POST /sessions/:id/checkLas comprobaciones del laboratorio con su motivo
POST /sessions/:id/ping, /pathUn ping o la ruta de un paquete
POST /sessions/:id/cancelCorta 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/solutionAplica la solución oficial de un ejercicio
POST /sessions/:id/saveEl laboratorio vivo como JSON, para el navegador o la cuenta
POST /sessions/:id/confirmEmite un confirmToken para un propósito
POST /sessions/:id/patch, /config, /buildCambios de Eve; exigen confirmToken (403 sin él)
POST /sessions/:id/highlightResalta 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).

HerramientaCambia algoQué hace
confirmEmite el confirmToken de un propósito
get_lab_stateEl estado de la sesión
get_deviceUn equipo con su configuración
get_pathLa ruta de un paquete, con la caída y su motivo
run_checkLas comprobaciones
list_commandsLos comandos de un tipo de equipo y perfil
highlight_devicesResalta 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 con Retry-After y retryAfter en el cuerpo. Leer el estado y confirm no 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, con sub, email y guest. La web lo guarda en localStorage.nb_token y 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

RutaSin tokenInvitadoCuenta
Temario, salud, comandos✔✔✔
Sesiones y herramientas de Eve✔✔✔
GET /auth/me401✔✔
Laboratorios guardados (/labs)401401✔, 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

VariableDóndeSin ella
JWT_SECRETLas variables del proyecto en la plataforma de hostingLa API firma con un valor de desarrollo; nunca en producción
DATABASE_URLIgualUsuarios 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óndeQuéCuánto dura
La memoria de la APILas sesiones: un Engine por laboratorio abierto, con sus tablas ARP, MAC, rutas y paquetesHasta que la API se reinicia
Postgres (Neon)Usuarios y laboratorios guardadosSiempre
El navegadorEl laboratorio de invitado, la sesión abierta, preferencias, puntos de controlLo 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.

CampoQué es
id, name, goal, descriptionIdentidad y texto. Los del temario son lab-*, model-* y ex-*; las copias propias, nb-*
kind, level, topicsmodel o exercise; beginner a expert; etiquetas como vlan u ospf
modelId, solutionSolo en ejercicios: el modelo que funciona, y las pistas y el parche que lo arreglan
deviceskind, 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)
linksLos dos extremos (PC1:eth0) y el tipo de cable
checksLo que tiene que funcionar: ping, ssh, wifi-associated, dhcp-bound, ospf-full
differsNoteEn 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

ClaveQué guarda
nb_tokenEl JWT
nb_guest_labEl 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_labsLos laboratorios propios de este navegador
nb_passedLos laboratorios cuyo Check pasó
nb_ckptLos puntos de control (12 como mucho)
nb_basic, nb_advanced, nb_focusLos modos
nb_eve_open, nb_eve_autoEl cajón de Eve abierto y la aprobación automática
nb_localeEl idioma
nb_view, nb_dock_h, nb_welcomeOpciones 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 /api y 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:eve otra vez.
  • Sin DATABASE_URL, cuentas y laboratorios viven en memoria.

Producción

PiezaDóndeCómo se despliega
WebVercel, proyecto netbench-wwwCada push a main
EveVercel, proyecto netbench-eveCada push a main; a mano con npm run deploy:eve
APIUna plataforma de hosting propia, en un Mac, proyecto netbench-api, publicado en https://netbench-api.cristiancode.devCada push a main
Base de datosNeon, proyecto netbenchsql/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.

AjusteValor
Ramamain, despliegue automático
Tipobackend, servido por Cloudflare
Node24
Instalaciónnpm ci --no-audit --no-fund --workspace @netbench/engine --workspace @netbench/api --include-workspace-root
Buildnpm test -w @netbench/engine && npm test -w @netbench/api
Arranquenpm 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 PORT y HOST=127.0.0.1, y la API escucha ahí; en un contenedor, sin HOST, escucha en 0.0.0.0.
  • /api/health devuelve el commit desplegado como version (de HOSTING_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_path es 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 --noEmit pasa 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

APIDóndePara
Sin Zone.jsToda la aplicaciónLos signals avisan a la vista; nada parchea los eventos del navegador
Componentes standaloneTodosCada componente importa lo que usa
Plantillas en ficheros aparte (templateUrl)TodosLa lógica y el HTML se leen por separado
ChangeDetectionStrategy.OnPush8 componentesSolo se repintan cuando cambia una entrada o un signal
signal, computedWorkspace, Api, EveClient, el restoEstado local y derivado; basicMode(), focusMode(), showEve() deciden qué se pinta en cada modo
input, outputnb-terminal, nb-packets, nb-lab-picker, nb-mine-picker, nb-cheat-sheet, nb-flagEntradas como signals y eventos sin EventEmitter
inject()Servicios y componentesInyección sin constructor
viewChildnb-terminalLa salida y el campo de texto, sin decoradores
@if, @for, @switchTodas las plantillasControl de flujo nativo; workspace.html tiene 249 bloques
ng-template con NgTemplateOutletworkspace.htmlEl mismo panel de equipo en el inspector de escritorio y en la hoja del móvil
Pipei18n.ts, eve-markdown.tsLa traducción en las plantillas; la negrita y el código de las respuestas de Eve, escapadas antes de pasar por [innerHTML]
provideRouterapp.config.tsUna ruta, '' → Workspace

Decisiones de la web

  • Un componente grande a propósito. Workspace lleva 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() y showTerm() deciden qué se ve en escritorio, en móvil y en Focus. Un panel nuevo se añade ahí, no con un @if suelto.
  • 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 addEventListener y llama a detectChanges(), porque sin Zone.js Angular no se entera solo.
  • La terminal no usa ngModel. Escribe en un signal con [value] y (input), porque ngModel aplica 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.css define los colores (ink-*, brand-*, ok, warn, danger, eve) en @theme y 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

CapaQué hay
L1Cables 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)
L2Aprendizaje 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
L3ARP 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
ServiciosDHCPv4 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
SeguridadACL estándar y de IPv6, el cortafuegos con zonas, políticas y nft, NAT con sobrecarga (PAT) hacia Internet
Wi-FiUn 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é:

EjemploCapa
Interface Gi0/2 is administratively downL1, puerto apagado
No cable on eth0L1
Wrong cable (estado del puerto)L1, directo donde iba cruzado o al revés
VLAN mismatch on SW1 Gi0/2L2
No subinterface for VLAN 20 on R1 Gi0/0L2/L3, router-on-a-stick incompleto
RSTP-lite blocking SW2 Gi0/3L2, puerto bloqueado por un ciclo
ARP timeout for 10.0.1.254 at PC2L3, puerta de enlace que no existe
No route to 10.9.9.10 on R2L3
TTL expired at R1L3
ACL drop: deny tcp 10.2.2.10 → 10.9.9.10 …Seguridad
not associatedWi-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

TipoPasa cuando
pingEl eco y la respuesta llegan, en IPv4 o IPv6
sshLa conexión se permite, o se deniega si eso es lo esperado
wifi-associatedEl cliente está asociado al SSID
dhcp-boundEl cliente tiene concesión
ospf-fullDos 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

HerramientaCambia algoPara
get_lab_stateEl estado de la sesión
get_deviceUn equipo y su configuración
get_pathLa ruta de un paquete y su caída
run_checkLas comprobaciones
list_commandsLos comandos de un tipo de equipo
highlight_devicesSeñalar equipos en el lienzo
api_statusLa 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

SubagenteHace
explainerSolo lee. Un veredicto de una o dos frases, la ruta o la configuración que lo prueba, y el siguiente comando que escribir
fixerLee el contexto, corre run_check y get_path del par que falla, aplica el cambio más pequeño y vuelve a comprobar
builderConstruye 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

  1. Antes de cada cambio, la herramienta pide a la API un confirmToken para ese propósito (POST /api/eve/tools/confirm). Nunca acepta uno que diga el modelo.
  2. Manda el cambio con el token y una idempotencyKey nueva. Si la llamada se corta y se repite, la API devuelve la primera respuesta en vez de aplicar dos veces.
  3. La aprobación humana es configurable con EVE_APPROVAL: auto (por defecto), dangerous (pide permiso para reemplazar el laboratorio, borrar equipos o apagar puertos), once o always. En la web, el interruptor Auto-approve del cajón hace lo mismo.
  4. Antes de llamar a la API, guards.ts descarta entradas que no tienen sentido: una labId de 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:

OrdenModelo
Principalminimax/minimax-m3.1-flash
Respaldosopenai/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.ts reintenta dos veces con espera creciente ante errores de red, tiempo agotado, 429 y 5xx, y respeta Retry-After. Cada error lleva un tipo (route-missing, stale-session, rate-limit…) y una instrucción para el modelo. route-missing significa 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

NivelLaboratorio
PrincipianteFirst IPv4 ping with DHCP · Unmanaged switch: plug and play · Two subnets through a router
IntermedioTwo 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
AvanzadoOSPF 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
ExpertoOffice: 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

NivelLaboratorio
PrincipiantePlug 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
IntermedioPC 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
AvanzadoMultilayer 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)
ExpertoOffice 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:

ModeloEjercicio
model-unmanaged-switchex-unmanaged-host-fault
model-managed-l2-switchex-managed-l2-trunk
model-multilayer-intervlanex-multilayer-ip-routing
model-multilayer-dhcpex-multilayer-dhcp-pool
model-multilayer-dhcp-relayex-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:

  1. Troubleshoot the check: the request reaches PC2, so look at what PC2 does with the reply.
  2. On PC2 run ip route. Which gateway does the default route use? Which address does R1 have on PC2’s side?
  3. 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)

ComandoQué hace
ip addr [add|del ADDR/P dev IF]Ver, añadir o quitar una dirección IPv4 o IPv6
ip addr flush dev IFQuitar todas las de una interfaz
ip link set IF up|downEncender 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], ping6Eco ICMP e ICMPv6
traceroute, traceroute6Traza (simulada)
dhclient [IF]Cliente DHCPv4
nmcli wifi connect SSID password PSKAsociarse al Wi-Fi y, normalmente, pedir DHCP
iw dev wlan0 linkEstado de la asociación
dig, nslookup, resolvectlDNS
systemctl start ssh, ssh user@HOSTServidor y cliente SSH (camino y puerto 22, sin criptografía)
ss, hostname, cat /etc/hosts, tcpdump -c 10, rebootSockets, nombre, hosts, últimas tramas, recargar el arranque

Switch

Tipo Cisco: se empieza en modo usuario, enable y configure terminal.

PerfilComandos
No gestionableNinguno: es un puente L2 sin configuración
Gestionable L2vlan 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
MulticapaLo anterior más ip routing, no switchport (puerto enrutado), ip route, ipv6 route, ip dhcp pool, ip dhcp excluded-address, ip helper-address

Router

ComandoQué hace
interface Gi0/N[.VLAN], encapsulation dot1Q NInterfaz enrutada o subinterfaz 802.1Q (router-on-a-stick)
ip address, no ip address, ipv6 address, no shutdownDirecciones
ipv6 nd prefix CIDR, no ipv6 nd suppress-raAnuncios de router para SLAAC
ip route NET MASK NH, no ip route …, ipv6 routeRutas 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 0OSPFv2, solo área 0
ip nat inside|outside, ip access-list standard NAME, ip nat inside source list NAME interface IF overloadNAT con sobrecarga
ip dhcp pool NAME, network, default-router, dns-serverServidor DHCPv4
ipv6 access-list NAMEACL de IPv6
show run|ip route|ipv6 route|ip ospf neighbor|ip ospf databaseVer

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

EquipoComandos
Access Pointssid 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
WLCwlan 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.

Nesta página

Visión general Qué lo hace distinto Enlaces Stack En cifras Por dónde seguir Producto y features Para quién Un recorrido Equipos y cables Modos de la interfaz Herramientas para aprender Guardar y compartir Idiomas Lo que no hace Arquitectura Las piezas El motor es la fuente de verdad Una sesión Por qué en producción no hay socket Eve dentro de la arquitectura Qué pasa si algo cae Monorepo packages/engine apps/api apps/web apps/eve-agent Scripts de la raíz API Salud Cuentas Laboratorios Sesiones Herramientas de Eve Comandos Límites WebSocket (solo en local) Cuentas e invitados Sin cuenta por defecto Con cuenta Qué comprueba la API Los cambios de Eve Lo que se quitó Secretos Modelo de datos Postgres Un laboratorio Un parche Un paquete En el navegador Puesta en marcha y despliegue En local Producción La API en la plataforma de hosting Comprobar un despliegue Con Docker, en cualquier otro sitio Historia del despliegue Decisiones Pocos equipos, y que funcionen El motor decide, la interfaz pinta Cada botón escribe un comando El motor en un proceso que no se apaga Eve no puede cambiar nada sin token Modelos de varios proveedores Modelos y ejercicios por pares Sin cuenta para empezar La API en un Mac propio, sin WebSocket La sesión vive en memoria Retos y resultados Retos Los cables desaparecían en el móvil Un tercer PC no tenía enlace Angular sin Zone.js y los gestos de Safari ip route se leía como Linux La API de Railway se quedó antigua Railway desapareció Un inicio de sesión que regalaba cuentas Un test que fallaba la mitad de las veces Resultados Pendiente Angular Qué usa de Angular Decisiones de la web Idiomas Comunicación con la API Build El motor Qué simula Lo que se aproxima El motivo de cada caída Los equipos se configuran con comandos El constructor Comprobaciones Eve, el instructor La regla Qué recibe Herramientas Subagentes y habilidades Cambios con permiso Los modelos Cómo se recupera Evals Límites Laboratorios Modelos Ejercicios Los switches, por pares Cómo es un ejercicio Las reglas del temario Laboratorios propios Comandos Linux (workstation, server) Switch Router Firewall Wi-Fi Internet Lo que no existe

0% lido

folder_zip Descarregar todos (ZIP)
Pergunte sobre o Cristian Assistente com IA, só dados públicos

É um assistente automático e pode errar. Para algo importante, escreva ao Cristian.