Day 2 Operations: Using MeshOptixIQ

How to interact with the Network Reasoner once deployed.

2. Configuration

MeshOptixIQ is configured via environment variables and YAML files.

Environment Variables

Variable	Default	Description
NEO4J_URI	bolt://localhost:7687	Neo4j connection string
NEO4J_PASSWORD	(empty)	Database password
GRAPH_BACKEND	neo4j	`neo4j` or `postgres`
API_KEY	required	API key for query endpoints — the server will not start without this set
MESHOPTIXIQ_LICENSE_KEY	(unset)	License key — required by the API server only; CLI and MCP inherit the plan from the API
MESHOPTIXIQ_API_URL	http://localhost:8000	Local API server URL used by the CLI and MCP server for license plan resolution

Inventory Configuration (inventory.yaml)

Define static devices to collect from:

devices:
  - hostname: core-sw-01
    host: 192.168.1.1
    vendor: cisco_ios
    username: admin
    password_env: DEVICE_PASSWORD  # references env var
    
  - hostname: edge-rtr-01
    host: 10.0.0.1
    vendor: juniper_junos
    username: netops
    key_file: /root/.ssh/id_rsa    # SSH key auth

Discovery Configuration (discovery.yaml)

Enable active scanning of IP ranges:

discovery:
  cidrs:
    - 10.0.0.0/24
    - 192.168.1.0/24
  scan_ports: [22]
  exclude:
    - 10.0.0.1
  credentials:
    username: admin
    password_env: DEVICE_PASSWORD

3. Data Model

The reasoning engine normalizes all vendor data into a standard graph schema (v1).

Device

Physical or virtual network appliance (Router, Switch, Firewall).

Interface

Physical port or logical interface (VLAN, Loopback).

IPAddress

IPv4 or IPv6 address assigned to an interface.

Subnet

Layer-3 network derived from IP/Mask (e.g., 192.168.1.0/24).

Endpoint

Connected host identified by MAC + IP pair.

Key Relationships

(Device)-[:HAS_INTERFACE]->(Interface)
(Interface)-[:CONNECTED_TO]->(Interface) (via LLDP/CDP)
(Interface)-[:HAS_IP]->(IPAddress)
(IPAddress)-[:IN_SUBNET]->(Subnet)
(Endpoint)-[:USES_MAC]->(MAC)-[:LEARNED_ON]->(Interface)

4. Running the Pipeline

# Run ingestion with discovery enabled
docker run --env-file .env \
  -v $(pwd)/configs:/app/configs \
  meshoptixiq/network-discovery:latest

Interacting with the API

The primary interface for automation and tools is the REST API.

Listing Available Queries

GET /api/v1/queries

Returns a list of all registered queries, their descriptions, and required parameters.

Executing a Query

POST /api/v1/queries/{query_name}/execute
Content-Type: application/json

{
  "parameters": {
    "device_name": "switch-01",
    "cidr": "10.0.0.0/24"
  }
}

Using the CLI (`meshq`)

For ad-hoc troubleshooting, use the bundled CLI tool (available in the Docker container or as a standalone binary).

# Find a device by MAC
meshq endpoints locate --mac "00:50:56:AB:CD:EF"
# OR via Docker
docker run meshoptixiq/network-discovery meshq endpoints locate ...

# Analyze blast radius of a subnet
meshq blast-radius subnet --cidr "192.168.10.0/24"

Web UI

MeshOptixIQ ships a built-in React web interface served at http://<host>:8000. No separate deployment is required. After connecting with your API key you have access to:

App Shell

Top Bar — backend health indicator, SSE live badge, demo-mode pill, notifications bell, user identity menu
Command Palette — press Cmd+K / Ctrl+K from any page; smart routing by IP, MAC, hostname, or page name
Inspector Drawer — right-side panel that opens when you click a device row or topology node; shows 6 tabs (Summary, Interfaces, Neighbors, Endpoints, Firewall, History)
Grouped sidebar navigation — seven sections: Overview, Observe, Assets, Security, Operations, Workbench, System

Key Pages

Route	Page	What it does
`/topology`	Topology	Force-directed graph; focus mode for 200+ device networks; blast radius and path overlays
`/devices`	Device Inventory	Virtualized table, vendor filters, Inspector Drawer integration, JSON export
`/endpoints`	Endpoint Search	Locate hosts by IP or MAC; inventory table mode; orphaned endpoints hygiene
`/subnets`	Subnets & IPAM	Browse IPs by CIDR or by device; VRF filter; orphaned IPs hygiene
`/firewall`	Firewall Policies	Search rules by device or zone pair; deny-rules summary
`/path-analysis`	Path Analysis	Trace traffic through firewall chains; overlay matched path on topology
`/blast-radius`	Blast Radius	Simulate device / VLAN / subnet failure; overlay impacted nodes on topology
`/history`	Change Center	Trend charts, snapshot diff, what-if simulation (Pro+)
`/automation`	Automation	Download Ansible dynamic inventory (JSON / INI); NetBox dry-run sync
`/admin`	Admin	Runtime config, RBAC editor, snapshots, support bundle copy

See Chapter 7 of the User Guide for the full Web Interface reference including the Command Palette, Inspector Drawer, topology overlays, and all page-level details.