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

# Development Environment

Use this guide to set up the `Charm` repository for local development.

## Prerequisites

* Python 3.10 or newer.
* Git.
* [`uv`](https://github.com/astral-sh/uv).
* Docker Desktop or Docker Engine for runner and sandbox testing.

## Clone the Repository

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
git clone https://github.com/CharmAIOS/Charm.git
cd Charm
```

If you plan to submit a pull request, fork the repository first and clone your fork.

## Create a Virtual Environment

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
uv venv
```

Activate it:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
source .venv/bin/activate
```

On Windows PowerShell:

```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
.\.venv\Scripts\Activate.ps1
```

## Install Development Dependencies

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
uv pip install -e ".[runner,dev]"
```

## Build the Local Runner Base Image

Some runner tests and Docker sandbox flows require the base image:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
docker build -f Dockerfile.base -t charm-runner-base:latest .
```

## Run Tests

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pytest
```

## Validate a Template

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm init /tmp/my-agent --template python
charm validate /tmp/my-agent
```

## Before Opening a PR

* Run relevant tests.
* Update docs when behavior changes.
* Avoid committing secrets or local environment files.
* Fill out the PR template with test evidence and release notes.