Skip to main content

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.

This guide creates a minimal Charm agent, runs it locally, and shows how the project is structured.

​
1. Create a Project

Run: 
charm init my-first-agent --template python
cd my-first-agent
The python template is the smallest starting point. It is best when you want to learn the shape of a Charm project before choosing a larger framework such as LangChain, LangGraph, CrewAI, or OpenClaw.

​
2. Inspect the Project

A Charm project usually has this structure: 
my-first-agent/
├── charm.yaml
├── requirements.txt or pyproject.toml
└── src/
    └── main.py
The important files are:
  • charm.yaml: the manifest that describes your agent, input form, runtime, pricing, auth, and publishing metadata.
  • src/main.py: the agent implementation.
  • requirements.txt or pyproject.toml: Python dependencies installed when the agent runs.

​
3. Understand charm.yaml

charm.yaml is the contract between your code and the Charm platform. It defines:
  • the name, version, description, and store metadata,
  • the input schema shown to users,
  • the runtime adapter and entry point,
  • required environment variables,
  • execution mode and lifecycle,
  • policies such as internet access and max steps.
For a full schema walkthrough, see Manifest Reference.

​
4. Run Locally

If the template accepts a simple text input, run: 
charm run . --input "Hello world"
If your template expects structured JSON, run: 
charm run . --json '{"message": "Hello world"}'
Charm loads the manifest, prepares the input payload, runs the entry point, and prints the result.

​
5. Validate the Manifest

Before publishing, validate the project: 
charm validate .
Validation catches common issues such as:
  • invalid charm.yaml fields,
  • missing entry points,
  • unsupported adapter configuration,
  • problematic paths,
  • pricing or auth configuration mistakes.

​
6. Test in Docker

If you installed charmos[runner] and Docker is running, test in the local sandbox: 
charm run . --input "Hello world" --docker
Use Docker mode before publishing if your agent depends on system packages, browser support, or cloud-runtime behavior.

​
7. Next Steps