Managing Golem Plugins

Plugins extend component and agent behavior without modifying application code. Currently, the only plugin type is Oplog Processor — a WASM component that receives and processes the operation log entries produced by agents (e.g., exporting traces, logs, or metrics).

Built-in Plugins

Golem ships with the following built-in plugins, automatically registered and available in every environment:

golem-otlp-exporter Parameters

Installing Plugins via golem.yaml

Add plugins to a component or agent in golem.yaml using the plugins field:

components:
  my-app:service:
    plugins:
      - name: golem-otlp-exporter
        version: "1.5.8"
        parameters:
          endpoint: "http://localhost:4318"
          signals: "traces,logs,metrics"
 
agents:
  MyAgent:
    plugins:
      - name: golem-otlp-exporter
        version: "1.5.8"
        parameters:
          endpoint: "https://otel-collector.example.com:4318"
          headers: "x-api-key=my-secret-key"
          signals: "traces,logs"
          service-name-mode: "agent-type"

Plugin Installation Fields

Template Substitution in Plugin Parameters

Plugin parameter values support Jinja-style template substitution using {{ VAR_NAME }}. At deploy time, these are resolved against the host machine’s environment variables:

plugins:
  - name: golem-otlp-exporter
    version: "1.5.8"
    parameters:
      endpoint: "{{ OTLP_ENDPOINT }}"
      headers: "x-api-key={{ OTLP_API_KEY }}"

If a referenced variable is missing, deployment fails with the list of unresolved variables. See the golem-add-env-vars skill for full details on the substitution syntax.

Using Templates

Plugins can be defined in componentTemplates and inherited via the cascade system:

componentTemplates:
  observability:
    plugins:
      - name: golem-otlp-exporter
        version: "1.5.8"
        parameters:
          endpoint: "http://localhost:4318"
          signals: "traces,logs,metrics"
 
components:
  my-app:service:
    templates: [rust, observability]

Plugin Merge Modes

When plugins are inherited from templates, the pluginsMergeMode field controls how they combine:

components:
  my-app:service:
    templates: [observability]
    pluginsMergeMode: replace
    plugins: []                    # Remove all inherited plugins

Per-environment Plugin Configuration

Use presets and environments to vary plugin parameters across deployment targets:

Use the environment selector app-env:production. A plain production custom preset can become the default custom preset when it is the only one, applying the production endpoint in every environment.

CLI output masking depends on the parameter name, not its value or the environment variable used to populate it. The OTLP plugin’s headers parameter is not a sensitive-looking name, so credentials inside it are not masked in output such as component get, component manifest-trace, and deployment diffs. Environment substitution does not change this. Keep the plugin-defined name headers; renaming it to trigger masking breaks plugin configuration. Treat these outputs as sensitive and do not copy credential-bearing output into logs or shared transcripts.

components:
  my-app:service:
    plugins:
      - name: golem-otlp-exporter
        version: "1.5.8"
        parameters:
          endpoint: "http://localhost:4318"
    presets:
      app-env:production:
        pluginsMergeMode: replace
        plugins:
          - name: golem-otlp-exporter
            version: "1.5.8"
            parameters:
              endpoint: "https://otel.prod.example.com:4318"
              headers: "x-api-key={{ OTLP_API_KEY }}"
              signals: "traces,logs,metrics"
 
environments:
  local:
    server: local
    componentPresets: debug
  production:
    server: cloud
    componentPresets: app-env:production

Managing Plugins via CLI

Listing Available Plugins

golem plugin list
golem plugin list --account owner@example.com
golem plugin list --account-id 2f6b30d9-bac2-4c67-9d4f-12ea89ba2211

With no account option, the list includes plugins owned by the authenticated account and plugins granted to the selected environment. An explicit account lists plugins owned by that account. --account and --account-id conflict.

Inspecting and unregistering registry plugins

golem plugin get my-plugin 1.0.0
golem plugin get --id 8fd5e4a2-9cab-4f8e-9d3a-1c2e4f567890
golem plugin unregister my-plugin 1.0.0
golem plugin unregister --id 8fd5e4a2-9cab-4f8e-9d3a-1c2e4f567890

The name and version form requires both positional values and accepts --account or --account-id. The --id form conflicts with the positional identity and account scope. A positional UUID is a name, not an ID; use --id explicitly.

Register a plugin from a JSON or YAML manifest, optionally for an explicit account:

golem plugin register ./my-plugin.yaml
golem plugin register ./my-plugin.yaml --account owner@example.com

The manifest requires name, version, description, icon, homepage, and specs. The registry currently accepts OplogProcessor specs, which identify the oplog-processor component with componentId and componentRevision.

Plugin installation is declarative. The retired component plugin and project plugin workflows are not available. Define installations in golem.yaml; golem deploy reconciles the manifest with deployed state.

Plugin Priority

When multiple plugins are installed, the order in the manifest’s plugins list determines priority (first entry = highest priority).

Documentation

• App manifest reference: https://learn.golem.cloud/app-manifest 
• Full docs: https://learn.golem.cloud 

Related Guides

• For enabling the built-in golem-otlp-exporter plugin and exporting telemetry from agents, load the language-specific skill: golem-enable-otlp-rust, golem-enable-otlp-ts, golem-enable-otlp-scala, or golem-enable-otlp-moonbit