Installation - Charm Docs

Install Charm locally so you can create, validate, run, and publish agents from your terminal.

Prerequisites

Before installing Charm, make sure you have:

Python 3.10 or newer.
pip or uv.
Git.
Docker Desktop or Docker Engine if you want to test agents in the local container sandbox.

uv is recommended because it creates fast, reproducible Python environments.

For agent development:

uv add charmos

For local runner and Docker sandbox testing:

uv add "charmos[runner]"

For agent development:

pip install charmos

For local runner and Docker sandbox testing:

pip install "charmos[runner]"

Run:

charm --help

You should see the available Charm commands, including init, run, validate, push, logs, and auth.

If you are working inside an agent repository, create and activate a virtual environment first.

python -m venv .venv

On macOS or Linux:

source .venv/bin/activate

On Windows PowerShell:

.\.venv\Scripts\Activate.ps1

Then install Charm:

pip install "charmos[runner]"

Charm can run agents locally in a container that more closely matches the cloud runtime. To use sandbox mode:

charm run . --input "Hello from Docker" --docker