Custom Runtimes

Use a custom runtime when the official Charm base images are not enough — extra system packages, pre-baked models, a private fork of charmos, or a third-party adapter/telemetry/memory plugin baked into the image. runtime.custom_image tells the cloud runner which container image to pull. When set, it overrides the default adapter→image mapping from Base Images.

When you need this

Goal	Typical setup
Extra Python/system deps only	`type: custom` + `custom_image`
Third-party adapter plugin	`type: your_plugin` + `custom_image` with plugin installed
Telemetry plugin on cloud	Typically no custom_image needed (runner auto-installs via `requirements.txt`)
Private or pinned `charmos` version	Extend base image and install your SDK build

You do not need custom_image for a normal charm init Python agent that runs on the default runner-base image.

1. Create a Dockerfile

Extend the official base image:

[!WARNING] You must inherit from an official Charm base image. The cloud runner injects a bootstrap script and expects bash, python3, and the core charmos SDK to be pre-installed. Do not build from scratch (e.g., FROM ubuntu or FROM python:3.11).

FROM ghcr.io/charmaios/charm-base:latest

# System dependencies (example)
RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg \
    && rm -rf /var/lib/apt/lists/*

# Third-party plugin packages (examples)
RUN uv pip install charm-adapter-ag2 charm-telemetry-datadog

Build and push to a registry the runner can reach:

[!CAUTION] Always build for linux/amd64. The cloud runners (Google Cloud Run / Fly.io) run on amd64 architecture. If you are on an Apple Silicon Mac (M1/M2/M3) and build without the --platform linux/amd64 flag, your agent will crash with an exec format error.

docker build --platform linux/amd64 -t ghcr.io/your-org/my-agent-runtime:prod .
docker push ghcr.io/your-org/my-agent-runtime:prod

For Google Artifact Registry:

gcloud auth configure-docker us-central1-docker.pkg.dev
docker tag ghcr.io/your-org/my-agent-runtime:prod \
  us-central1-docker.pkg.dev/YOUR_PROJECT/charm-images/my-agent-runtime:prod
docker push us-central1-docker.pkg.dev/YOUR_PROJECT/charm-images/my-agent-runtime:prod

2. Declare the image in `charm.yaml`

version: "0.4.2"

persona:
  name: "My Custom Agent"
  description: "Runs on a custom runtime image"
  version: "0.1.0"

interface:
  input:
    type: object
    required: [input]
    properties:
      input: { type: string }
  output:
    type: string

runtime:
  custom_image: "ghcr.io/your-org/my-agent-runtime:prod"
  adapter:
    type: custom
    entry_point: src.main:agent
  lifecycle: serverless

The runner bundles your agent source code at execute time; the image supplies the environment (Python deps, plugins, system libs).

3. Publish and run

charm validate .
charm push .

Users trigger runs from the Store; the runner pulls custom_image and executes your bundle inside that container.

Registry access

Registry visibility	Requirement
Public (GHCR public, etc.)	Runner pulls without extra IAM
Private	Grant the cloud runner service account read access to your registry

Note on dynamic installation: The cloud runner does run uv pip install -r requirements.txt at boot time for lightweight dependencies (like Telemetry and Memory plugins). However, if your agent requires heavy ML packages, long compile times, or system-level dependencies (like ffmpeg), you must use a custom_image to avoid the 300-second boot timeout.

Community Plugins

You can discover custom runtimes built by the community in the Charm Store (Plugins Tab). If you have built a custom runtime that others might find useful (e.g., an image pre-configured with Chromium, specialized ML models, or custom data pipelines), you can submit it to the official registry:

Fork the charm-community-plugin repository.
Edit runtimes/registry.json to include your image’s metadata and URL.
Submit a Pull Request.

Once merged, your runtime will instantly appear in the Charm Store for others to use via the custom_image field.

Development

Customization

Publishing & Versioning

When you need this

1. Create a Dockerfile

2. Declare the image in `charm.yaml`

3. Publish and run

Registry access

Community Plugins

​When you need this

​1. Create a Dockerfile

​2. Declare the image in charm.yaml

​3. Publish and run

​Registry access

​Community Plugins

​Related

When you need this

1. Create a Dockerfile

2. Declare the image in `charm.yaml`

3. Publish and run

Registry access

Community Plugins

Related