UI

UI providers are static asset bundles. Gestalt serves each configured bundle either directly from providers.ui.<name>.path or via plugins.<name>.ui.path. The built-in admin UI at /admin remains available regardless of whether public UI bundles are configured.

How UI providers work

Unlike executable providers, a UI provider is just a packaged asset root. gestaltd resolves the bundle, prepares it during gestaltd init, and then serves the pinned assets from the configured public path prefix when the server starts.

How UI routes use authorization

UI authorization is route-based. When you bind an authorizationPolicy to a UI entry, Gestalt authenticates the caller, resolves their role under that policy, and compares it to the mounted UI manifest’s spec.routes[].allowedRoles rules before serving the matching route or its static assets.

Plugin-backed mounted UIs inherit more than just a mount path. They also inherit the owning plugin’s dynamic grants when that plugin declares an authorizationPolicy, and they inherit the plugin’s route-auth provider when the plugin declares auth.provider. Direct providers.ui bundles and the built-in admin UI keep using the server-wide auth configuration instead.

First-party UI bundles

First-party UI bundles live under valon-technologies/gestalt-providers/web.

Provider
`github.com/valon-technologies/gestalt-providers/ui/default`

Configuring `providers.ui`

Use providers.ui as a map of UI bundles. You can either mount a bundle directly from providers.ui, or bind it to a plugin-backed app through the plugins block. Omit providers.ui entirely to run headless with no public UI bundles.

Point at a local source bundle during development:


providers:
  ui:
    roadmap:
      source: ./customer-roadmap-review/ui/manifest.yaml
      path: /create-customer-roadmap-review
      authorizationPolicy: roadmap_review

Bind a UI bundle to a plugin-backed app:


providers:
  ui:
    roadmap:
      source: ./customer-roadmap-review/ui/manifest.yaml
 
plugins:
  roadmap_review:
    source: ./customer-roadmap-review/plugin/manifest.yaml
    ui:
      bundle: roadmap
      path: /create-customer-roadmap-review
    authorizationPolicy: roadmap_review

Or let the plugin manifest own the UI bundle and keep only the deployment binding in config:


plugins:
  roadmap_review:
    source: ./customer-roadmap-review/plugin/manifest.yaml
    ui:
      path: /create-customer-roadmap-review
    authorizationPolicy: roadmap_review

With a plugin manifest like:


kind: plugin
source: github.com/acme/plugins/roadmap-review
version: 1.0.0
spec:
  auth:
    type: none
  ui:
    path: ../ui/manifest.yaml

Reference a published bundle in production:


providers:
  ui:
    roadmap:
      source: https://artifacts.example.com/ui/customer-roadmap-review/v0.0.1/provider-release.yaml
      path: /create-customer-roadmap-review
      authorizationPolicy: roadmap_review

When authorizationPolicy is set, Gestalt authenticates the caller, resolves their role from authorization.policies.<policy>, and checks the UI manifest’s spec.routes[].allowedRoles before serving the route or its associated static assets.

Locked deployments

When a published UI bundle is referenced from providers.ui, run:


gestaltd init --config ./config.yaml

That writes gestalt.lock.json and prepares the bundle under .gestaltd/. Afterward, gestaltd serve --locked serves the prepared assets from the configured path prefix.

The admin UI

The built-in admin UI is always served at /admin, regardless of whether custom UI bundles are configured. Mounted bundles own only their configured public prefixes.

The built-in shell includes two operator views: the Prometheus metrics dashboard and a plugin authorization workspace at /admin/?tab=members. Plugin-backed mounted UIs inherit the owning plugin’s dynamic grants when that plugin declares authorizationPolicy; direct providers.ui.<name>.authorizationPolicy bindings remain static-only. Plugin-backed mounted UIs also inherit the owning plugin’s route-auth provider when that plugin declares auth.provider; direct providers.ui bundles and the built-in admin UI continue using the server-wide auth provider.

Building your own UI bundle

Asset-root layout, build hooks, and release packaging now live under Custom Providers > UI and Custom Providers > Releasing.

UI