> ## 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.

# Create a Base Image

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`:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
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.