Provider Manifests

Gestalt provider packages and release archives are described by a manifest file: manifest.yaml, manifest.yml, or manifest.json. YAML is the easiest format to author by hand.

Providers are the umbrella concept in Gestalt. Authentication, authorization, agent, cache, indexeddb, runtime, S3, secrets, workflow, and plugin packages all use this manifest format. The plugin manifest kind is reserved for providers that expose callable operations.

Manifest Kinds

Every manifest defines exactly one provider kind, set by the kind field:

The kind field is required. Kind-specific configuration goes under the spec block.

Common Fields

These fields appear at the top level of every manifest regardless of kind.

Entrypoint

The entrypoint block declares the executable binary for the provider.

entrypoint:
  artifactPath: artifacts/linux/amd64/plugin
  args: ["--verbose"]

Runtime Metadata

Runtime providers use the same common manifest structure as other executable providers. Their kind-specific spec currently only uses configSchemaPath:

kind: runtime
source: github.com/acme/runtime/example
version: 0.0.1
entrypoint:
  artifactPath: artifacts/linux/amd64/runtime
spec:
  configSchemaPath: ./schemas/config.schema.yaml

Operators then reference that package under top-level runtime.providers, not under providers.*.

Plugin Metadata

The spec block for a kind: plugin manifest describes a plugin. It supports declarative REST operations, spec-loaded surfaces (OpenAPI, GraphQL, MCP), executable code, or any combination.

Core Fields

Owned UI

Plugins that back mounted apps may declare their UI artifact in the plugin manifest. Deployment config still chooses whether to mount the app, which public path to use, and which authorization policy to bind. The manifest only says which UI bundle belongs to the plugin.

spec.ui supports two mutually exclusive forms:

When a deployment sets plugins.<name>.ui.path and omits plugins.<name>.ui.bundle, Gestalt synthesizes the mounted UI binding from this block.

Source-manifest example:

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

Published-manifest example:

kind: plugin
source: github.com/acme/plugins/roadmap-review
version: 1.0.0
spec:
  auth:
    provider: server
  connections:
    default:
      auth:
        type: none
  ui:
    ref: github.com/acme/web/roadmap-review
    version: 1.0.0
    auth:
      token:
        secret:
          provider: default
          name: roadmap-review-ui-source-token

Connections

The connections map defines named connection profiles. Deployment config can override or extend these defaults; see Config File for the config-side schema. Each connection supports the following fields:

Surfaces

Surfaces load operation catalogs from external specifications. They are configured under spec.surfaces.

spec.surfaces.openapi

spec.surfaces.graphql

GraphQL surfaces expose a raw GraphQL passthrough immediately. Generated GraphQL operation catalogs are resolved lazily from the upstream schema when a real request runs under that surface’s connection. Gestalt does not introspect GraphQL endpoints during package build, gestaltd init, or config validation.

spec.surfaces.mcp

spec.surfaces.rest

surfaces.rest is the declarative REST form. surfaces.openapi, surfaces.graphql, and surfaces.mcp are passthrough surfaces. You may combine openapi and graphql on the same plugin, and mcp may be added alongside any of them.

Authentication Types

spec.auth.provider selects a route-auth provider for plugin HTTP routes. Gestalt currently enforces it on /api/v1/integrations/{name}/operations, /api/v1/{integration}/{operation}, and plugin-backed mounted UIs, including browser-login flows whose next path resolves into that plugin’s mounted UI. Standalone providers.ui bundles, the built-in admin UI/admin API, integration OAuth helper routes, and /mcp still use the server-wide auth provider. Upstream auth still lives on spec.connections.<name>.auth, and the auth.type field on a connection accepts these values:

Manual authentication in provider manifests also supports authMapping, using the same value / valueFrom.credentialFieldRef.name shape as deploy config.

spec:
  connections:
    default:
      auth:
        type: manual
        credentials:
          - name: organization_id
            label: Organization ID
          - name: api_key
            label: API Key
        authMapping:
          basic:
            username:
              valueFrom:
                credentialFieldRef:
                  name: organization_id
            password:
              valueFrom:
                credentialFieldRef:
                  name: api_key

Hosted HTTP Bindings

Hosted HTTP bindings are optional routes layered on top of operations. They do not replace the generic /api/v1/{plugin}/{operation} facade; use them when a plugin needs a stable custom path, form-encoded request bodies, hosted request verification, or an immediate host-managed acknowledgment response.

spec.http.<name>.path is plugin-relative. The configured plugin key determines the public prefix: for a deployment entry named example, path: /command mounts at /api/v1/example/command.

Each binding must name a security scheme. Use a type: none scheme only for routes that are intentionally unsigned.

spec.securitySchemes

Every scheme requires type. hmac, apiKey, and http schemes also require secret. HMAC schemes compare the computed digest against signatureHeader, optionally prefixed by signaturePrefix; payloadTemplate supports {raw_body} and {header:Header-Name} placeholders.

spec.http.<name>

Example:

spec:
  securitySchemes:
    signed:
      type: hmac
      secret:
        env: REQUEST_SIGNING_SECRET
      signatureHeader: X-Request-Signature
      signaturePrefix: v0=
      payloadTemplate: "v0:{header:X-Request-Timestamp}:{raw_body}"
      timestampHeader: X-Request-Timestamp
      maxAgeSeconds: 300
  http:
    command:
      path: /command
      method: POST
      credentialMode: none
      security: signed
      target: handle_command
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded: {}
      ack:
        status: 200
        body:
          status: accepted

Hosted HTTP routes are declared in the manifest. Source plugins written in Go, Python, Rust, or TypeScript implement the target operation in code, while spec.securitySchemes and spec.http remain the source of truth for mounted HTTP routes during local source execution and gestaltd provider release.

Gestalt parses query parameters into the operation input for every hosted HTTP binding. For request bodies, application/json object fields merge into the input, application/x-www-form-urlencoded fields become string parameters, and other content types are exposed as rawBody. If requestBody.content is set, the request Content-Type must match one of the declared media types or */*.

If ack is set, Gestalt returns that status, headers, and body immediately and dispatches the target operation asynchronously. Without ack, the route waits for the operation result and returns it to the caller.

Executable providers may optionally implement hosted HTTP subject resolution before the target operation runs. The resolver receives the verified binding name, method, path, headers, query parameters, decoded params, raw body, security scheme, and verified claims. Returning a subject makes normal plugin authorization and connection lookup run as that subject; returning nothing uses the binding’s system subject.

Pagination

Plugin-level pagination configuration applies to all operations by default. Individual operations can override this through allowedOperations.

spec:
  pagination:
    style: cursor
    cursorParam: starting_after
    cursor:
      source: body
      path: next_cursor
    limitParam: limit
    defaultLimit: 100
    maxPages: 10

Allowed Operations

The allowedOperations map selectively exposes and customizes operations from a spec-loaded surface. Keys are the original operation IDs from the OpenAPI or MCP spec. For GraphQL, they apply to the lazily resolved session catalog and use the original upstream field names.

spec:
  allowedOperations:
    tickets.list:
      alias: list_tickets
      allowedRoles: [viewer, admin]
      paginate: true
    tickets.get:
      alias: get_ticket
      allowedRoles: [admin]

Response Mapping

The responseMapping block extracts a data array and pagination metadata from API responses that wrap results in an envelope.

Managed Parameters

Managed parameters inject fixed values into every request, removing them from the caller-facing operation signature.

Discovery

The discovery block on a connection performs an authenticated lookup immediately after a connection is established. Gestalt calls the configured URL with the new access token, parses the response, and turns each item into a candidate connection.

If discovery returns exactly one item, Gestalt merges its metadata into the stored connection automatically. Multiple items prompt the user to choose. Zero items fails the connection.

Connection Params

The params map on a connection defines parameters that are populated during or after connect rather than from user input.

Authentication Provider Metadata

The spec block for a kind: authentication manifest describes a platform authentication provider package.

Authentication providers require an executable entrypoint. Declare it under entrypoint.

kind: authentication
source: github.com/valon-technologies/gestalt-providers/auth/oidc
version: 1.0.0
displayName: OIDC Authentication
spec:
  configSchemaPath: schemas/config.schema.json
entrypoint:
  artifactPath: artifacts/linux/amd64/auth
artifacts:
  - os: linux
    arch: amd64
    path: artifacts/linux/amd64/auth

IndexedDB Provider Metadata

The spec block for a kind: indexeddb manifest describes a persistence backend package.

IndexedDB providers require an executable entrypoint. Declare it under entrypoint.

kind: indexeddb
source: github.com/valon-technologies/gestalt-providers/indexeddb/relationaldb
version: 1.0.0
displayName: PostgreSQL
spec:
  configSchemaPath: schemas/config.schema.json
entrypoint:
  artifactPath: artifacts/linux/amd64/provider
artifacts:
  - os: linux
    arch: amd64
    path: artifacts/linux/amd64/provider

UI Metadata

The spec block for a kind: ui manifest describes a static UI package.

Each spec.routes entry declares a mounted path and the allowed human roles for that path. Path matching is exact or longest-prefix with a terminal /*. When a deployment sets authorizationPolicy, route definitions must have non-empty allowedRoles, and the manifest must include a route that covers /.

kind: ui
source: github.com/acme/plugins/gestalt-ui
version: 1.0.0
displayName: Custom UI
spec:
  assetRoot: ui/out
  routes:
    - path: /
      allowedRoles: [viewer, admin]
    - path: /admin/*
      allowedRoles: [admin]

Artifacts

The artifacts array lists platform-specific binaries included in the package.

Declarative-only plugin packages do not require artifacts. Pure executable source manifests used with plugins.*.provider.source.path or gestaltd provider release may omit them.

Full Example

This manifest shows a plugin with an executable entrypoint, multiple connections, OpenAPI and MCP surfaces, pagination, allowed operations, and managed parameters.

kind: plugin
source: github.com/acme/plugins/support
version: 1.2.3
displayName: Support
description: Tickets, knowledge base, and MCP workspace tools
iconFile: assets/icon.svg
spec:
  configSchemaPath: schemas/config.schema.yaml
  headers:
    X-App-Version: "2026-04-01"
  managedParameters:
    - in: path
      name: workspace_id
      value: primary
  connections:
    default:
      mode: user
      auth:
        type: oauth2
        authorizationUrl: https://accounts.support.example.com/oauth/authorize
        tokenUrl: https://accounts.support.example.com/oauth/token
        clientId: ${SUPPORT_CLIENT_ID}
        clientSecret: ${SUPPORT_CLIENT_SECRET}
        scopes:
          - tickets.read
          - tickets.write
      params:
        workspace_id:
          required: true
          from: discovery
      discovery:
        url: https://api.support.example.com/workspaces
        idPath: id
        namePath: name
        metadata:
          workspace_id: id
    mcp:
      mode: user
      auth:
        type: mcp_oauth
  surfaces:
    openapi:
      document: openapi.yaml
      connection: default
    mcp:
      url: https://mcp.support.example.com/mcp
      connection: mcp
  pagination:
    style: cursor
    cursorParam: starting_after
    cursor:
      source: body
      path: next_cursor
    limitParam: limit
    defaultLimit: 50
    maxPages: 5
  allowedOperations:
    tickets.list:
      alias: list_tickets
      paginate: true
    tickets.get:
      alias: get_ticket
entrypoint:
  artifactPath: artifacts/linux/amd64/plugin
artifacts:
  - os: linux
    arch: amd64
    libc: musl
    path: artifacts/linux/amd64/plugin
    sha256: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

{
  "kind": "plugin",
  "source": "github.com/acme/plugins/support",
  "version": "1.2.3",
  "displayName": "Support",
  "description": "Tickets, knowledge base, and MCP workspace tools",
  "iconFile": "assets/icon.svg",
  "spec": {
    "configSchemaPath": "schemas/config.schema.yaml",
    "headers": {
      "X-App-Version": "2026-04-01"
    },
    "managedParameters": [
      { "in": "path", "name": "workspace_id", "value": "primary" }
    ],
    "connections": {
      "default": {
        "mode": "user",
        "auth": {
          "type": "oauth2",
          "authorizationUrl": "https://accounts.support.example.com/oauth/authorize",
          "tokenUrl": "https://accounts.support.example.com/oauth/token",
          "clientId": "${SUPPORT_CLIENT_ID}",
          "clientSecret": "${SUPPORT_CLIENT_SECRET}",
          "scopes": ["tickets.read", "tickets.write"]
        },
        "params": {
          "workspace_id": { "required": true, "from": "discovery" }
        },
        "discovery": {
          "url": "https://api.support.example.com/workspaces",
          "idPath": "id",
          "namePath": "name",
          "metadata": { "workspace_id": "id" }
        }
      },
      "mcp": {
        "mode": "user",
        "auth": { "type": "mcp_oauth" }
      }
    },
    "surfaces": {
      "openapi": {
        "document": "openapi.yaml",
        "connection": "default"
      },
      "mcp": {
        "url": "https://mcp.support.example.com/mcp",
        "connection": "mcp"
      }
    },
    "pagination": {
      "style": "cursor",
      "cursorParam": "starting_after",
      "cursor": {
        "source": "body",
        "path": "next_cursor"
      },
      "limitParam": "limit",
      "defaultLimit": 50,
      "maxPages": 5
    },
    "allowedOperations": {
      "tickets.list": { "alias": "list_tickets", "paginate": true },
      "tickets.get": { "alias": "get_ticket" }
    }
  },
  "entrypoint": {
    "artifactPath": "artifacts/linux/amd64/plugin"
  },
  "artifacts": [
    {
      "os": "linux",
      "arch": "amd64",
      "libc": "musl",
      "path": "artifacts/linux/amd64/plugin",
      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    }
  ]
}

Declarative-Only Example

This plugin requires no binary. It defines REST operations entirely in the manifest.

kind: plugin
source: github.com/acme/plugins/support-api
version: 0.0.1-alpha.1
displayName: Support API
description: Small ticket API
iconFile: assets/icon.svg
spec:
  connections:
    default:
      auth:
        type: bearer
        credentials:
          - name: token
            label: API Token
  surfaces:
    rest:
      baseUrl: https://api.support.example.com
      operations:
        - name: list_tickets
          description: Return open tickets
          method: GET
          path: /tickets
          allowedRoles: [viewer, admin]
        - name: get_ticket
          description: Return one ticket
          method: GET
          path: /tickets/{ticket_id}
          allowedRoles: [admin]

Authoring Notes

Manifest paths must stay inside the package. kind, source, and version are required. A manifest defines exactly one provider kind: kind: plugin, kind: authentication, kind: indexeddb, kind: secrets, or kind: ui.

configSchemaPath validates per-plugin config and may be written in JSON or YAML. Any connection may define params and discovery. OpenAPI and GraphQL may be declared together on one plugin, and MCP may be added alongside either or both.

A connection using mcp_oauth auth requires the plugin to declare an MCP surface (via spec.surfaces.mcp or an equivalent). Manifests that set auth.type: mcp_oauth without an MCP surface fail validation.

When an executable plugin defines helper operations in Go, Rust, Python, or TypeScript, Gestalt materializes the executable catalog automatically during local source-plugin execution and provider release. Hosted HTTP/security metadata remains manifest-authored in spec.securitySchemes and spec.http; release preserves those blocks in the packaged manifest. Authentication and indexeddb source packages use the same release flow for Go, Rust, and TypeScript, but they do not generate catalogs. See Plugins for the end-to-end authoring flow.

my-plugin/
  go.mod
  manifest.yaml
  provider.go

my-plugin/
  pyproject.toml
  manifest.yaml
  provider.py

[tool.gestalt]
provider = "provider"

my-plugin/
  Cargo.toml
  manifest.yaml
  src/
    lib.rs

gestalt::export_provider!(constructor = new, router = router);

my-plugin/
  package.json
  manifest.yaml
  provider.ts

{
  "gestalt": {
    "provider": {
      "kind": "plugin",
      "target": "./provider.ts#plugin"
    }
  }
}

Release-only build steps can be declared in source manifests with release.build. Gestalt runs that command before source-manifest preparation, which lets packages generate support files or UI bundles without checking built artifacts into source control.

kind: ui
source: github.com/acme/plugins/gestalt-ui
version: 1.0.0
release:
  build:
    workdir: ui
    command:
      - npm
      - run
      - build
spec:
  assetRoot: ui/out

Release

Build a release from a provider source directory:

gestaltd provider release --version 1.2.3

gestaltd provider release preserves the source manifest format, so manifest.yaml stays YAML and manifest.json stays JSON in the release archive. For executable Go and Rust plugins, release materializes the executable catalog automatically before packaging. Python source plugins load the module declared in [tool.gestalt].provider and materialize the executable catalog automatically. TypeScript source providers load the target declared in package.json under gestalt.provider. A string target such as ./provider.ts#plugin defaults to a plugin provider; auth and indexeddb providers use an object with kind and target. Hosted HTTP/security metadata is read from manifest spec.securitySchemes / spec.http and preserved in the packaged manifest. Authentication and indexeddb source packages support the same release flow for Go, Rust, and TypeScript, but they do not generate catalogs. Source packages build the host-platform artifact by default. Pass --platform for an explicit os/arch[/libc] target list, or --platform all in CI to build the full supported release matrix.