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:

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, zoom, and drill into multi-layer network views 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.

Integrations

See Plugin Authoring to write your own data source.

YAML format

name: "Simple Network"

settings:
  direction: TB
  theme: light

subgraphs:
  - id: core
    label: "Core Layer"

nodes:
  - id: rt-01
    label: "Router 01"
    type: router
    vendor: yamaha
    model: rtx3510
    parent: core

  - id: sw-01
    label: "Switch 01"
    type: l3-switch
    parent: core

links:
  - from:
      node: rt-01
      port: lan1
    to:
      node: sw-01
      port: ge-0/0/0
    bandwidth: 10G

Library

The rendering engine is also published to npm as standalone packages.

npm install shumoku

import { YamlParser, renderGraphToHtml } from 'shumoku'

const { graph } = new YamlParser().parse(yamlString)

// Interactive HTML (pan / zoom / tooltips)
const html = await renderGraphToHtml(graph, { title: 'My Network' })

Need SVG or PNG instead? Use the dedicated renderers:

import { renderGraphToSvg } from '@shumoku/renderer/static'
import { renderGraphToPng } from '@shumoku/renderer-png' // Node.js only

const svg = await renderGraphToSvg(graph)
const png = await renderGraphToPng(graph, { scale: 2 })

CLI

npx @shumoku/cli render network.yaml -o diagram.svg
npx @shumoku/cli render network.yaml -f html -o diagram.html
npx @shumoku/cli render network.yaml -f png -o diagram.png --scale 3

Playground | YAML Reference

Repository layout

apps/
  server/   Real-time monitoring platform — Bun + Hono API, SvelteKit web UI
  editor/   Visual topology designer — SvelteKit + xyflow
  cli/      Render YAML → SVG / HTML / PNG
  docs/     Documentation site (Next.js + Fumadocs)
libs/
  shumoku            All-in-one npm package
  @shumoku/*         Core engine, renderers, catalog, plugin SDK
  plugins/*          Data-source integrations
docs/                Architecture, YAML reference, plugin authoring
examples/            Sample YAML networks + a sample plugin

Each top-level directory has its own index: apps/ · libs/ · examples/.

Documentation

• Server Guide — Setup, data sources, dashboards
• YAML Reference — Full YAML syntax
• Vendor Icons — Available icons
• Playground — Try without installation
• Architecture — Monorepo overview, load pipeline, layout engine
• Plugin Authoring — Writing a DataSourcePlugin: capability mixins, data shapes, severity mapping

Development

git clone https://github.com/konoe-akitoshi/shumoku.git
cd shumoku
bun install
bun run build      # build all libraries (excludes the server app)
bun run dev        # run everything in dev mode

Common scripts: bun run test, bun run lint, bun run typecheck, bun run format. This is a Bun workspaces + Turborepo monorepo — see CONTRIBUTING.md.

Star History

Community & governance

Shumoku is an open-source project led by @konoe-akitoshi. Contributions are welcome under the AGPL-3.0 license.

• Contributing — dev setup, pull requests, DCO sign-off
• Governance — roles, decision-making, releases
• Support — community help on GitHub · Commercial support — paid implementation / integration services
• Code of Conduct · Security · Brand guidelines · Name & logo story (日本語)

License

Shumoku is free and open-source software, licensed under AGPL-3.0 (LICENSE).

For enterprise use, we provide paid commercial support and implementation services (deployment, NetBox/Zabbix integration, PoC, custom plugin development, priority handling) — separate from the open-source license, in collaboration with our commercial support partner. See COMMERCIAL_SUPPORT.md, or reach out at [email protected]. If AGPL-3.0 does not fit your use case, contact us to discuss the options.