# How to Run the Egonex-AI Dashboard Locally: Complete Development Setup

> Learn how to run the Egonex-AI dashboard locally. Follow our step-by-step guide to clone, install dependencies, build the core, and launch the UI for seamless development.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-22

---

**Clone the Egonex-AI/Understand-Anything repository, install dependencies with pnpm ≥ 10, build the core package with `pnpm --filter @understand-anything/core build`, then launch the dashboard using `GRAPH_DIR=../.. npx vite --host 127.0.0.1 --open` to serve the UI on `http://127.0.0.1:5173`.**

The Egonex-AI Understand-Anything dashboard is a React-based visualization tool that displays knowledge graphs generated by the core analysis engine. To run the Egonex-AI dashboard locally for development purposes, you must build the core package first to generate required TypeScript types, then serve the UI using Vite with the `GRAPH_DIR` environment variable pointing to a project containing a `.understand-anything` graph folder. This setup enables hot-reload development while the dashboard proxies graph data requests to your local filesystem.

## Prerequisites and System Requirements

Before starting, ensure your environment meets the requirements specified in the monorepo configuration. You need **Node.js ≥ 22** and **pnpm ≥ 10** installed globally to handle the workspace dependencies and lock-file format. Additionally, you must have a project directory containing a [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) file, which the dashboard will visualize.

## Step-by-Step Local Development Setup

Follow these steps to build and run the dashboard from the source code.

### Clone the Repository and Install Workspace Dependencies

First, clone the monorepo and install the shared dependencies at the root level. According to the README quick-start section (lines 48-55), this establishes the workspace foundation.

```bash
git clone https://github.com/Egonex-AI/Understand-Anything.git
cd Understand-Anything
pnpm install

```

This creates the necessary lock-file and installs shared tooling across the monorepo.

### Build the Core Package

The dashboard depends on compiled types and schemas from the core package. As documented in the `understand-dashboard` skill file (lines 22-33), you must build the core before running the UI.

```bash
pnpm --filter @understand-anything/core build

```

This command generates the TypeScript output required by the dashboard's import statements.

### Install Dashboard-Specific Dependencies

Navigate to the dashboard package directory and install its local dependencies using the frozen lock-file to ensure exact versions of React, Vite, Tailwind CSS v4, and Zustand.

```bash
cd understand-anything-plugin/packages/dashboard
pnpm install --frozen-lockfile

```

The dependencies are declared in [`understand-anything-plugin/packages/dashboard/package.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/package.json), which includes scripts for `dev` and `build` operations.

### Launch the Vite Development Server

Set the `GRAPH_DIR` environment variable to point to the folder containing your `.understand-anything` graph data, then start the Vite dev server. As specified in the skill documentation (lines 73-82), use the following command:

```bash
GRAPH_DIR=../../.. npx vite --host 127.0.0.1 --open

```

By default, this serves the dashboard on `http://127.0.0.1:5173` and opens your browser automatically. The `GRAPH_DIR` path is relative to the dashboard directory and should target the root of the project you want to visualize.

## Key Configuration and Environment Variables

The dashboard relies on specific environment variables to locate graph data and configure the development server.

- **`GRAPH_DIR`**: Required. Points to the directory containing the [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) file. The server proxies [`/file-content.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main//file-content.json) requests to this location.
- **`VITE_PORT`**: Optional. Changes the default development server port from `5173`.
- **`VITE_OPEN`**: Optional. Set to `false` to prevent the browser from opening automatically on server start.

When running, the dashboard injects an access token automatically to validate requests between the UI and the local graph data, handled by the **TokenGate** component.

## Core Architecture and Source Files

Understanding the key source files helps navigate the codebase for custom development.

- **[`understand-anything-plugin/packages/dashboard/src/App.tsx`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/src/App.tsx)**: The entry component that wires the layout, graph view, and side panels.
- **[`understand-anything-plugin/packages/dashboard/src/store.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/src/store.ts)**: Implements the Zustand store holding graph state, search queries, selected nodes, and tour data.
- **[`understand-anything-plugin/packages/dashboard/src/components/TokenGate.tsx`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/src/components/TokenGate.tsx)**: Validates the access token before rendering the graph view, ensuring secure access to the local data.
- **[`understand-anything-plugin/packages/dashboard/src/components/GraphView.tsx`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/src/components/GraphView.tsx)**: Renders the ELK-based force-directed graph, handling node interactions and hover tooltips.
- **[`understand-anything-plugin/skills/understand-dashboard/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand-dashboard/SKILL.md)**: Contains the canonical commands used to launch the dashboard, serving as the source of truth for the development workflow.

## Development Workflow Tips

For efficient local development, run the core `/understand` command after code changes to regenerate the [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json) file; the Vite dev server automatically picks up these updates without requiring a restart. If the graph layout appears broken, check the browser console for ELK errors, which are surfaced through the [`src/components/WarningBanner.tsx`](https://github.com/Egonex-AI/Understand-Anything/blob/main/src/components/WarningBanner.tsx) component. To create a production build, run `pnpm --filter @understand-anything/dashboard build`, which outputs an optimized static bundle to the `dist/` directory.

## Summary

- **Install** Node.js ≥ 22 and pnpm ≥ 10, then clone the Egonex-AI/Understand-Anything repository.
- **Build** the core package using `pnpm --filter @understand-anything/core build` before running the dashboard.
- **Configure** the `GRAPH_DIR` environment variable to point to your project folder containing [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json).
- **Launch** the development server with `GRAPH_DIR=../.. npx vite --host 127.0.0.1 --open` to serve the UI on `http://127.0.0.1:5173`.
- **Reference** the key source files in `understand-anything-plugin/packages/dashboard/src/` for UI customization and state management using Zustand.

## Frequently Asked Questions

### What are the minimum version requirements for running the dashboard locally?

You need **Node.js version 22 or higher** and **pnpm version 10 or higher** to install dependencies and run the build commands successfully. These versions ensure compatibility with the monorepo workspace configuration and the Vite build tooling.

### Why must I build the core package before starting the dashboard?

The dashboard imports TypeScript types and schema definitions from the core package. Running `pnpm --filter @understand-anything/core build` generates these compiled outputs in the core package's `dist` directory, which the dashboard's module resolution depends on. Without this step, the dashboard will fail to start due to missing type definitions.

### How do I connect the dashboard to a different project folder?

Set the `GRAPH_DIR` environment variable to the absolute or relative path of the target directory containing the `.understand-anything` folder. For example, if your project is at `/home/user/projects/my-app`, launch the server with `GRAPH_DIR=/home/user/projects/my-app npx vite --host 127.0.0.1`, ensuring the path includes the [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json) file.

### What port does the development server use by default?

The Vite development server defaults to **port 5173** on `127.0.0.1` as specified by the `--host 127.0.0.1` flag. You can override this by setting the `VITE_PORT` environment variable to your desired port number before running the launch command.