Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.charmos.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Extensibility Overview

Charm separates a small stable core from community-owned extensions. Not every extension works the same way — some are runtime Python plugins, some are store contributions, and some are manifest PRs. Use this page to pick the right path before you start building.

​
Extension paths at a glance

What you want to addRegistrationRuns whereNeeds custom_image on cloud?Needs store deploy?
Custom adapter plugincharm.adapters entry pointAgent containerYesNo
Custom runtime onlyruntime.custom_image in YAMLAgent containerYesNo
Telemetry exportercharm.telemetry entry pointAgent containerYesNo
Memory backendcharm.memory entry pointAgent containerYes (if not built-in)No
Input form widgetsinterface.ui in YAMLStore UINoOnly for new widget types
Output renderers_charm_render_type in agent outputStore UINoOnly for new renderer types
Starter templatesPR to templates-manifest.jsoncharm initNoNo (manifest merge)

​
Two kinds of “custom” (important)

These names overlap — they are not the same thing:
TermMeaning
runtime.adapter.type: customBuilt-in Charm adapter for plain Python agents (CharmCustomAdapter in core). Good default for charm init projects.
runtime.custom_imageDocker image override for the cloud runner. Required for third-party adapter/telemetry/memory plugins.
Third-party adapter pluginNew adapter name (e.g. ag2, plugin_test) registered via [project.entry-points."charm.adapters"].
Scenario: you can use type: custom with custom_image (extra deps, no new adapter class).
Scenario: you can use type: ag2 with custom_image (new adapter plugin + image that installs it).
  1. Start from a normal agent — charm init my-agent --template python
  2. Add a pip package with your adapter/telemetry/memory classes and pyproject.toml entry points
  3. Point charm.yaml at your plugin — runtime.adapter.type: your_plugin_name
  4. Build a Docker image that installs your package (and compatible charmos) — see Custom Runtimes
  5. Set runtime.custom_image to that image URI
  6. charm validate → charm push → run on the Store
The cloud runner does not pip install your plugin at runtime. Your package must already be in the container image.

​
Built-in vs third-party

LayerBuilt-in (no plugin package)Third-party (plugin author)
Python agent logiccharm init + type: customSame
Adapter typecustom, langchain, openclaw, …New name via entry points
Runtime imageOfficial runner-* imagesYour custom_image
Store form widgetstext, textarea, fileNew widgets → store PR
Rich output UIBuilt-in _charm_render_type valuesNew types → store PR

​
Cloud prerequisites

For any custom image on production:
  1. Push the image to a registry the runner can pull (Artifact Registry, GHCR, etc.)
  2. Grant the runner service account read access to that registry (if private)
  3. Declare runtime.custom_image in charm.yaml — the runner selects it over default adapter images
See Base Images and Custom Runtimes.

​
Next steps

For core contributors merging adapters into the official SDK, see Write a Custom Adapter (in-repo process).