Plugin Manifest Reference

Every plugin provides a manifest in HCL format via the GetManifest RPC. The platform uses this to discover plugin metadata without loading the full plugin.

Format

plugin "plugin-name" {
  version     = "1.0.0"
  description = "What this plugin does."
  author      = "yourorg"
  icon        = "icon-name"
  type        = "remote"

  # Optional: define configuration fields the workspace admin sets
  config_schema {
    field "api_key_env" {
      type        = "string"
      required    = true
      description = "Environment variable containing the API key"
    }

    field "default_model" {
      type    = "string"
      default = "gpt-4"
      options = ["gpt-4", "gpt-3.5-turbo"]
    }
  }
}

Fields

Plugin Block

Field	Type	Required	Description
`version`	string	yes	Semantic version (e.g. `"1.0.0"`)
`description`	string	yes	Human-readable description
`author`	string	yes	Author name or organization
`icon`	string	no	Icon identifier for the UI
`type`	string	yes	`"local"` (subprocess) or `"remote"` (standalone gRPC server)

Config Schema Block (optional)

Defines configuration fields that workspace administrators set when adding the plugin. Configuration values are passed to the plugin via RegisterRequest.config.

Field Block

Attribute	Type	Default	Description
`type`	string	required	`"string"`, `"number"`, `"bool"`
`ui_type`	string	auto	Override widget type: `"text"`, `"number"`, `"checkbox"`, `"radio"`, `"select"`
`required`	bool	`false`	Whether the field is required
`default`	string	none	Default value
`description`	string	`""`	Help text
`options`	list	none	Allowed values (renders as a searchable select in the UI)
`pattern`	string	none	Regex pattern for validation
`placeholder`	string	`""`	Placeholder text for the input
`api_source`	string	none	URL for dynamic select options (response: `[{"value":"...","label":"..."}]`)

UI widget derivation rules:

type="string" with no options → text input
type="string" with options → searchable select (default) or radio if ui_type="radio"
type="number" → number input
type="bool" → checkbox
api_source set → searchable select that fetches options from API

All selects are searchable by default.

Examples

config_schema {
  field "api_key_env" {
    type        = "string"
    required    = true
    placeholder = "e.g. MY_API_KEY"
    description = "Environment variable containing your API key"
  }

  field "region" {
    type    = "string"
    options = ["us-east-1", "us-west-2", "eu-west-1"]
    default = "us-east-1"
    description = "AWS region for the service"
  }

  field "region_dynamic" {
    type       = "string"
    api_source = "https://api.example.com/regions"
    description = "Select a region (fetched from API)"
  }

  field "deployment_mode" {
    type    = "string"
    ui_type = "radio"
    options = ["production", "staging", "development"]
    default = "development"
  }

  field "max_retries" {
    type    = "number"
    default = "3"
    description = "Maximum retry attempts"
  }

  field "verbose_logging" {
    type    = "bool"
    default = "false"
    description = "Enable detailed debug logging"
  }
}

Workspace Configuration

Plugins are added to workspaces in the workspace HCL config:

Local Plugin

workspace "my-workspace" {
  plugin "my-plugin" {
    source = "path/to/binary"

    config {
      api_key_env = "MY_API_KEY"
    }
  }
}

Remote Plugin

workspace "my-workspace" {
  plugin "my-plugin" {
    source  = "remote://host:port"
    version = "1.0.0"

    config {
      api_key_env = "MY_API_KEY"
    }
  }
}

The config block values are sent in RegisterRequest.config. For remote plugins, workspace environment variables are also sent in RegisterRequest.env_vars since the remote process can't read them from its own environment.