# How to Deploy Understand Anything to a Server: Complete Production Guide

> Deploy Understand Anything to a server with our production guide. Install skills, generate knowledge graphs, build the dashboard, and serve static assets for a complete setup.

- Repository: [Yuxiang Lin/Understand-Anything](https://github.com/Lum1104/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-05

---

**Deploy Understand Anything by installing platform skills via the [`install.sh`](https://github.com/Lum1104/Understand-Anything/blob/main/install.sh) script, generating knowledge graphs with the `/understand` command, building the dashboard with `pnpm build`, and serving the static assets alongside the JSON data files.**

Understand Anything is an AI-powered codebase analysis tool that generates interactive knowledge graphs for complex projects. This guide covers how to deploy Understand Anything to a server for production use, walking through the three-phase deployment process from the Lum1104/Understand-Anything repository.

## Prerequisites

Before starting, ensure your environment meets these requirements:

- **Node.js** version 22 or higher
- **pnpm** package manager
- **Git** for repository cloning
- Access to a command line with bash support

## Phase 1: Install Platform Skills

The first step in deploying Understand Anything is installing the skill set for your AI-coding platform. The repository provides an installer script at [`install.sh`](https://github.com/Lum1104/Understand-Anything/blob/main/install.sh) that handles both fresh installations and updates.

The script clones the repository into `~/.understand-anything/repo` and creates appropriate symlinks for your specific platform (Claude Code, Codex, VS Code + Copilot, etc.). According to the source code in [`install.sh`](https://github.com/Lum1104/Understand-Anything/blob/main/install.sh) (lines 1-14, 21-23), the installer can be run directly from the web:

```bash
curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash -s <platform>

```

Replace `<platform>` with your target environment (e.g., `codex`, `vscode`, `claude`). This command sets up the necessary symlinks so that your AI assistant can invoke the `/understand` command natively.

## Phase 2: Generate the Knowledge Graph

Once the skills are linked, you must generate the knowledge graph data that powers the dashboard. This phase is platform-agnostic and creates a set of JSON files under the `.understand-anything/` directory in your target codebase.

Navigate to your target project and run the analysis command:

```bash
cd /path/to/your/codebase
understand

```

This generates the following essential files consumed by the dashboard:
- [`.understand-anything/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json)
- [`.understand-anything/domain-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/domain-graph.json)
- [`.understand-anything/diff-overlay.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/diff-overlay.json)
- [`.understand-anything/config.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/config.json)

These JSON files form the data layer that the dashboard visualizes, and they must be accessible to the frontend in production.

## Phase 3: Build and Serve the Dashboard

### Build the Production Bundle

The dashboard lives in the `@understand-anything/dashboard` package within `understand-anything-plugin/packages/dashboard/`. As defined in the [`package.json`](https://github.com/Lum1104/Understand-Anything/blob/main/package.json) (lines 6-11), the build script compiles TypeScript and runs a Vite production build:

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

```

The output is placed in `understand-anything-plugin/packages/dashboard/dist/`. This directory contains pure static files (HTML, CSS, JS) ready for deployment.

### Static Hosting Options

Because the built assets are static, you can serve them using any HTTP server or deploy to static-hosting services like GitHub Pages, Vercel, Netlify, or Cloudflare Pages. For local testing or lightweight servers:

```bash
npx serve -s understand-anything-plugin/packages/dashboard/dist -l 8080

```

The dashboard will be reachable at `http://127.0.0.1:8080/`. Note that the Vite development server is **not** used in production; instead, the production bundle serves the UI directly.

### Expose the JSON Endpoints

The dashboard expects the knowledge-graph files to be reachable under the same origin at specific paths: [`/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main//knowledge-graph.json), [`/domain-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main//domain-graph.json), [`/diff-overlay.json`](https://github.com/Lum1104/Understand-Anything/blob/main//diff-overlay.json), [`/config.json`](https://github.com/Lum1104/Understand-Anything/blob/main//config.json), and [`/file-content.json`](https://github.com/Lum1104/Understand-Anything/blob/main//file-content.json).

You have two options for serving these in production:

**Option A: Copy JSON files to the dist directory**
Copy the generated files from your target codebase into the dashboard's `dist` folder so they are served as static assets:

```bash
cp /path/to/codebase/.understand-anything/*.json \
   understand-anything-plugin/packages/dashboard/dist/

```

**Option B: Run a Node server with middleware**
Mirror the middleware logic from the Vite development configuration (found in [`vite.config.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/vite.config.ts), lines 85-90 and 98-105). The `serve-knowledge-graph` plugin in the Vite config validates a one-time token and sanitizes file paths. For production, you can implement similar logic in a lightweight Node.js server, though the token check can be omitted for publicly hosted static sites since the assets are already reachable.

## Complete Deployment Workflow

Here is the full end-to-end deployment process:

```bash

# 1️⃣ Clone the repository

git clone https://github.com/Lum1104/Understand-Anything.git
cd Understand-Anything

# 2️⃣ Install platform skills (replace <platform> as needed)

curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash -s <platform>

# 3️⃣ Install Node dependencies

pnpm install

# 4️⃣ Generate knowledge graph from your target codebase

cd /path/to/target/codebase
understand

# 5️⃣ Build the dashboard

cd /path/to/Understand-Anything
pnpm --filter @understand-anything/dashboard build

# 6️⃣ Copy generated graph files to the dist folder

cp /path/to/target/codebase/.understand-anything/*.json \
   understand-anything-plugin/packages/dashboard/dist/

# 7️⃣ Deploy using a static server

npx serve -s understand-anything-plugin/packages/dashboard/dist -l 8080

```

## Deploying to GitHub Pages

To deploy the dashboard to GitHub Pages, use an orphan branch strategy:

```bash

# From the repository root after a successful build

git checkout --orphan gh-pages
git reset --hard
git rm -rf .
mv understand-anything-plugin/packages/dashboard/dist/* .
git add .
git commit -m "Deploy dashboard"
git push -u origin gh-pages --force

```

The site will be available at `https://<username>.github.io/Understand-Anything/`. Because the JSON files are stored in the same folder as the built assets, the dashboard can fetch them without additional server logic.

## Summary

- **Install skills** using the [`install.sh`](https://github.com/Lum1104/Understand-Anything/blob/main/install.sh) script, which clones to `~/.understand-anything/repo` and creates platform-specific symlinks
- **Generate graphs** by running the `/understand` command in your target codebase to create JSON files in `.understand-anything/`
- **Build the dashboard** using `pnpm --filter @understand-anything/dashboard build`, outputting to the `dist` directory
- **Serve statically** by copying the JSON files into `dist/` and hosting with any HTTP server or static platform
- **Configure endpoints** to ensure [`/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main//knowledge-graph.json) and related files are accessible at the root path

## Frequently Asked Questions

### What are the system requirements for deploying Understand Anything?

Understand Anything requires **Node.js version 22 or higher**, the **pnpm** package manager, and a bash-compatible shell. The build process relies on Vite for bundling and TypeScript for compilation. The generated knowledge graphs are served as static JSON files, so the production server itself has minimal runtime requirements beyond serving static assets.

### Can I deploy Understand Anything without using the Vite development server?

**Yes.** In production deployments, you should **not** use the Vite development server. Instead, run the production build command (`pnpm --filter @understand-anything/dashboard build`) and serve the resulting static files from the `dist` directory using any HTTP server (such as `npx serve`, Nginx, or Apache) or deploy to static hosting platforms like GitHub Pages or Vercel. The Vite server is intended only for local development.

### How do I update my Understand Anything installation after the initial deployment?

Run the install script again to update the core repository. The [`install.sh`](https://github.com/Lum1104/Understand-Anything/blob/main/install.sh) script (as implemented in lines 21-23 of the source) handles both fresh installs and updates by pulling the latest changes into `~/.understand-anything/repo`. After updating the core code, rebuild the dashboard using the build command and replace the static assets on your server with the new `dist` contents.

### Is the knowledge graph data publicly accessible when deployed to a static server?

**By default, yes.** When you copy the JSON files into the `dist` directory for static hosting, they become publicly accessible at their respective URLs ([`/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main//knowledge-graph.json), etc.). If you require access control, you must implement a server-side middleware solution (similar to the token validation logic in [`vite.config.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/vite.config.ts), lines 85-90) rather than using pure static hosting.