Providers

Gestalt loads integrations as providers instead of compiling them into gestaltd. This follows the Terraform providers  model.

What Providers Do

Each provider adds one kind of capability to Gestalt. Some providers expose tools that users and agents can call. Others back services such as authentication, authorization, and storage.

Every configured provider is resolved from a manifest and validated by gestaltd.

The provider pages describe the configuration shape, runtime model, SDK examples, and custom provider contract for that kind:

How to Use Providers

Providers are distributed separately from gestaltd. The official registry of first-party providers is registry.gestaltd.ai . The registry lists first-party packages published from valon-technologies/gestalt-providers.

Provider sources are configured under apps.<name>, providers.<kind>.<name>, or runtime.providers.<name>.

Provider packages

Use package sources for published providers. A package source names a package, optional repository, and optional version constraint. Gestalt resolves it through a provider repository and locks the selected release.

Provider repositories are static YAML indexes. Gestalt fetches the index, selects a version, then fetches its provider-release.yaml. The default repository is valon:

https://raw.githubusercontent.com/valon-technologies/gestalt-providers/main/provider-index.yaml

Add repositories in project or user config. Use source.repo for non-default repositories or duplicate package addresses.

server:
  providers:
    authentication: oidc
 
providers:
  authentication:
    oidc:
      source:
        package: github.com/valon-technologies/gestalt-providers/auth/oidc
        version: ^1.4.0
      config:
        issuerUrl: https://login.example.com
        clientId: ${OIDC_CLIENT_ID}
        clientSecret:
          secret:
            provider: default
            name: oidc-client-secret
 
  # ...

Local source paths

Local sources point at a provider manifest near the config, such as ./apps/my-plugin/manifest.yaml. Use them for development and testing before packaging. Executable source manifests can declare run for local source execution and build.command plus entrypoint.artifactPath for compiled release artifacts. UI source manifests declare build.command and spec.assetRoot.

apps:
  my-plugin:
    source: ./apps/my-plugin/manifest.yaml

providers:
  ui:
    dashboard:
      source: ./gestalt-ui/manifest.yaml
      path: /dashboard

Exact sources

Exact sources point at one release’s provider-release.yaml. Use them for releases outside a provider repository, local release metadata, or private GitHub Release assets. They omit repository and version constraints, so package upgrade commands cannot move them.

apps:
  github:
    source: https://github.com/valon-technologies/gestalt-providers/releases/download/app/github/v0.0.1-alpha.1/provider-release.yaml

providers:
  ui:
    dashboard:
      source: https://github.com/valon-technologies/gestalt-providers/releases/download/ui/default/v1.2.0/provider-release.yaml
      path: /dashboard
      config:
        brand_name: Acme

apps:
  support:
    source:
      githubRelease:
        repo: acme/gestalt-provider-releases
        tag: apps/support/v1.3.0
        asset: provider-release.yaml

Commit-pinned git sources

Git sources point at an external repository, full commit SHA, and manifest path. Use them for reproducible provider revisions before provider-index publication. materialization controls whether Gestalt prepares from source or uses a prebuilt snapshot. See Config File for the full source.git shape.

apps:
  support:
    source:
      git:
        repo: https://github.com/acme/gestalt-providers.git
        ref: 60fa7e0521eeedea8b28abdd9b43284e9ea246e2
        path: apps/support/manifest.yaml
        materialization: source

Provider Installation

Use the provider CLI to add, inspect, lock, sync, upgrade, and remove configured providers. Mutating commands accept one --config path and update the lockfile by default. Use --no-lock when you need to edit config first and run gestaltd lock later.

Add providers

Add an indexed provider package to one writable config file:

gestaltd provider add github.com/valon-technologies/gestalt-providers/auth/oidc \
  --config ./gestalt.yaml \
  --kind authentication \
  --name oidc \
  --version '^1.4.0'

When no version is given, Gestalt chooses the newest non-yanked stable version. If a package has no stable versions, it chooses the newest non-yanked prerelease. Yanked versions are skipped unless you request an exact yanked version. provider add validates the changed config and lockfile in a scratch directory before writing either file.

Add --sync when you want to materialize artifacts immediately after adding the provider:

gestaltd provider add github.com/valon-technologies/gestalt-providers/app/github \
  --config ./gestalt.yaml \
  --sync

Lock and sync

Run gestaltd lock when you want to resolve and pin published releases ahead of time, then gestaltd sync --locked to prepare artifacts before gestaltd serve --locked starts from that prepared state:

gestaltd lock --config ./gestalt.yaml
gestaltd sync --locked --config ./gestalt.yaml
gestaltd serve --locked --config ./gestalt.yaml

This writes lock state to gestalt.lock.json and extracts prepared artifacts under .gestaltd/. After sync, gestaltd serve --locked starts from that prepared state without resolving or writing artifacts at runtime.

List installed providers

provider list shows configured provider entries and how they relate to the lockfile:

gestaltd provider list --config ./gestalt.yaml
gestaltd provider list --config ./gestalt.yaml --kind app

Run gestaltd lock --check --config ./gestalt.yaml in CI when you need a strict lockfile check.

Upgrade providers

Refresh lock state for every configured package source:

gestaltd provider upgrade --config ./gestalt.yaml

This does not edit version constraints. It re-resolves package sources and writes the lockfile with the selected versions.

Change one package source to a new constraint:

gestaltd provider upgrade github \
  --config ./gestalt.yaml \
  --kind app \
  --version '^1.5.0'

The named entry must already be a package source. If the same name exists under more than one provider kind, pass --kind.

Remove providers

Remove one entry from config and update the lockfile:

gestaltd provider remove github --config ./gestalt.yaml --kind app

Omit --kind only when the name is unique across provider kinds.

Private Providers

Private package repositories and private release sources can require credentials. Put fetch credentials under source.auth when Gestalt needs to authenticate to read repository metadata, release metadata, or release archives:

apps:
  support:
    source:
      repo: acme
      package: github.com/acme/gestalt-providers/app/support
      version: ^1.3.0
      auth:
        token: ${GESTALT_PROVIDER_TOKEN}

User-level provider repositories can also supply a token for private indexes. A project-level repository with the same name overrides the repository URL for that project, while the user-level entry can still provide credentials.

How to Find Providers

To find first-party providers, browse the official registry at registry.gestaltd.ai . The registry is the public directory for first-party provider packages.

The CLI can also search configured provider repositories. The built-in valon repository points at the first-party provider index:

gestaltd provider search
gestaltd provider search github
gestaltd provider search github --repo valon

Search matches the package address, display name, and description. The output prints repository name, package address, and display name:

valon  github.com/valon-technologies/gestalt-providers/app/github  GitHub

Use provider info to see the versions published for one package:

gestaltd provider info github.com/valon-technologies/gestalt-providers/app/github

Use provider repositories

List configured repositories:

gestaltd provider repo list
gestaltd provider repo list --config ./gestalt.yaml

Add a repository to your user-level store:

gestaltd provider repo add valon https://registry.gestaltd.ai/provider-index.yaml

Add a repository to project config:

gestaltd provider repo add valon https://registry.gestaltd.ai/provider-index.yaml \
  --config ./gestalt.yaml

The project form writes:

providerRepositories:
  valon:
    url: https://registry.gestaltd.ai/provider-index.yaml

Project config overrides the repository URL for that project. A user-level repository with the same name can still supply a token for private indexes.

Fetch repository indexes into the local cache:

gestaltd provider repo update
gestaltd provider repo update --config ./gestalt.yaml

Remove a repository from the same place you added it:

gestaltd provider repo remove acme
gestaltd provider repo remove acme --config ./gestalt.yaml

Publish an index

A provider index is ordinary YAML:

schema: gestaltd-provider-index
schemaVersion: 1
packages:
  github.com/acme/gestalt-providers/app/support:
    displayName: Support
    description: Internal support tools
    versions:
      1.3.0:
        kind: app
        runtime: go
        metadata: ./apps/support/1.3.0/provider-release.yaml
        platforms:
          - darwin/arm64
          - linux/amd64

metadata may be an absolute https:// or file:// URL, or a relative path resolved from the index URL. Keep the index small enough to fetch often; Gestalt rejects indexes larger than 10 MiB.

How to Develop Providers

Build providers with the Gestalt SDKs, create archives with gestaltd provider package, and finalize release metadata with gestaltd provider release.

Implementation details live on each provider-kind page. Start with the kind you are building, then use the release guidance below when the package is ready.

Releasing provider packages

Gestalt uses the same release system for executable provider packages, authentication and datastore component packages, and packaged UI bundles. Every package is described by a provider manifest file: manifest.yaml, manifest.yml, or manifest.json.

Minimal executable source manifest

kind: app
source: github.com/acme/apps/my-plugin
version: 0.0.1-alpha.1
build:
  command:
    - go
    - build
    - -o
    - .gestalt/build/my-plugin
    - ./cmd/my-plugin
  inputs:
    - go.mod
    - go.sum
    - cmd
    - internal
entrypoint:
  artifactPath: .gestalt/build/my-plugin
spec:
  connections:
    default:
      auth:
        type: none

Executable source packages can declare a local run command and a separate compiled package artifact. Gestalt uses run for local source execution and uses object-form build.command plus entrypoint.artifactPath for release packaging. The build command can call any toolchain available in the preparation environment: Go, Cargo, npm, Python, or an internal wrapper script all use the same manifest shape. Declarative app manifests that only describe hosted/spec-loaded surfaces may omit build, run, and entrypoint.

Source UI builds

Source UI manifests must define top-level build.command and spec.assetRoot. Gestalt runs the command before source-manifest preparation, which lets UI packages generate static assets without checking built files into source control. The environment running gestaltd lock, gestaltd sync --locked, gestaltd serve --path, or gestaltd provider package must have the command’s build tools available. gestaltd serve --locked only serves prepared static assets.

kind: ui
source: github.com/acme/apps/gestalt-ui
version: 1.2.0
build:
  workdir: ui
  command:
    - npm
    - run
    - build
  inputs:
    - ui/package.json
    - ui/package-lock.json
    - ui/src
spec:
  assetRoot: ui/out
  routes:
    - path: /
      allowedRoles: [viewer, admin]

Released UI packages still contain spec.assetRoot; Gestalt verifies that build.command produced that directory and strips build metadata. There is no release.build field and no separate build.output field.

Release manifest for an executable provider

Released executable app providers add concrete entrypoint and artifacts entries:

kind: app
source: github.com/acme/apps/my-plugin
version: 0.0.1-alpha.1
spec: {}
entrypoint:
  artifactPath: artifacts/linux/amd64/provider
artifacts:
  - os: linux
    arch: amd64
    libc: musl
    path: artifacts/linux/amd64/provider
    sha256: "..."

UI bundle manifest

UI packages use the same manifest system:

kind: ui
source: github.com/acme/apps/ui/default
version: 1.2.0
spec:
  assetRoot: ui/out
  configSchemaPath: schemas/ui-config.schema.json

gestaltd lock records the released UI in gestalt.lock.json, and gestaltd sync --locked prepares its assets. gestaltd serve --locked then serves the prepared asset root at whatever public path the deployment config binds for that UI bundle. Omit providers.ui to run headless with no public UI bundles. The built-in admin UI remains available at /admin regardless.

Build a release

Use gestaltd provider package to build provider release archives:

gestaltd provider package --version 0.0.1-alpha.1

Run it from the provider source directory. It writes release archives to dist/. Then finalize those archives:

gestaltd provider release --dist-dir dist --version 0.0.1-alpha.1

The release step validates the packaged archives, writes checksums.txt, and writes provider-release.yaml next to the archives. It does not run source build commands and can run after multiple platform-specific package jobs have collected their archives into one dist directory.

For source manifests that declare object-form build.command, package runs that command, verifies that the declared output exists, strips build and run metadata from the packaged manifest, and records released artifacts. The build environment must provide whatever runtime or compiler the command invokes. When you pass --platform, Gestalt sets target environment variables such as GOOS, GOARCH, GESTALT_TARGET_OS, GESTALT_TARGET_ARCH, and GESTALT_TARGET_PLATFORM for build scripts that need them.

Release archive layout

A typical release archive contains:

manifest.yaml
artifacts/
  my-plugin-linux-amd64
  my-plugin-darwin-arm64
schemas/
  config.schema.json
assets/
  icon.svg

The exact structure is determined by the manifest. schemas/ is optional and used for provider config validation. assets/ is optional and used for icons or other static files.

Use Provider Manifests for the canonical manifest reference.