Quick Start

Marrow has no graphical drag-and-drop canvas. The editing interface is a conversation: an operator describes a network, an autonomous vertical AI agent authors and validates the topology YAML, and the operator reviews the compiled interactive diagram.

Follow these steps to configure your agent, clone Marrow, and compile your first topology.

Step 1: Use Any Vertical AI Agent of Your ChoiceCopy Anchor Link

Marrow is designed to work with any vertical AI agent or autonomous coding assistant. You describe your network requirements in natural language; the agent handles schema authoring, icon lookups, and compiler verification.

Choose any vertical agent or coding environment of your choice:

• Terminal CLI Agents: Claude Code, Aider, or terminal shell scripts.
• Agentic IDEs & Extensions: Cursor, Windsurf, Antigravity, Cline, or GitHub Copilot.
• Autonomous Platforms & Open Lists: OpenHands, Devin, or any assistant from curated registries like Awesome AI Agents (e2b) and Awesome LLM Agents.

How agents read MarrowCopy Anchor Link

Marrow includes operational instructions in the repository root:

• AGENTS.md: Defines compiler modes, invariant rules, and command references.
• .agents/skills/marrow-topology/: Domain skill covering schema validation, icon queries, link semantics, and geometric collision checks.

When you open the Marrow repository in your vertical agent, it reads AGENTS.md automatically.

Step 2: Clone Marrow and Run SetupCopy Anchor Link

Marrow requires Node.js 24 or newer. It operates completely offline with zero database or external rendering servers.

1. Clone the repositoryCopy Anchor Link

git clone https://github.com/raiz-toff/Marrow.git
cd Marrow

2. Run the setup scriptCopy Anchor Link

Execute the interactive setup command:

npm run setup

The script runs six automated verification steps:

1. Validates Node.js version ($\ge 24$).
2. Installs workspace dependencies via npm install.
3. Compiles the TypeScript packages and the offline client runtime bundle.
4. Installs verified vendor icon packs (Cisco, Affinity, AWS, Azure, GCP).
5. Prompts for optional organization branding in marrow.config.yaml.
6. Compiles a test diagram end-to-end to verify the toolchain.

For headless CI/CD pipelines or container builds, use the non-interactive flag:

npm run setup -- --yes

Step 3: Prompt Your Agent (or Author YAML)Copy Anchor Link

Once your vertical agent is running inside the Marrow workspace, describe your network in plain language. The agent executes the understand → author → validate → see loop automatically.

Example prompts for your agentCopy Anchor Link

Create a 2-spine 4-leaf EVPN datacenter topology in input/dc-fabric.yaml.
Use Cisco Nexus 9000 switches with 100G routed uplinks between leaves and spines.
Add an about section documenting our maintenance window and runbook link.
Validate the schema and generate a snapshot PNG for review.

Read our branch router config snippet and create input/branch-office.yaml.
Group devices into an edge zone and LAN zone.
Connect the WAN router to an HA firewall pair, and link down to access switches.
Validate the file and fix any diagnostic warnings.

Generate an AWS transit gateway network connecting two VPCs (Production and Staging).
Use official AWS EC2, Transit Gateway, and VPC icons from the aws icon pack.
Set the layout density to standard and theme to dark.

Authoring by handCopy Anchor Link

If authoring YAML directly without an agent, create input/network.yaml:

marrow: 2
name: Core Spine-Leaf Fabric
author: NetOps Architecture Team
theme: dark
density: standard

# Documentation modal and watermark attribution
about:
  Architecture: 5-stage Clos data center fabric with EVPN-VXLAN overlay.
  Maintenance: Bi-weekly maintenance window Tuesdays 02:00-04:00 UTC.
  Runbook: https://wiki.internal.net/runbooks/spine-leaf-failover

zones:
  - id: dc-fabric
    name: Primary Fabric
    accent: "#3b82f6"

devices:
  - id: spine-01
    name: Spine Switch 1
    icon: cisco/switches/layer-3-switch
    tier: core
    zone: dc-fabric
    mgmt_ip: 10.0.0.1

  - id: spine-02
    name: Spine Switch 2
    icon: cisco/switches/layer-3-switch
    tier: core
    zone: dc-fabric
    ha_pair_with: spine-01
    mgmt_ip: 10.0.0.2

  - id: leaf-01
    name: Leaf Switch 1
    icon: cisco/switches/workgroup-switch
    tier: distribution
    zone: dc-fabric
    mgmt_ip: 10.0.1.1
    interfaces:
      - name: Eth1/1
        description: Uplink to Spine 1
      - name: Eth1/2
        description: Uplink to Spine 2

links:
  - from: spine-01:Eth1/1
    to: leaf-01:Eth1/1
    mode: routed
    speed: 100G
    protocol: ebgp

  - from: spine-02:Eth1/1
    to: leaf-01:Eth1/2
    mode: routed
    speed: 100G
    protocol: ebgp

Step 4: Discover Vendor IconsCopy Anchor Link

Never guess icon identifiers. Search the catalog of ~2,850 verified vendor icons before defining devices:

# Search for generic switch and router types
npm run icons search switch router firewall

# Search specific vendor hardware
npm run icons search "cisco nexus" "layer 3 switch"

Icon identifiers follow <pack>/<category>/<name>.

Step 5: Validate and CompileCopy Anchor Link

Marrow enforces strict schema verification and geometric collision detection before compiling HTML.

1. Validate schema and layoutCopy Anchor Link

npm run validate input/network.yaml

The validator checks:

• Strict schema syntax and type constraints.
• Uniqueness of device identifiers.
• Resolution of link ports and device endpoints.
• HA pairing constraints (ha_pair_with).
• Collision gates to guarantee zero overlapping nodes or zones.

To produce machine-readable JSON for agents, add --json:

npm run validate input/network.yaml --json

2. Verify visual output (snapshot)Copy Anchor Link

Generate a headless Chromium rendering to inspect visual hierarchy and edge routing:

npm run snapshot input/network.yaml -o output/network.png

Vision-enabled agents inspect this image to confirm tier alignment, zone bounds, and label placement.

3. Compile standalone HTMLCopy Anchor Link

Compile the final production diagram:

npm run build input/network.yaml -o dist/network.html

The compiled file (dist/network.html) is 100% self-contained. It contains inlined SVG icons, theme styles, and the interactive pan/zoom canvas client. It opens offline without network access:

open dist/network.html

Step 6: Live Development PreviewCopy Anchor Link

During active authoring, start the hot-reloading development preview server:

npm run dev -- input/network.yaml

Open http://127.0.0.1:5200 in your browser. Every change saved to input/network.yaml updates the canvas instantly over a local WebSocket.

Step 7: Essential CustomizationsCopy Anchor Link

About This Diagram ModalCopy Anchor Link

Define an about: dictionary in your topology YAML. The compiled diagram renders an About this diagram button in the command bar:

about:
  Topology: Spine-Leaf EVPN Data Center Fabric
  Owner: NetOps Architecture Team
  Contact: netops@example.com

Clicking the button opens an engineering document dialog showing your custom markdown text alongside Marrow's watermark credit.

Embedding and Dashboard Display ModesCopy Anchor Link

Marrow supports iframe embedding into monitoring dashboards, internal wikis, and portal pages. Use URL hash flags or HTML attributes:

Example iframe embedding code:

<iframe
  src="network.html#embed=true&controls=off"
  width="100%"
  height="600px"
  style="border: 1px solid #27272a; border-radius: 8px;"
/>

Layout Density PresetsCopy Anchor Link

Adjust node sizing and layout compactness with the density: setting:

density: compact   # 48px nodes, tight spacing. Optimal for 500+ device campus networks.
density: standard  # 64px nodes, 48px gap (default).
density: spacious  # 80px nodes, 64px gap. Optimal for executive presentations.

Engineering Title BlocksCopy Anchor Link

Add a formal blueprint title block to your canvas with title_block::

title_block:
  title: Spine-Leaf EVPN Fabric
  drawing_number: DWG-NET-2026-004
  revision: Rev 3.2
  drawn_by: NetOps Architecture Team
  approved_by: Lead Network Architect
  date: 2026-10-19

Common Diagnostic CodesCopy Anchor Link

Next StepsCopy Anchor Link

• Authoring Topologies: Complete guide to interfaces, custom fields, and link protocols.
• Zones & Tiers: Hierarchy design, containment zones, and layout flow.
• The Golden Loop: Step-by-step operating guide for AI agents.
• Schema Reference: Complete schema specification.