Skip to main content
Base images define the runtime environment used to execute agents.

​
Existing Base Images

Charm currently provides several pre-built base images depending on the adapter type:
  • Custom / Python (type: "custom" or "python"): Uses runner-base. Minimal Python environment for plain code agents.
  • LangChain (type: "langchain"): Uses runner-langchain.
  • LangGraph (type: "langgraph"): Uses runner-langchain (same image as LangChain).
  • CrewAI (type: "crewai"): Uses runner-crewai.
  • OpenClaw (type: "openclaw"): Uses runner-openclaw (Playwright, FFmpeg, OpenClaw engine).
  • Third-party adapter plugins: Use whatever image you declare in runtime.custom_image — the runner does not map plugin names automatically.
When runtime.custom_image is set, adapter→image mapping is ignored and your URI is used directly. Agents automatically select the correct base image based on their adapter.type, or explicitly override it using custom_image: 
runtime:
  custom_image: "ghcr.io/your-org/my-custom-image:latest"

​
Contribution Requirements

Base image changes should include:
  • clear reason for the new dependency,
  • size impact,
  • security impact,
  • local build validation,
  • runtime smoke test,
  • documentation update.

​
Best Practices

  • Keep images small.
  • Pin versions when practical.
  • Avoid installing unnecessary system packages.
  • Prefer reusable base layers.
  • Test both build and runtime behavior.

​
Before Opening a PR

Run the relevant Docker build and at least one agent smoke test using the image.