Skip to content

Commit 0f52295

Browse files
committed
docs: feature coverage pass on the website, slimmer README (#1365)
Website (features page, all 10 languages): real uplink evidence tags and manual fleet overrides on the topology section, per-device offline alerts and the newer device type icons on devices, connect/disconnect events with session duration on WireGuard, the actual alert categories with extra notification channels (ntfy, Telegram, webhooks), and the integration list (MQTT/Home Assistant, MCP, API tokens, HTTPS) on settings. README: drop Why NetPulse? (human origin story included), What to expect, How discovery works and Development; promote the MCP server to a first-class feature paragraph in What you get, absorbing its standalone section. Mirrored in README.es.md.
1 parent f89c839 commit 0f52295

4 files changed

Lines changed: 97 additions & 212 deletions

File tree

‎README.es.md‎

Lines changed: 11 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -44,38 +44,6 @@ No necesitas un solo router para ver NetPulse funcionando:
4444
es el inventario completo: cada pantalla y cada función, con las decisiones
4545
técnicas y el alcance honesto de cada una.
4646

47-
## ¿Por qué NetPulse?
48-
49-
Si usas OpenWrt, tu red ya es tuya. Pero que sea tuya implica *conocerla*:
50-
qué se conecta dónde, qué va bien, qué cambió anoche. LuCI te muestra un
51-
router cada vez; las suites NMS tipo Zabbix o LibreNMS están pensadas para
52-
un datacenter. Lo que faltaba es lo intermedio: un NOC doméstico que se
53-
instala en minutos y simplemente te enseña tu red.
54-
55-
NetPulse es esa pieza. Nació de mi propia red: un GL.iNet Flint 2 como
56-
gateway y tres puntos de acceso Xiaomi AX6 de segunda mano, todos con
57-
OpenWrt, cada uno con su LuCI. Quería una sola pantalla que me dijera la
58-
verdad sobre el conjunto, así que la construí y la uso cada mañana.
59-
60-
Tres reglas dan forma a todo lo que hace:
61-
62-
- **El sondeo nunca escribe.** El servidor genera su propio par de claves
63-
SSH; autorizas la pública en cada router y NetPulse solo *lee* (ubus,
64-
`/proc`, iwinfo, `bridge fdb`, `wg show`). Todo lo que escribe (reservar
65-
una IP, bloquear un dispositivo, orquestar servicios, actualizar
66-
firmware) es una acción explícita que lanzas tú, con snapshot de
67-
configuración y rollback automático.
68-
- **Sin nube, sin cuentas.** Un único binario Go estático con la web
69-
embebida, corriendo en una caja pequeña dentro de tu LAN. SQLite para las
70-
series temporales, modo WAL, sin servicios externos. La única llamada a
71-
casa es un contador diario anónimo de instancias: un id aleatorio, la
72-
versión y el OS/arquitectura, nada más (no se guardan IPs ni sale ningún
73-
dato de tu red). Existe solo para saber cuántas instancias corren y se
74-
actualizan; desactívalo cuando quieras con `NETPULSE_TELEMETRY=0`.
75-
- **Libre de verdad, para siempre.** AGPL-3.0, sin versión premium esperando
76-
detrás de un pago. Si te sirve, una estrella en GitHub es la forma de dar
77-
las gracias.
78-
7947
## Qué te llevas
8048

8149
**Resumen de flota y una puntuación de salud que significa algo.** Un único
@@ -144,9 +112,6 @@ pausar sin borrarla: sin sondeo ni alertas, con su histórico intacto.
144112
- **Rack físico (preview en Labs)**: dibuja tu rack de 19", coloca tu hardware
145113
y deja que NetPulse proponga el cableado desde la topología detectada.
146114
Apagado por defecto.
147-
- **Asistente IA (MCP)**: un servidor MCP integrado de solo lectura que tu
148-
asistente consulta con un token de API (ver
149-
[Asistentes de IA](#asistentes-de-ia-mcp)).
150115
- **Alertas que te encuentran**: temperatura, dispositivo nuevo, firmware
151116
disponible, WAN caída, problemas de agente; feed en la campana más canales
152117
de aviso (Web Push nativo, ntfy, Telegram y webhook saliente). Los canales
@@ -168,20 +133,21 @@ pausar sin borrarla: sin sondeo ni alertas, con su histórico intacto.
168133
o las opciones UCI `mqtt_*` en on-box). Topics, entidades y limitaciones en el
169134
[manual](docs/manual.es.md#home-assistant-mqtt).
170135

136+
**Un servidor MCP para tu asistente de IA.** NetPulse lleva un servidor
137+
[MCP](https://modelcontextprotocol.io) embebido de solo lectura (streamable
138+
HTTP en `/mcp`) para que tu asistente consulte el estado de la flota, la
139+
salud por router, los dispositivos conocidos, los peers WireGuard, las
140+
estadísticas de AdGuard Home, el grafo de topología y las alertas activas con
141+
un token de API. Solo tokens (nunca la cookie de sesión), rate limit y cada
142+
llamada registrada en el log de auditoría. Desactivado por defecto: actívalo
143+
con `NETPULSE_MCP_ENABLED=1` y crea un token en Ajustes → Tokens de API.
144+
Mantén el puerto en tu LAN: quien tenga el token puede leer el estado
145+
completo de tu red.
146+
171147
Esto sigue siendo una selección: **[todas las funcionalidades están en la
172148
web](https://netpulse.cloudless.club/features)**, una a una, y todo lo
173149
anterior se puede tocar en la **[demo en vivo](https://demo.netpulse.cloudless.club)**.
174150

175-
## Cómo funciona el descubrimiento
176-
177-
NetPulse descubre los dispositivos cliente a partir de tres fuentes en los
178-
routers monitorizados: leases DHCP, el FDB del bridge (clientes cableados) y
179-
mDNS cuando `umdns` está instalado. LLDP identifica routers y switches
180-
vecinos. El tráfico por cliente prefiere `nlbwmon` (contadores por MAC,
181-
cable) y cae a los contadores de bytes de hostapd (Wi-Fi); si un cliente
182-
cableado no muestra serie de tráfico, instala `nlbwmon` en ese router.
183-
`vnstat` mide totales por interfaz, no por cliente, así que no es sustituto.
184-
185151
## Empieza en unos cinco minutos
186152

187153
Necesitas una caja Linux con systemd (x86_64, arm64 o armv7; un LXC o VM
@@ -284,17 +250,6 @@ cambiado" antes de actualizar. El historial completo vive en
284250
[página de releases](https://github.com/gnacho/netpulse/releases); el plan
285251
que viene, en [docs/ROADMAP.md](docs/ROADMAP.md).
286252

287-
## Qué debes esperar
288-
289-
NetPulse es un proyecto personal, construido para mi propia red y publicado
290-
como software libre (AGPL-3.0). Es y será siempre libre. Trabajo en él en mi
291-
tiempo libre y evoluciona siguiendo primero mis propias necesidades; con
292-
colaboraciones o apoyo quizás crezca más rápido, pero no puedo prometer
293-
nada. **Nota honesta de alcance**: de momento solo se ha probado con mi
294-
propio hardware (un gateway GL.iNet Flint 2 y tres puntos de acceso Xiaomi
295-
AX6 con OpenWrt), además de WireGuard y AdGuard Home. Otros dispositivos
296-
OpenWrt deberían funcionar, pero el tuyo sería el primero en contarlo.
297-
298253
## Documentación
299254

300255
- **[Manual de usuario](docs/manual.es.md)** (también en
@@ -307,46 +262,6 @@ OpenWrt deberían funcionar, pero el tuyo sería el primero en contarlo.
307262
- **[Discusiones](https://github.com/gnacho/netpulse/discussions)**:
308263
preguntas, ideas y hablar del futuro.
309264

310-
## Asistentes de IA (MCP)
311-
312-
NetPulse lleva un servidor [MCP](https://modelcontextprotocol.io) embebido
313-
(streamable-HTTP) para que los asistentes de IA puedan consultar tu instancia
314-
con herramientas de solo lectura: estado de la flota, salud por router,
315-
dispositivos conocidos, peers WireGuard, estadísticas de AdGuard Home, el
316-
grafo de topología detectado y las alertas activas. Nada más: sin cambios de
317-
configuración ni reinicios.
318-
319-
Vive en Ajustes > Integraciones y está **desactivado por defecto a nivel de
320-
servidor**. Para activarlo:
321-
322-
```bash
323-
NETPULSE_MCP_ENABLED=1
324-
```
325-
326-
Después crea un token de API en Ajustes > Tokens de API y apunta tu cliente
327-
MCP a `http://<host-de-netpulse>:<puerto>/mcp` con ese token como Bearer. El
328-
endpoint solo acepta tokens de API (nunca la cookie de sesión), lleva rate
329-
limit y cada llamada a tool queda registrada en el log de auditoría. Mantén
330-
el puerto en tu LAN o detrás de un firewall: quien tenga el token puede leer
331-
el estado completo de tu red.
332-
333-
## Desarrollo
334-
335-
```bash
336-
# Backend (Go; sirve app/dist vía go:embed)
337-
cd server-go
338-
cp ../app/dist internal/staticspa/dist -r # el dist embebido nunca se trackea
339-
go build -o netpulse ./cmd/netpulse && DEMO_MODE=1 ./netpulse
340-
341-
# Frontend (dev server con proxy)
342-
cd app
343-
npm install
344-
npm run dev
345-
346-
# Tests
347-
cd server-go && go test ./...
348-
```
349-
350265
## Gracias enormes
351266

352267
NetPulse no existiría sin [OpenWrt](https://openwrt.org/). Toda la premisa

‎README.md‎

Lines changed: 9 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -43,37 +43,6 @@ You don't need a single router to see NetPulse working:
4343
is the complete feature inventory: every screen and feature, with the
4444
technical decisions and the honest scope of each one.
4545

46-
## Why NetPulse?
47-
48-
If you run OpenWrt, you already own your network. But owning it means
49-
*knowing* it: what connects where, what's healthy, what changed overnight.
50-
LuCI shows you one router at a time; NMS suites like Zabbix or LibreNMS are
51-
built for datacenters. What was missing is the thing in between: a home NOC
52-
that installs in minutes and just shows you your network.
53-
54-
NetPulse is that missing piece. It grew out of my own network: a GL.iNet
55-
Flint 2 as the gateway and three second-hand Xiaomi AX6 access points, all on
56-
OpenWrt, each with its own LuCI. I wanted one screen that told me the truth
57-
about the whole thing, so I built it and use it every morning.
58-
59-
Three rules shape everything it does:
60-
61-
- **Monitoring never writes.** The server generates its own SSH key; you
62-
authorize the public key on each router and NetPulse only ever *reads*
63-
(ubus, `/proc`, iwinfo, `bridge fdb`, `wg show`). Anything that writes
64-
(reserving an IP, blocking a device, orchestrating services, flashing
65-
firmware) is an explicit, admin-triggered action, applied with a config
66-
snapshot and automatic rollback.
67-
- **No cloud, no accounts.** One static Go binary with the web app embedded,
68-
running on a small box inside your LAN. SQLite for the time series, WAL
69-
mode, no external services. The only call home is a daily anonymous
70-
instance count: a random id, the version and the OS/architecture, nothing
71-
else (no IPs are stored, no network data ever leaves your LAN). It exists
72-
only to know how many instances run and stay updated; turn it off any time
73-
with `NETPULSE_TELEMETRY=0`.
74-
- **Free as in forever.** AGPL-3.0, no premium tier waiting behind a paywall.
75-
If it's useful to you, a star on GitHub is the way to say thanks.
76-
7746
## What you get
7847

7948
**Fleet overview and a health score that means something.** One 0-100 score
@@ -138,9 +107,6 @@ kept.
138107
OpenWrt only (device list filtered, with an explanatory note).
139108
- **Physical rack (Labs preview)**: draw your 19" rack, place your hardware and
140109
let NetPulse propose the cabling from the detected topology. Off by default.
141-
- **AI assistant (MCP)**: an embedded read-only MCP server your assistant can
142-
query with an API token (see
143-
[AI assistants](#ai-assistants-mcp)).
144110
- **Alerts that find you**: temperature, new device, firmware available, WAN
145111
down, agent issues; bell feed plus notification channels (native Web Push,
146112
ntfy, Telegram and outgoing webhook). Notification channels only carry
@@ -162,19 +128,18 @@ kept.
162128
equivalent `mqtt_*` UCI options on-box). Topics, entities and limits in the
163129
[manual](docs/manual.en.md#home-assistant-mqtt).
164130

131+
**An MCP server for your AI assistant.** NetPulse embeds a read-only
132+
[MCP](https://modelcontextprotocol.io) server (streamable HTTP at `/mcp`) so
133+
your assistant can query fleet status, per-router health, known devices,
134+
WireGuard peers, AdGuard Home stats, the topology graph and active alerts
135+
with an API token. Token-only auth (never the session cookie), rate limited,
136+
every call logged for audit. Disabled by default: enable it with
137+
`NETPULSE_MCP_ENABLED=1` and mint a token in Settings → API tokens. Keep the
138+
port on your LAN: anyone with the token can read your whole network state.
139+
165140
That is still a selection: **[every feature is on the website](https://netpulse.cloudless.club/features)**,
166141
one by one, and everything above is clickable in the **[live demo](https://demo.netpulse.cloudless.club)**.
167142

168-
## How discovery works
169-
170-
NetPulse discovers client devices from three sources on the monitored
171-
routers: DHCP leases, the bridge FDB (wired clients) and mDNS when `umdns` is
172-
installed. LLDP identifies neighbouring routers and switches. Per-client
173-
traffic prefers `nlbwmon` (per-MAC counters, wired) and falls back to hostapd
174-
byte counters (Wi-Fi); if a wired client shows no traffic series, install
175-
`nlbwmon` on that router. `vnstat` counts per-interface totals, not per
176-
client, so it is not a substitute.
177-
178143
## Get started in about five minutes
179144

180145
You need a Linux box with systemd (x86_64, arm64 or armv7; a small LXC or VM
@@ -274,17 +239,6 @@ before you update. The full version history lives in
274239
[releases page](https://github.com/gnacho/netpulse/releases); the plan ahead
275240
is in [docs/ROADMAP.md](docs/ROADMAP.md).
276241

277-
## What to expect
278-
279-
NetPulse is a personal project, built for my own network and released as
280-
free software (AGPL-3.0). It is and will always be free. I work on it in my
281-
free time and it evolves following my own needs first; with contributions or
282-
support it might grow faster, but I can't promise anything. **Honest scope
283-
note**: so far it has been tested with my own hardware (a GL.iNet Flint 2
284-
gateway and three Xiaomi AX6 access points running OpenWrt) plus WireGuard
285-
and AdGuard Home. Other OpenWrt devices should work, but yours would be the
286-
first to tell.
287-
288242
## Documentation
289243

290244
- **[User manual](docs/manual.en.md)** (also in
@@ -297,45 +251,6 @@ first to tell.
297251
- **[Discussions](https://github.com/gnacho/netpulse/discussions)**: questions,
298252
ideas and shape-the-future talk.
299253

300-
## AI assistants (MCP)
301-
302-
NetPulse ships an embedded [MCP](https://modelcontextprotocol.io) server
303-
(streamable-HTTP) so AI assistants can query your instance with read-only
304-
tools: fleet status, per-router health, known devices, WireGuard peers,
305-
AdGuard Home stats, the detected topology graph and active alerts. Nothing
306-
else: no configuration changes, no restarts.
307-
308-
It lives under Settings > Integrations and is **disabled by default at the
309-
server level**. To enable it:
310-
311-
```bash
312-
NETPULSE_MCP_ENABLED=1
313-
```
314-
315-
Then create an API token in Settings > API tokens and point your MCP client
316-
at `http://<your-netpulse-host>:<port>/mcp` with that token as the Bearer
317-
token. The endpoint only accepts API tokens (never the session cookie), is
318-
rate limited, and every tool call is logged for audit. Keep the port on your
319-
LAN or behind a firewall: anyone with the token can read your whole network
320-
state.
321-
322-
## Development
323-
324-
```bash
325-
# Backend (Go; serves app/dist via go:embed)
326-
cd server-go
327-
cp ../app/dist internal/staticspa/dist -r # the embedded dist is never tracked
328-
go build -o netpulse ./cmd/netpulse && DEMO_MODE=1 ./netpulse
329-
330-
# Frontend (dev server with proxy)
331-
cd app
332-
npm install
333-
npm run dev
334-
335-
# Tests
336-
cd server-go && go test ./...
337-
```
338-
339254
## Big thanks
340255

341256
NetPulse wouldn't exist without [OpenWrt](https://openwrt.org/). The whole

‎web/features.html‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,7 @@ <h3 data-i18n="featuresPage.topologyTitle">Topología en vivo</h3>
153153
<li data-i18n="featuresPage.topologyL2">Hipervisores con contenedores anidados visibles</li>
154154
<li data-i18n="featuresPage.topologyL3">Animación de tráfico y estado de enlaces</li>
155155
<li data-i18n="featuresPage.topologyL4">Modo edición: arrastra los nodos y guarda tu layout</li>
156+
<li data-i18n="featuresPage.topologyL5">Etiqueta de evidencia en cada enlace: LLDP, FDB, atribución por device o override manual</li>
156157
</ul>
157158
<span class="feature-status available" data-i18n="featuresPage.statusAvailable">Disponible</span>
158159
</div>
@@ -163,9 +164,10 @@ <h3 data-i18n="featuresPage.topologyTitle">Topología en vivo</h3>
163164
<h3 data-i18n="featuresPage.devicesTitle">Dispositivos</h3>
164165
<p data-i18n="featuresPage.devicesP">Cada cliente clasificado automáticamente por patrones de hostname y OUI, con banda, señal en dBm, primer visto y el router o puerto al que habla.</p>
165166
<ul class="feature-list">
166-
<li data-i18n="featuresPage.devicesL1">Clasificación por tipo: ordenador, móvil, IoT, cámara, consola...</li>
167+
<li data-i18n="featuresPage.devicesL1">Clasificación por tipo: ordenador, móvil, IoT, cámara, aspirador, videoportero, aire acondicionado, caldera, placa SBC...</li>
167168
<li data-i18n="featuresPage.devicesL2">Banda (2.4 GHz / 5 GHz / cable) y señal</li>
168169
<li data-i18n="featuresPage.devicesL3">Estado online/offline y first-seen</li>
170+
<li data-i18n="featuresPage.devicesL4">Alertas de desconexión opt-in: marca un cliente y recibe un push urgente cuando se cae de verdad</li>
169171
</ul>
170172
<span class="feature-status available" data-i18n="featuresPage.statusAvailable">Disponible</span>
171173
</div>
@@ -246,6 +248,7 @@ <h3 data-i18n="featuresPage.wireguardTitle">WireGuard</h3>
246248
<li data-i18n="featuresPage.wireguardL1">Estado de cada peer y tiempo desde el último handshake</li>
247249
<li data-i18n="featuresPage.wireguardL2">RX/TX acumulado por túnel</li>
248250
<li data-i18n="featuresPage.wireguardL3">Visualización del túnel desde Internet hasta el gateway</li>
251+
<li data-i18n="featuresPage.wireguardL4">Eventos de conexión y desconexión en el registro, con la duración de la sesión</li>
249252
</ul>
250253
<span class="feature-status available" data-i18n="featuresPage.statusAvailable">Disponible</span>
251254
</div>
@@ -267,11 +270,12 @@ <h3 data-i18n="featuresPage.adguardTitle">AdGuard Home</h3>
267270
<div class="card feature reveal">
268271
<svg viewBox="0 0 24 24" fill="none" stroke="rgb(var(--warn))" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>
269272
<h3 data-i18n="featuresPage.alertsTitle">Alertas</h3>
270-
<p data-i18n="featuresPage.alertsP">Seis categorías con urgencia por categoría: temperatura, firmware disponible, nuevo dispositivo, handshake WireGuard, puerto de red y eventos de roaming. Feed en la campana y notificaciones Web Push.</p>
273+
<p data-i18n="featuresPage.alertsP">Alertas categorizadas como router, internet, clientes, señal, VPN y sistema, cada una con su nivel de urgencia. Feed persistente con resolución automática, Web Push nativo y alertas de desconexión por dispositivo que activas desde el editor del cliente.</p>
271274
<ul class="feature-list">
272275
<li data-i18n="featuresPage.alertsL1">Feed persistente con resolución automática</li>
273276
<li data-i18n="featuresPage.alertsL2">Web Push nativo VAPID sin terceros</li>
274277
<li data-i18n="featuresPage.alertsL3">Sugerencias de acción en alertas de puerto</li>
278+
<li data-i18n="featuresPage.alertsL4">Canales extra: ntfy, Telegram y webhooks salientes (solo alertas urgentes)</li>
275279
</ul>
276280
<span class="feature-status available" data-i18n="featuresPage.statusAvailable">Disponible</span>
277281
</div>
@@ -298,6 +302,7 @@ <h3 data-i18n="featuresPage.settingsTitle">Ajustes</h3>
298302
<li data-i18n="featuresPage.settingsL1">Usuarios con roles y bcrypt</li>
299303
<li data-i18n="featuresPage.settingsL2">Test de velocidad WAN real, ejecutado desde el servidor</li>
300304
<li data-i18n="featuresPage.settingsL3">Auto-actualización con changelog</li>
305+
<li data-i18n="featuresPage.settingsL4">Integraciones: publicador MQTT/Home Assistant, servidor MCP, tokens de API, HTTPS</li>
301306
</ul>
302307
<span class="feature-status available" data-i18n="featuresPage.statusAvailable">Disponible</span>
303308
</div>

0 commit comments

Comments
 (0)