Shumoku

Network diagrams that don't drift away from reality.

Shumoku generates readable network topology maps from structured network data.

Network diagrams should not be static drawings that slowly become outdated. They should be reproducible, updateable, and grounded in a source of truth.

Shumoku turns YAML, NetBox, LLDP, SNMP, and other topology data into diagrams that reflect how the network actually exists.

Try the playground  ·  Documentation  ·  Discord

[!NOTE] 製作者が janog58 NOC に参加中です。導入支援・技術サポートはお気軽にご相談ください。  📧 [email protected]  ·  𝕏 @shumoku_dev

Live weathermap — real-time traffic overlaid on the topology

Dashboard in production — JANOG57 NOC Live

Philosophy

Networks need maps, too.  ネットワークにも、地図が必要だ。

Network diagrams are one of the most important tools in network operations. But in many environments they are still drawn by hand, updated manually, and slowly drift away from the real network.

Shumoku starts from three principles.

1. A diagram should be readable

A topology map should make the structure of the network understandable at a glance — the relationships, layers, paths, and points of failure.

2. A diagram should be trustworthy

A diagram is only useful when it reflects reality. Shumoku generates diagrams from structured data — YAML, NetBox, LLDP, SNMP — instead of relying on manual drawing alone.

3. A diagram should be updateable

Networks change. Diagrams should be regenerated, reviewed, and maintained as part of the operational workflow.

Shumoku treats network diagrams not as static pictures, but as generated views of the network — close to the source of truth, and easy to keep that way.

→ Read the full design philosophy.

What's in the box

At its core, Shumoku is a topology generation engine — it turns structured network data into a readable diagram. Around that core, it ships ready-to-use apps:

📦 Library + CLI	The core engine — turn a network YAML into SVG / HTML / PNG, in Node or the browser	libs/shumoku
✏️ Editor	Visual topology designer built on the engine — lay out devices, modules, and cables; derive a bill of materials	apps/editor
🖥️ Server	Topology-based monitoring built on the engine — overlay live metrics and alerts on the map, build dashboards, share read-only links	apps/server

Features

• Live weathermap — Overlay real-time traffic utilization on links, color-coded by load
• Alert visualization — Show active alerts from Zabbix, Prometheus, and Grafana on topology
• Auto-generate from NetBox — Pull devices and cables from NetBox to build topology automatically
• Network discovery — Seed-crawl SNMP + LLDP to discover topology with no inventory at all
• Interactive dashboards — Pan and zoom the whole network, drawn on one page, in the browser
• 900+ vendor icons — Yamaha, Aruba, AWS, Juniper, and more — rendered at correct aspect ratios
• Shareable links — Publish topology views with a share token — no login required

Server

The server is the full platform: a Bun + Hono API with an SQLite store and a SvelteKit web UI. Run it from the published Docker image, or build from source.

See the Server Setup Guide for Docker, Kubernetes (Helm), systemd, and manual deployment.

# Published Docker image (quickest)
install -d -m 700 .shumoku
openssl rand -base64 32 > .shumoku/admin-password
chmod 600 .shumoku/admin-password
docker run -d -p 8080:8080 -v shumoku-data:/data \
  -v "$PWD/.shumoku/admin-password:/run/secrets/shumoku_admin_password:ro" \
  -e SHUMOKU_BOOTSTRAP_ADMIN_PASSWORD_FILE=/run/secrets/shumoku_admin_password \
  ghcr.io/konoe-akitoshi/shumoku:latest
# → http://localhost:8080   (add `-e DEMO_MODE=true` to preload a sample network)

# Docker Compose with an exact production version
cd apps/server && SHUMOKU_VERSION=0.1.1 docker compose up -d

# Development from source (API :8080 + web UI :5173)
bun run dev:server     # from the repo root

What you can do:

1. Create topologies — Upload YAML files or write them in the built-in editor
2. Connect data sources — Link Zabbix, Prometheus, or NetBox to pull live metrics
3. Monitor in real-time — See node status and link utilization update live over WebSocket
4. Build dashboards — Combine multiple topologies and metric widgets into custom views
5. Share — Generate public links for read-only access without authentication

Editor

The Editor is hosted on Vercel independently from the Server. Branches and pull requests receive isolated Preview deployments; merging to main updates Production. The running version, deployment channel, and commit are shown on the Editor home screen.

This is the beginning of the README. Read the rest at the original. Read the full README ↗