How to Troubleshoot Token Usage in Egonex AI: First Run vs Incremental Updates

Egonex AI generates a one-time access token in vite.config.ts when you launch the development dashboard, requiring the ?token= query parameter on every request; after incremental updates or server restarts, a new token invalidates previous URLs, causing 403 Forbidden errors until you use the freshly printed URL from the terminal.

The Egonex-AI/Understand-Anything repository secures its development dashboard using a lightweight token-gating mechanism implemented directly in the Vite configuration. Understanding how this access token behaves during your initial setup versus after incremental code changes is essential to avoid authentication errors when visualizing knowledge graphs.

How the Token System Works

Token Generation in vite.config.ts

When you execute pnpm dev:dashboard, the Vite configuration file at understand-anything-plugin/packages/dashboard/vite.config.ts generates a cryptographically random string stored in the ACCESS_TOKEN variable. The server immediately prints a URL to the terminal that embeds this token:

🔑  Dashboard URL: http://127.0.0.1:5173/?token=9f7c2b1e6a...

This URL must be used exactly as printed, as the token is not persisted to disk or environment variables.

Middleware Validation Logic

The same configuration file injects a middleware function that intercepts every HTTP request before Vite handles it. The validation logic checks the query string using url.searchParams.get("token") and compares it against the runtime ACCESS_TOKEN variable:

if (url.searchParams.get("token") !== ACCESS_TOKEN) {
  sendJson(res, 403, { error: "Forbidden: missing or invalid token" });
  return;
}

If the values mismatch, the server returns a 403 Forbidden response. This enforcement applies to all endpoints, including static file serving and the /file-content.json API that provides raw source data to the dashboard.

First Run vs Incremental Updates

Fresh Server Start (First Run)

During the first run of pnpm dev:dashboard, the system creates a brand-new ACCESS_TOKEN. If you attempt to access http://127.0.0.1:5173/ without the ?token= parameter, the middleware rejects the request with a 403 error. The dashboard UI displays a localized error message defined in understand-anything-plugin/packages/dashboard/src/locales/en.ts under the tokenGate key, prompting you to provide the correct URL from the terminal.

Post-Update Restarts (Incremental Updates)

After you modify source code and restart the development server, a new token is generated. Browser tabs that were open with the previous token will suddenly receive 403 errors upon refresh because the ACCESS_TOKEN variable has changed in the new process. This is the most common source of confusion during incremental development cycles.

To resolve this, copy the new dashboard URL printed in the terminal after the restart, or manually update the token parameter in your browser’s address bar to match the new value.

Hot Module Replacement (HMR) vs Full Restart

When Vite performs Hot Module Replacement (HMR) without a full server restart, the original ACCESS_TOKEN persists in memory, and existing browser tabs continue to function. However, if you terminate the process (Ctrl+C) and run pnpm dev:dashboard again, the token regenerates, breaking existing sessions.

Troubleshooting Common Token Issues

• Missing Query Parameter: Ensure your URL includes ?token= followed by the exact string printed in the terminal. Accessing the root path alone always returns 403.

• Token Mismatch After Restart: Each server instance generates a unique token. If you see 403 errors after updating code, you are likely using a stale URL from a previous session.

• Multiple Terminal Instances: Running two dashboard servers simultaneously creates two different ACCESS_TOKEN values. Requests will only succeed when sent to the server instance that generated the token in the URL.

• Reverse Proxy Stripping: If you run the dashboard behind NGINX or another proxy, ensure the configuration forwards the full query string. Stripping parameters removes the token, causing 403 errors on every request.

• Browser Cache: Clear your browser cache or open an incognito window to ensure you are not loading a stale HTML file that references outdated resource URLs.

Implementation Examples

Starting the Development Server

Run the following command from the repository root:

pnpm install
pnpm dev:dashboard

Wait for the terminal output showing the dashboard URL, then open that exact link in your browser.

Handling Incremental Updates

After editing files such as src/utils/layout.ts or src/components/GraphView.tsx:

# Save your changes, then restart the server

pnpm dev:dashboard

Look for the new token in the terminal output:

🔑  Dashboard URL: http://127.0.0.1:5173/?token=3a8f9e2b...

Update your browser’s address bar to use this new token to avoid 403 errors.

Configuring NGINX with Token Preservation

If proxying the dashboard, ensure the query string passes through:

location / {
    proxy_pass http://localhost:5173;
    proxy_set_header Host $host;
    # Preserve the query string including ?token=

    proxy_set_header X-Original-URI $request_uri;
}

Key Source Files

• understand-anything-plugin/packages/dashboard/vite.config.ts – Contains the ACCESS_TOKEN generation and the middleware validation logic using sendJson().
• understand-anything-plugin/packages/dashboard/src/locales/en.ts – Defines the tokenGate error message displayed when authentication fails.
• understand-anything-plugin/packages/dashboard/src/index.ts – Entry point that initializes the dashboard application and expects the token-validated environment.
• README.md – Provides high-level setup instructions and the pnpm dev:dashboard command reference.

Summary

• The dashboard generates a one-time access token in vite.config.ts at server startup.
• Every request must include the exact ?token= value printed in the terminal.
• Incremental updates require a server restart, which generates a new token and invalidates old browser URLs.
• 403 Forbidden errors almost always indicate a stale or missing token parameter.
• Reverse proxies must preserve query strings to allow token validation to function.

Frequently Asked Questions

Why does my dashboard return 403 after restarting the dev server?

The ACCESS_TOKEN variable is regenerated every time you run pnpm dev:dashboard. Your browser tabs from the previous session contain the old token value, which no longer matches the new server instance. Copy the fresh URL from the terminal to restore access.

Can I disable the token gate for local development?

Yes, but it is not recommended for networks beyond localhost. Comment out the middleware check in understand-anything-plugin/packages/dashboard/vite.config.ts that calls sendJson(res, 403, ...) when the token mismatches. Re-enable this protection before exposing the server to any public interface.

How do I resolve token issues when running behind a reverse proxy?

Ensure your proxy configuration forwards the full query string to the upstream Vite server. NGINX users should verify that proxy_pass includes the $request_uri or that explicit rules do not strip the ?token= parameter. The middleware requires access to url.searchParams.get("token") to validate requests.

Where is the access token stored persistently?

The token is not stored persistently. It exists only as a runtime variable (ACCESS_TOKEN) within the Node.js process running the Vite dev server. This ephemeral design ensures that each development session has a unique, unpredictable credential that expires when the process terminates.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}