Skip to main content
The interface block in charm.yaml defines the JSON Schema for user inputs. The optional interface.ui block maps fields to Store form widgets. For all manifest fields, see the Manifest Reference.

​
Text inputs

interface:
  input:
    type: object
    required: [message]
    properties:
      message:
        type: string
        title: Message
        description: What should the agent do?
  output:
    type: string

​
Validation rules

      depth:
        type: integer
        title: Search Depth
        default: 3
        minimum: 1
        maximum: 5

​
Built-in UI widgets

Map fields to Store components with interface.ui: 
  ui:
    message: { "ui:widget": "textarea" }
    upload: { "ui:widget": "file" }
Supported built-in widgets today:
WidgetDescription
textSingle-line input (default). Shows number spinner if type is integer/number.
textareaMulti-line input
fileFile upload — runner receives the uploaded file path in inputs
selectDropdown menu based on the enum property in your schema
checkboxBoolean toggle switch
sliderSlider based on minimum and maximum schema properties
Legacy templates may use x-ui-widget on individual properties; the Store still resolves those for backward compatibility. Unknown widget names fall back to text.

​
Access inputs in code

def agent(inputs):
    message = inputs.get("message")
    depth = inputs.get("depth", 3)
    return f"Processed: {message} (depth={depth})"
File fields are injected by the runner/store pipeline — use the key name from your schema.

​
Adding custom UI Widgets (Community Plugins)

If you need a specialized input widget (like a code editor, color picker, or map selector), you can build and share it dynamically using the Charm Community Plugin registry.
  1. Build a React Component: Your component must implement the FieldProps interface and be exported as the default export.
  2. Publish: Publish your component as an ESM-compatible NPM package.
  3. Register: Submit a Pull Request to the charm-community-plugin repository. Add your widget to widgets/registry.json.
Once your PR is merged, any agent developer can use your widget instantly by specifying its id in their ui:widget config. The Charm Store will dynamically download and render your NPM package on the fly—no platform redeploys required!