Customizing Overlay - Overlay Web

The web app is the canonical surface for enterprise customization. Self-hosters should start in src/overlay.config.ts, then use the shared package APIs from @overlay/app-core, @overlay/extension-sdk, @overlay/api-client, @overlay/ui, @overlay/chat-core, @overlay/chat-react, and @overlay/modules-react. src/overlay.config.ts is a serializable app registry. It can replace brand metadata, add navigation destinations, hide feature-gated surfaces, register settings panels, and describe custom tools or integrations.

import {
  DEFAULT_OVERLAY_NAVIGATION,
  defineOverlayAppConfig,
} from '@overlay/app-core/app-shell'

export const overlayAppShell = defineOverlayAppConfig({
  brand: {
    name: 'Acme AI',
    shortName: 'Acme',
    logoSrc: '/assets/acme-logo.png',
    homeHref: '/app/chat',
    supportEmail: '[email protected]',
  },
  navigation: [
    ...DEFAULT_OVERLAY_NAVIGATION,
    {
      id: 'admin',
      label: 'Admin',
      href: '/app/admin',
      icon: 'shield-check',
      componentKey: 'acme.nav.admin',
    },
  ],
  featureFlags: [
    { id: 'knowledge', label: 'Knowledge', enabled: true },
    { id: 'extensions', label: 'Extensions', enabled: false },
  ],
})

Registries merge with defaults by id. If you provide an item with the same id, Overlay replaces that item’s metadata. Unspecified default items remain available.

Component Keys

Bootstrap returns serializable metadata only. React renderers are local to each surface and are referenced by stable componentKey strings. For example, a settings panel can declare componentKey: 'acme.settings.security'; the web app maps that key to a local React component, while mobile can map the same key to a React Native renderer or ignore it.

Build-Time Extensions

Use @overlay/extension-sdk for trusted extensions that are bundled at build time:

import { defineOverlayExtension } from '@overlay/extension-sdk'

export const studentRevisionExtension = defineOverlayExtension({
  id: 'student-revision',
  version: '1.0.0',
  navigation: [{ id: 'student-revision', label: 'Student Revision', href: '/app/x/student-revision', icon: 'sparkles' }],
  featureModules: [{
    id: 'student-revision',
    label: 'Student Revision',
    routePatterns: ['/app/x/student-revision'],
    componentKey: 'student.modules.revisionDashboard',
  }],
  apiHandlers: [{
    method: 'GET',
    path: '/overview',
    handler: async () => Response.json({ ok: true }),
  }],
})

Register app metadata through extendOverlayAppConfig, map React renderers in src/extensions/registry.tsx, and keep authenticated API handlers under /api/v1/extensions/:extensionId/:path.

Feature Visibility

Use featureFlags for coarse product areas and policyGates for enterprise policy. Feature flags remove gated registry entries from bootstrap when disabled. Policy gates let surfaces show disabled states, warnings, or hidden entries without changing backend route behavior.

Model Providers

Register model provider metadata in modelProviders. Use modelPolicy hooks for local model filtering and defaults. Hooks are not serialized to bootstrap; only serializable model provider metadata is returned to other surfaces.

​Brand, Theme, And Navigation

​Component Keys

​Build-Time Extensions

​Feature Visibility

​Model Providers

Brand, Theme, And Navigation

Component Keys

Build-Time Extensions

Feature Visibility

Model Providers