Skip to Content
ProvidersRuntime

Runtime

Runtimes are under active development and are not yet stable. Breaking changes may happen between releases without warning. Feedback and bug reports are welcome via GitHub Issues .

Runtime providers manage where executable apps, hosted agent providers, and hosted workflow providers run.

By default, executable providers run on the same machine as gestaltd. A runtime provider lets an operator place selected providers in another execution environment, such as a local driver, container host, or hosted sandbox.

When to use a runtime

Use a runtime when the provider needs a stronger execution boundary, a hosted Linux environment, runtime-managed image startup, sandboxing, or specific egress policy enforcements.

Keep the provider host-local when it is trusted, lightweight, and does not need runtime-specific isolation or deployment controls.

Configuring a runtime provider

Runtime providers are configured under top-level runtime.providers:

runtime:
  providers:
    kubernetes:
      source:
        path: ./vendor/gestalt-providers/runtime/kubernetes/manifest.yaml
      default: true
      config:
        namespace: gestalt-runtime
        container: runtime
        connectionMode: portForward
 
server:
  runtime:
    defaultProvider: kubernetes
 
apps:
  support:
    source: ./apps/support/manifest.yaml
    runtime:
      image: ghcr.io/example/support-plugin:2026-04-21
      template: python-dev
      metadata:
        environment: production

Selection is intentionally two-step. runtime.providers defines named backends, while an app, agent provider, or workflow provider opts into hosted execution with its own runtime block. server.runtime.defaultProvider only selects a default backend for entries that already opted into hosted execution.

Provider images

Hosted runtime providers run prebuilt provider images. Gestalt does not upload provider bundles into hosted sessions. The configured image should contain the provider package at the image working directory and preserve the release package layout.

apps:
  support:
    source:
      package: github.com/valon-technologies/gestalt-providers/app/httpbin
      version: 0.0.1-alpha.1
    runtime:
      provider: kubernetes
      image: ghcr.io/example/support-app@sha256:...

Keep the manifest release and image digest in sync. Gestalt does not inspect the image to prove that the manifest entrypoint exists inside it.

For private OCI images, configure imagePullAuth.dockerConfigJson with Docker config JSON, matching the registry auth material used by Docker and Kubernetes image pull secrets.

Building your own runtime provider

Build a runtime provider only when you need to add a new execution backend. Runtime providers use the same package model as other executable providers: manifest, entrypoint, optional config schema, release archive, and published provider-release.yaml metadata.

kind: runtime
source: github.com/your-org/runtime/example
version: 0.0.1
displayName: Example Runtime
description: Hosted runtime backend for executable providers.
entrypoint:
  artifactPath: ./bin/example-runtime
spec:
  configSchemaPath: ./schemas/config.schema.yaml

A runtime provider should advertise its capabilities, create and tear down runtime sessions, start the hosted provider image or process, and optionally support agent workspace preparation and runtime-originated logs. Keep those capabilities truthful: they are what operators see when they inspect configured runtimes and what Gestalt uses to reject unsupported placements early.

For packaging and publishing, see Releasing provider packages. For the full generated SDK surface, use the SDK reference for the language you are implementing.

For the config fields, see Configuration and Config File. For plugin-side opt-in, see Plugin. For the execution boundary, see Security.

AppS3