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. Identity, authorization, agent, cache, indexeddb, runtime, S3, secrets, workflow, and app packages all use this manifest format. The app 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"]

For executable source manifests, entrypoint.artifactPath is the packaged executable path. When object-form or list-form build is present, Gestalt runs it before release packaging and requires the command to produce that file and/or static assets under GESTALT_BUILD_STATIC. If a source manifest also declares run, local source execution uses run instead of entrypoint.

kind: indexeddb
source: github.com/acme/providers/indexeddb/postgres
version: 1.0.0
build:
  command: ["go", "build", "-o", ".gestalt/build/indexeddb", "./cmd/indexeddb"]
  inputs: ["go.mod", "go.sum", "cmd", "internal"]
entrypoint:
  artifactPath: .gestalt/build/indexeddb
spec:
  configSchemaPath: schemas/config.schema.yaml

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.*.

App Metadata

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

Core Fields

Connections

The connections map defines named connection profiles. Deployment config can override or extend these defaults under apps.<name>.connections; see Config File for the config-side schema. Put new upstream auth definitions in connections.default unless you need a surface-specific profile. A surface can select a named connection with spec.surfaces.<surface>.connection, and defaultConnection selects the fallback when a surface does not name one. 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. When allowedOperations entries include GraphQL documents, Gestalt builds a static catalog from those documents without introspecting the upstream schema. GraphQL surfaces without document-backed operations still resolve generated catalogs lazily from the upstream schema when a real request runs under that surface’s connection.

spec.surfaces.mcp

MCP surfaces are exposed to MCP clients through Gestalt’s /mcp endpoint and to REST clients through the generic REST facade at POST /api/v1/{app}/{operation}. REST-visible MCP tools are listed as transport: mcp-passthrough operations.

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 app HTTP routes. Gestalt currently enforces it on /api/v1/apps/{name}/operations, /api/v1/{integration}/{operation}, and apps.<name>.static mounts, including browser-login flows whose next path resolves into that app’s mount. 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/{app}/{operation} facade; use them when a plugin needs a stable custom path, form-encoded request bodies, or hosted request verification.

spec.http.<name>.path is app-relative. The configured app 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: {}

Hosted HTTP routes are declared in the manifest. Source apps 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 package.

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 */*.

The route waits for the target operation to finish and returns its status and body 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

App-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 document-backed operations, keys are Gestalt operation IDs; the document itself determines the upstream root field and variables.

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

For GraphQL surfaces, prefer document-backed operations. Gestalt parses each document locally and exposes variables as operation parameters. The allowlist key is the Gestalt operation ID and does not need to match the upstream root field:

spec:
  allowedOperations:
    search_issues:
      alias: issues.search
      graphql:
        operationName: SearchIssues
        document: |
          query SearchIssues(
            "Search text."
            $query: String!
            $first: Int = 25
          ) {
            issues(filter: { search: $query }, first: $first) {
              nodes { id identifier title url team { id name key } }
              pageInfo { hasNextPage endCursor }
            }
          }

Variables may include GraphQL descriptions. Gestalt uses those descriptions for parameter help text, then strips them from the executable document it sends upstream so providers that have not adopted variable descriptions can still run the operation. Gestalt marks variables as required when they are non-null and have no default value, and maps variable types to simple catalog parameter types without schema introspection. Named fragments are supported only when the fragment definition is present in the same graphql.document; manifests do not support a fragmentFiles list or fragments loaded from separate files.

If a GraphQL surface has no document-backed operations, Gestalt keeps the legacy lazy session-catalog behavior and treats allowedOperations keys as upstream query or mutation root field names. Ambiguous root fields that exist on both query and mutation roots must be converted to document-backed operations. For providers that combine GraphQL with another surface, entries without a graphql block are left for the other surface. Raw GraphQL passthrough access remains a separate surface permission.

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.

Identity Provider Metadata

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

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

kind: identity
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

Command Phases

Source app manifests may declare three serial phases: install, build, and run. Each phase accepts:

• Argv list — a YAML sequence of strings, for example [npm, ci]
• Object — { command: [...], workdir, env, inputs, readyTimeout }
• Command list — a sequence of argv lists and/or objects executed in order

install:
  - [npm, ci]
build:
  - command: [npm, run, build]
    inputs:
      - package.json
      - package-lock.json
      - src
run:
  - command: [npm, run, dev]
    readyTimeout: 120s
  - command: [npm, run, dev:provider]

install runs before build during lock, sync, package, and local preparation. build may produce an executable at entrypoint.artifactPath and/or static files in the directory named by GESTALT_BUILD_STATIC. run is source-only; gestaltd uses it for local provider startup and dev-server proxying. Multiple run commands require dev-mode support.

Legacy object-form build.command and single run argv arrays remain valid.

Static Assets

When a build step writes index.html into GESTALT_BUILD_STATIC, Gestalt stages that directory as static/ in prepared and release archives and records the packaged static root on the manifest. Engineers author builds to GESTALT_BUILD_STATIC; they do not commit a static/ directory in source.

build:
  - command: [npm, run, build]

# after package
static/
  index.html
  assets/

Run

Top-level run is source-only and starts an executable provider from local source. It is an argv array, not a shell string. Gestalt runs it from the manifest directory, so project-local executables should usually include ./.

build: [uv, sync, --frozen, --no-install-project]
run: [uv, run, --frozen, ./provider.py, --serve]

run is never included in prepared or released manifests. Use entrypoint.artifactPath and artifacts for the compiled package command. A manifest that only declares run is local-only; add SDK-native provider metadata or object-form build.command with entrypoint.artifactPath before using it with lock, sync, or release packaging.

Artifacts

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

Declarative-only app packages do not require artifacts. Pure executable source manifests used with apps.*.provider.source.path or gestaltd provider package may omit them.

Full Example

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

kind: app
source: github.com/acme/apps/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: subject
      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: subject
      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": "app",
  "source": "github.com/acme/apps/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": "subject",
        "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": "subject",
        "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 app requires no binary. It defines REST operations entirely in the manifest.

kind: app
source: github.com/acme/apps/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. The current set is app, identity, authorization, agent, cache, indexeddb, runtime, s3, secrets, ui, and workflow.

configSchemaPath validates deployment config for the provider and may be written in JSON or YAML. For app connections, put params and discovery on the default connection unless you have confirmed the named-connection behavior you need. OpenAPI and GraphQL may be declared together on one app, and MCP may be added alongside either or both.

A connection using mcp_oauth auth requires the app 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.

Executable source providers may either use the SDK-native Go, Rust, Python, or TypeScript source-package metadata, or declare top-level run for local source execution. Use object-form build.command with entrypoint.artifactPath when the source package needs to produce a compiled release artifact. Source manifests must not include artifacts; prepared and released manifests include artifacts and omit build and run.

kind: indexeddb
source: github.com/acme/providers/indexeddb/postgres
version: 1.0.0
build:
  command:
    - go
    - build
    - -o
    - .gestalt/build/indexeddb
    - ./cmd/indexeddb
  inputs:
    - go.mod
    - go.sum
    - cmd
    - internal
entrypoint:
  artifactPath: .gestalt/build/indexeddb
spec:
  configSchemaPath: schemas/config.schema.yaml

For local-only source execution, run can start the provider directly:

kind: app
source: github.com/acme/apps/slack
version: 1.0.0
build: [uv, sync, --frozen, --no-install-project]
run: [uv, run, --frozen, ./provider.py, --serve]
spec:
  connections:
    default:
      auth:
        type: none

Declarative app manifests that only describe hosted HTTP, GraphQL, MCP, or spec-loaded surfaces may omit entrypoint and build. See Plugins for the end-to-end authoring flow.

Release

Build release archives from a provider source directory, then finalize metadata:

gestaltd provider package --version 1.2.3
gestaltd provider release --dist-dir dist --version 1.2.3

gestaltd provider package preserves the source manifest format, so manifest.yaml stays YAML and manifest.json stays JSON in the release archive. For source manifests with object-form build.command, package runs the command before packaging. Executable providers must produce entrypoint.artifactPath; unified app packages with static frontends must produce index.html under GESTALT_BUILD_STATIC. Released manifests strip build and run, then record the prepared artifacts metadata. Hosted HTTP/security metadata is read from manifest spec.securitySchemes / spec.http and preserved in the packaged manifest.

Executable source packages that are not SDK-native require build.command for release packaging and build the host-platform artifact by default. Platform-neutral packages, such as declarative providers and static-only app packages, produce a generic archive by default. Pass --platform for an explicit os/arch target list, or --platform all in CI to build the full supported release matrix. For explicit platforms, 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.