Operator dashboard

AI Ops Dashboard

Where it all comes together

⚙ Tabs

Show or hide any dashboard tab.

How: Toggle tabs on/off and pick the default tab. Hidden tabs stay installed and can be turned back on anytime — nothing is deleted.

Change the dashboard's color theme.

How: Pick any of the 8 themes — your choice is saved in this browser only (it doesn't change the shared default).

Data updated 10/19/2018, 6:46 PM PDT
Rendered 6/19/2026, 10:23 PM PDT · auto-refresh 120s
← AI Operations Dashboard docs·help/upgrading.md

Upgrading

AI Operations Dashboard ships as a distributable product: GitHub main on the master repo is the single source of truth, and every install tracks it through an upstream git remote. When the maintainer merges to main and bumps the version, your install detects the new version and offers a one-click update — or you can run the same engine from the CLI. The update overlays only product files, preserves all of your data, runs migrations, verifies, and rolls back automatically on any failure.

The one-click update (in-app)

When your install is behind upstream/main, an Update available · vX → vY banner appears in the dashboard header. Click Update now and the dashboard:

  1. Snapshots your instance directories (so a failure can roll back).
  2. Fetches upstream/main and overlays only product paths (app code, CLI, scripts, lockfile) — your data is never touched.
  3. Runs any pending migrations (scripts/migrations/<version>.mjs), in semver order.
  4. Runs npm install, then verifies with npm run check:data and the type/build check.
  5. On success, records the new version in .ai-ops-dashboard/install.json. On any failure, rolls back to the snapshot.

The update runs as a detached background process (it overlays the app's own code, so it cannot finish cleanly inside the live server). While it runs the banner shows "Updating… restart the server when it finishes" — watch .ai-ops-dashboard/upgrade-status.json for state, then restart npm run dev / your server once it reads done.

The CLI update

Same engine, no browser:

npx ai-ops-dashboard upgrade --check     # print current vs available version, exit (no changes)
npx ai-ops-dashboard upgrade --dry-run   # print the overlay + migration plan, no changes
npx ai-ops-dashboard upgrade             # run the upgrade (snapshot → overlay → migrate → verify → rollback-on-fail)

--check is offline-safe: with no network it simply reports no update available.

What is preserved

A path is instance (preserved, never overwritten) if it matches an instancePath in .ai-ops-dashboard/upgrade-manifest.json; otherwise it's a product path (overlaid from upstream/main).

| Preserved (instance) | Overlaid (product) | |---|---| | ai-ops-dashboard.config.ts | app/, components/, lib/ | | data/, docs/, knowledge/, plans/ | cli/, scripts/, help/, public/ | | .ai-ops-dashboard/ (your manifest, install.json, custom panels) | next.config.mjs, tsconfig.json, package.json, package-lock.json | | .ai-ops-dashboard-client/, .env | graphify-out/graph.json + report + manifest |

> Precedence: the whole .ai-ops-dashboard/ directory is instance except .ai-ops-dashboard/upgrade-manifest.json, which is product (so the preserve/overlay rules themselves stay up to date).

Capability — updates are local-only

The in-app Update now button and the CLI both run a capability check first. An update is only offered when all of these hold:

  • The install root is a git repo.
  • An `upstream` (or origin) remote exists, pointing at the master.
  • The working directory is writable.
  • The process is not running under a read-only/hosted signal (NODE_ENV / hosting env).

On a hosted or read-only deployment the button never appears — there's nothing to overlay. Update locally, commit, and redeploy as usual (see deployment.md).

Rollback

The engine snapshots your instance directories before it mutates anything. If migrations, npm install, or verification fail, it restores the snapshot and records the error in .ai-ops-dashboard/upgrade-status.json (state: "error"). Your install is left exactly as it was before you clicked Update now. Re-run after fixing the cause (e.g. a dirty working tree).

How versions work

| Bump | When | Effect | |---|---|---| | Patch (0.7.0 → 0.7.1) | Bug fix, no API changes. | Overlay only; rarely a migration. | | Minor (0.7.0 → 0.8.0) | New features, additive only. | Overlay + any additive migration. | | Major (0.x → 1.0) | Breaking changes to AiOpsDashboardConfig / PanelDefinition / public exports. | Overlay + migration; read the MIGRATIONS.md note. |

The install's product version is package.json's version, recorded in .ai-ops-dashboard/install.json. CHANGELOG.md has the human-readable changes.

Stability guarantees

Stable across minor versions:

  • AiOpsDashboardConfig shape — field names, types, defaults.
  • PanelDefinition / BannerDefinition / BannerState interfaces (lib/panels/types.ts).
  • Public exports from lib/data-sources — readJson, readMarkdown, walkMarkdown, readGitLog, fetchJson, fileMtime, fileExists, formatPT.
  • The CSS variable names in app/globals.css and shared utility classes (data-card, chip, stat-label, data-table).
  • The instance file layout in .ai-ops-dashboard/upgrade-manifest.json -> instancePaths — these are preserved across every update.

NOT guaranteed: internal components/dashboard/* structure, undocumented CSS class names, build-script internals.

Reporting upgrade issues

If an update breaks something documented as stable, that's a bug. File an issue with the from/to version (from .ai-ops-dashboard/install.json), your sanitized ai-ops-dashboard.config.ts, and the state: "error" block from .ai-ops-dashboard/upgrade-status.json.

Next

Upgrading