Providers

Gestalt loads most integration and platform surfaces as providers instead of compiling them into gestaltd. Plugins, authentication backends, IndexedDB backends, authorization backends, agent backends, workflow backends, runtime backends, cache backends, S3 object stores, external secret managers, and public UIs all use the same provider model: you reference a package in config, the host resolves it, validates it, and starts it with the permissions and request context it needs.

Provider kinds

Kind	Purpose	Config location
`plugin`	Tool providers that expose operations over CLI, HTTP API, and MCP	`plugins.<name>`
`auth`	Platform authentication backends	`providers.authentication.<name>`
`authorization`	Dynamic subject authorization backends	`providers.authorization.<name>`
`agent`	Global agent run backends that reason over messages and tools	`providers.agent.<name>`
`cache`	Plugin-bound cache backends	`providers.cache.<name>`
`indexeddb`	Persistent state backends for users, sessions, tokens, and credentials	`providers.indexeddb.<name>`
`runtime`	Hosted execution backends for executable plugins	`runtime.providers.<name>`
`s3`	S3-compatible object stores mounted into plugins	`providers.s3.<name>`
`secrets`	Secret managers that resolve structured secret refs	`providers.secrets.<name>`
`workflow`	Workflow run, schedule, and event-trigger backends	`providers.workflow.<name>` plus top-level `workflows.*`
`ui`	Public UI bundles served under configured path prefixes	`providers.ui`

How providers work

Use source.path during local development to point at a provider manifest in a local source tree.
Use source: https://.../provider-release.yaml to consume a published provider package.
Use source.githubRelease when the published provider-release.yaml lives in a private GitHub Release and you want checked-in config to stay readable.
Use sibling auth.token when a remote release source, including source.githubRelease, needs authenticated metadata or archive fetches.
Executable providers run as child processes and connect back to the host over gRPC on a temporary Unix socket.
UI providers are static asset bundles rather than executable processes.
allowedHosts and server.egress declare outbound policy for executable providers, with complete enforcement depending on the sandbox runtime in use.
Two simple secret managers, env and file, remain built into gestaltd. Telemetry and audit backends are also built in.

First-party providers

First-party provider packages live in valon-technologies/gestalt-providers. The repository is organized by provider type:

Type	Repository path	Typical config key
Plugin	`plugins/`	`plugins.<name>`
Authentication	`auth/`	`providers.authentication.<name>`
Authorization	`authorization/`	`providers.authorization.<name>`
Cache	`cache/`	`providers.cache.<name>`
IndexedDB	`indexeddb/`	`providers.indexeddb.<name>`
Runtime	`runtime/`	`runtime.providers.<name>`
S3	`s3/`	`providers.s3.<name>`
Secret	`secrets/`	`providers.secrets.<name>`
Workflow	`workflow/`	`providers.workflow.<name>`
UI	`web/`	`providers.ui`

There is not yet a first-party agent provider published from valon-technologies/gestalt-providers. If you need one today, implement it as a custom provider with the neutral agent protocol described in Custom Providers > Agent.

Using providers

Reference the package you want to run, then initialize or start the server:


server:
  providers:
    indexeddb: main
 
providers:
  authentication:
    oidc:
      source: https://artifacts.example.com/auth/oidc/v0.0.1-alpha.1/provider-release.yaml
      config:
        issuerUrl: https://login.example.com
        clientId: ${OIDC_CLIENT_ID}
        clientSecret:
          secret:
            provider: default
            name: oidc-client-secret
 
  indexeddb:
    main:
      source: https://artifacts.example.com/indexeddb/relationaldb/v0.0.1-alpha.1/provider-release.yaml
      config:
        dsn: ${DATABASE_URL}
 
  cache:
    session:
      source: https://artifacts.example.com/cache/valkey/v0.0.1-alpha.1/provider-release.yaml
      config:
        address: ${VALKEY_ADDR}
 
  s3:
    assets:
      source: ./providers/s3/minio/manifest.yaml
      config:
        endpoint: http://127.0.0.1:9000
        region: us-east-1
        accessKeyId: ${MINIO_ROOT_USER}
        secretAccessKey:
          secret:
            provider: default
            name: minio-root-password
 
plugins:
  github:
    source: https://artifacts.example.com/plugin/github/v0.0.1-alpha.1/provider-release.yaml
    cache:
      - session
 
  media:
    source: ./plugins/media/manifest.yaml
    s3:
      - assets

Run gestaltd init when you want to resolve and pin published releases ahead of time, then gestaltd serve --locked to start from that prepared state.

Building custom providers

If you need a provider Gestalt does not already ship, the implementation and release workflow now lives under Custom Providers.