# Agent Adapters
Source: https://docs.charmos.io/adapters/overview



Adapters tell Charm how to call your agent code.

Different frameworks expose different runtime objects, so the adapter bridges your code to the Charm runner.

## Supported Adapter Types

| Type        | Best For                                     | Entry Point Style |
| ----------- | -------------------------------------------- | ----------------- |
| `custom`    | Plain Python functions/classes               | `module:object`   |
| `langchain` | LangChain chains/runnables                   | `module:chain`    |
| `langgraph` | LangGraph graphs                             | `module:graph`    |
| `crewai`    | CrewAI crews                                 | `module:crew`     |
| `openclaw`  | OpenClaw/browser-tool agents                 | OpenClaw host     |
| `hermes`    | Self-improving agents with persistent memory | `module:agent`    |

## Configure an Adapter

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  adapter:
    type: "custom"
    entry_point: "src.main:agent"
```

## Choosing an Adapter

* Use `custom` for Python agent that do not use any frameworks.
* Use `langchain`, `langgraph`, or `crewai` when you already use that framework.
* Use `openclaw` for OpenClaw based agents.
* Use `hermes` for Nous Research Hermes agents with self-improving skills and persistent memory.

## Third-party adapter plugins

Any pip package can register additional `runtime.adapter.type` values via `[project.entry-points."charm.adapters"]`. These require a [custom runtime image](/guides/custom-runtimes) on the cloud runner. See [Extensibility Overview](/guides/extensibility) and [Custom Adapters](/guides/custom-adapters).

## Adapter Types

* [Custom](/adapters/custom)
* [LangChain](/adapters/langchain)
* [LangGraph](/adapters/langgraph)
* [CrewAI](/adapters/crewai)
* [OpenClaw](/adapters/openclaw)
* [Hermes](/adapters/hermes)


# Create Agent
Source: https://docs.charmos.io/api-reference/agents/create-agent

/openapi.json post /v1/agents
Create a new agent



# Delete Agent
Source: https://docs.charmos.io/api-reference/agents/delete-agent

/openapi.json delete /v1/agents/{agent_id}
Delete an agent



# Get Agent
Source: https://docs.charmos.io/api-reference/agents/get-agent

/openapi.json get /v1/agents/{agent_id}
Get an agent by ID



# List Agents
Source: https://docs.charmos.io/api-reference/agents/list-agents

/openapi.json get /v1/agents
List agents



# Update Agent
Source: https://docs.charmos.io/api-reference/agents/update-agent

/openapi.json patch /v1/agents/{agent_id}
Update an agent



# Create Subscription
Source: https://docs.charmos.io/api-reference/billing/create-subscription

/openapi.json post /v1/billing/subscriptions
Create subscription



# Get Subscription
Source: https://docs.charmos.io/api-reference/billing/get-subscription

/openapi.json get /v1/billing/subscriptions/{subscription_id}
Get subscription by ID



# Get Wallet
Source: https://docs.charmos.io/api-reference/billing/get-wallet

/openapi.json get /v1/billing/wallet
Get user's wallet balance



# List Subscriptions
Source: https://docs.charmos.io/api-reference/billing/list-subscriptions

/openapi.json get /v1/billing/subscriptions
List subscriptions



# Record Transaction
Source: https://docs.charmos.io/api-reference/billing/record-transaction

/openapi.json post /v1/billing/transactions
Record a transaction



# Stripe Webhook
Source: https://docs.charmos.io/api-reference/billing/stripe-webhook

/openapi.json post /v1/billing/webhook-event
Handle Stripe webhook



# Control Daemon
Source: https://docs.charmos.io/api-reference/daemons/control-daemon

/openapi.json post /v1/daemon/{agent_id}/control
Control daemon



# Create Daemon
Source: https://docs.charmos.io/api-reference/daemons/create-daemon

/openapi.json post /v1/daemons
Create daemon



# Get Daemon Status
Source: https://docs.charmos.io/api-reference/daemons/get-daemon-status

/openapi.json get /v1/daemon/{agent_id}/status
Get daemon status



# List Daemons
Source: https://docs.charmos.io/api-reference/daemons/list-daemons

/openapi.json get /v1/daemons
List daemons



# Start Daemon
Source: https://docs.charmos.io/api-reference/daemons/start-daemon

/openapi.json post /v1/daemon/{agent_id}/start
Start daemon



# Stop Daemon
Source: https://docs.charmos.io/api-reference/daemons/stop-daemon

/openapi.json post /v1/daemon/{agent_id}/stop
Stop daemon



# Execute Agent
Source: https://docs.charmos.io/api-reference/execute/execute-agent

/openapi.json post /v1/execute
Execute an AI agent with input payload and stream results via SSE



# Cancel Run
Source: https://docs.charmos.io/api-reference/runs/cancel-run

/openapi.json post /v1/runs/{run_id}/cancel
Cancel a running run



# Complete Run
Source: https://docs.charmos.io/api-reference/runs/complete-run

/openapi.json post /v1/runs/{run_id}/complete
Mark run as complete



# Get Run
Source: https://docs.charmos.io/api-reference/runs/get-run

/openapi.json get /v1/runs/{run_id}
Get run status and result



# Get Run Events
Source: https://docs.charmos.io/api-reference/runs/get-run-events

/openapi.json get /v1/runs/{run_id}/events
Get events for a run



# Update Progress
Source: https://docs.charmos.io/api-reference/runs/update-progress

/openapi.json post /v1/runs/{run_id}/progress
Update run progress



# Get Agent Errors
Source: https://docs.charmos.io/api-reference/studio/get-agent-errors

/openapi.json get /v1/studio/agents/{agent_id}/errors
Get error breakdown



# Get Agent Installs
Source: https://docs.charmos.io/api-reference/studio/get-agent-installs

/openapi.json get /v1/studio/agents/{agent_id}/installs
Get installation counts by day



# Get Agent Runs Chart
Source: https://docs.charmos.io/api-reference/studio/get-agent-runs-chart

/openapi.json get /v1/studio/agents/{agent_id}/runs
Get run counts grouped by day



# Get Agent Stats
Source: https://docs.charmos.io/api-reference/studio/get-agent-stats

/openapi.json get /v1/studio/agents/{agent_id}/stats
Get aggregate stats for an agent



# Get Latency Distribution
Source: https://docs.charmos.io/api-reference/studio/get-latency-distribution

/openapi.json get /v1/studio/agents/{agent_id}/latency-distribution
Get latency distribution



# Get Session Depth
Source: https://docs.charmos.io/api-reference/studio/get-session-depth

/openapi.json get /v1/studio/agents/{agent_id}/session-depth
Get session depth distribution



# Get Studio Agents
Source: https://docs.charmos.io/api-reference/studio/get-studio-agents

/openapi.json get /v1/studio/agents
List agents owned by authenticated user



# Get Token Distribution
Source: https://docs.charmos.io/api-reference/studio/get-token-distribution

/openapi.json get /v1/studio/agents/{agent_id}/token-distribution
Get token usage distribution



# Get Usage Log
Source: https://docs.charmos.io/api-reference/studio/get-usage-log

/openapi.json get /v1/studio/agents/{agent_id}/usage-log
Get detailed usage logs



# Get Thread Runs
Source: https://docs.charmos.io/api-reference/threads/get-thread-runs

/openapi.json get /v1/threads/{thread_id}/runs
List all runs for a thread



# Get Agent Versions
Source: https://docs.charmos.io/api-reference/versions/get-agent-versions

/openapi.json get /v1/versions/{agent_id}
Get all versions for an agent



# Rollback Agent
Source: https://docs.charmos.io/api-reference/versions/rollback-agent

/openapi.json post /v1/rollback
Rollback agent to previous version



# Upgrade Agent
Source: https://docs.charmos.io/api-reference/versions/upgrade-agent

/openapi.json post /v1/upgrade
Upgrade agent to new version



# Changelog
Source: https://docs.charmos.io/changelog/overview



This page will become the docs entry point for Charm release notes.

Use the changelog to understand what changed between releases, whether you need to upgrade, and which operational steps are required.

## Planned Sections

* Latest release.
* Recent changes.
* Breaking changes.
* Migration notes.
* Older releases.

## Release Categories

Charm release notes should group changes into:

* Features.
* Fixes.
* Breaking changes.
* Infrastructure and migrations.
* Documentation.
* Internal maintenance.

## What to Look For

Before upgrading, check:

* required SDK or CLI version,
* `charm.yaml` compatibility changes,
* migration or deploy requirements,
* runtime image changes,
* billing/auth/security notes,
* known issues.

## Release Notes

Charm uses Release Drafter to prepare draft GitHub Releases from merged pull requests.
Release owners should review the generated draft, fill in the summary and upgrade notes, then publish it from GitHub Releases.

## Source of Truth

GitHub Releases are the source of truth for published changelogs.
The docs changelog should link to published releases and only duplicate release text when a docs-native archive is needed.

## Pull Request Labels

Every user-facing pull request should include one release label:

* `release:feature` for new capabilities.
* `release:fix` for bug fixes.
* `release:breaking` for incompatible API, CLI, runtime, or manifest changes.
* `release:security` for security fixes or hardening.
* `release:infra` for deployment, runner, billing, auth, or migration changes.
* `release:docs` for documentation-only changes.
* `release:chore` for internal maintenance that should still appear in release notes.
* `release:skip` for changes that should not appear in release notes.

Use `release:major`, `release:minor`, or `release:patch` only when the default version bump from the category label is not correct.

The release label check requires exactly one category label on every pull request.
The label sync workflow creates and updates these labels in GitHub when the workflow runs.


# Release Notes Template
Source: https://docs.charmos.io/changelog/release-notes



Use this structure when reviewing the draft GitHub Release generated by Release Drafter.

## Template

Release Drafter creates a draft GitHub Release after changes are merged to `main`.
Before publishing, release owners should edit the draft body so it follows this structure.

Each section should be concise and user-facing:

* Explain why the change matters.
* Link related PRs or issues.
* Call out migration and deploy requirements.
* Include rollback or mitigation notes for infrastructure changes.

## Pull Request Inputs

Release notes are generated from pull request titles, authors, numbers, and `release:*` labels.
Use a clear PR title and fill in the Release Notes section in the PR template so the release owner can quickly rewrite the generated draft into public-facing language.

## Example

```markdown theme={"theme":{"light":"min-light","dark":"min-dark"}}
## v0.5.0 - 2026-05-11

### Summary

This release adds the first public open-source docs skeleton and release process.

### Features

- Added docs pages for templates, references, and open-source contribution.

### Fixes

- Fixed broken navigation entries.

### Breaking Changes

- None.

### Infrastructure and Migrations

- None.

### Documentation

- Added release process and docs versioning pages.

### Upgrade Notes

- No action required.

### Known Issues

- Some pages are still first-pass content and need final design.
```


# charm auth
Source: https://docs.charmos.io/cli/auth



Manage the local credentials used by the Charm CLI.

## Sign In

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm auth login
```

This opens the browser-based login flow and stores a local token for future commands such as `charm push` and `charm logs`.

## Check Current User

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm auth whoami
```

Use this before publishing if you are unsure which account the CLI will use.

## Manual Token

For headless environments or CI-style workflows:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm auth manual --token <TOKEN>
```

Only use manual tokens in trusted environments.

## Sign Out

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm auth logout
```

This removes local Charm credentials.

## Credential Storage

The CLI stores local configuration under the user's Charm config directory, commonly `~/.charm/config.toml`.

Do not commit local credential files.


# charm config
Source: https://docs.charmos.io/cli/config



Manage local configuration settings for the Charm CLI.

## Usage

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm config [command]
```

## Commands

### 1. Set a Configuration Value

Use `charm config set` to update a specific configuration value. Keys are formatted as `section.key`.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm config set core.api_base {api_base_url}
```

### 2. List Configuration

Use `charm config list` to view all your current local configuration settings.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm config list
```

## Storage

Configuration is saved locally, typically in `~/.charm/config.toml`. Do not commit this file to version control.


# charm init
Source: https://docs.charmos.io/cli/init



Scaffold a new Charm agent project.

## Usage

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm init <name> [--template <template>] [--create <file>] [--interactive]
```

## Common Examples

Create a minimal Python agent:

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

Start an interactive prompt for template selection:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm init my-agent --interactive
```

Create a single file from a template:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm init . --create charm.yaml
```

## Options

| Option                | Description                                                                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`                | Agent directory path. Use `.` for the current directory.                                                                                                     |
| `--template`          | Template to use. Defaults to `python`. Valid values are fetched dynamically from the community templates registry (e.g., `python`, `openclaw`, `slack-bot`). |
| `--create`            | Create a single file instead of a full project.                                                                                                              |
| `--interactive`, `-i` | Launch guided template selection.                                                                                                                            |

## Generated Structure

Most templates produce:

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
my-agent/
├── charm.yaml
├── requirements.txt or pyproject.toml
└── src/
    └── main.py
```

After scaffolding, run:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
cd my-agent
charm validate .
charm run . --input "Hello"
```


# charm logs
Source: https://docs.charmos.io/cli/logs



Fetch recent cloud execution logs for an agent from the terminal.

## Usage

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm logs --path . --limit 50
```

## Options

| Option          | Description                                                   |
| --------------- | ------------------------------------------------------------- |
| `--path`        | Path to the Charm project. Defaults to the current directory. |
| `--limit`, `-l` | Number of recent log entries to fetch. Defaults to 50.        |
| `--api-base`    | Override the platform API base URL.                           |
| `--debug`       | Print additional diagnostic output.                           |

## Requirements

* You must be authenticated with `charm auth login`.
* The project must have a `charm.yaml` with an agent ID.
* The agent must have cloud run history.

## When to Use

Use `charm logs` when:

* a published agent fails in the Store,
* a cloud run behaves differently from local execution,
* you need quick terminal access without opening Studio.

For deeper analysis, use the Studio and observability pages in the platform UI.


# charm push
Source: https://docs.charmos.io/cli/push



Publish a Charm agent version to Charm Store.

`charm push` validates the manifest, bundles the project, uploads it, and creates or updates the published agent version.

## Usage

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm push [path] [--dry-run]
```

If no path is provided, Charm pushes the current directory.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm push .
```

## Before Pushing

Authenticate first:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm auth login
```

Validate the project:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm validate .
```

Run locally:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input "Hello"
```

## Dry Run

Preview the payload without publishing:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm push . --dry-run
```

Use this to inspect metadata and bundle behavior before creating a Store version.

## Bundle Rules

Charm packages your project source and manifest into a bundle.

Use `.charmignore` to exclude files that should not be uploaded, such as:

* local virtual environments,
* large generated files,
* secrets,
* local datasets,
* build artifacts.

Never commit or publish private credentials.

## Versioning

Update `persona.version` in `charm.yaml` when publishing a new version. If the same version already exists, the Store may reject the push.

## After Publishing

After a successful push:

* open the agent in Charm Store,
* run a smoke test,
* verify required keys/OAuth connections,
* check logs if execution fails.


# charm run
Source: https://docs.charmos.io/cli/run



Run a Charm agent locally.

Use `charm run` while developing agent logic, testing input schemas, and checking runtime compatibility before publishing.

## Usage

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run [path] [--input <text>] [--json <payload>] [--input-file <file>] [--docker]
```

## Simple Text Input

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input "Write a short welcome message"
```

## JSON Input

Use JSON when your `interface.input` defines multiple fields:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --json '{"message": "Hello", "tone": "friendly"}'
```

## Input File

Use `--input-file` for repeatable test cases:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input-file test-cases.json
```

Example test file:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
[
  {
    "name": "Basic greeting",
    "input": {
      "message": "Hello"
    }
  }
]
```

## Docker Sandbox

Run inside a container to better match the cloud runtime:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input "Hello" --docker
```

Docker mode requires `charmos[runner]` and a running Docker daemon.

## Mocked Integrations

For agents that require OAuth or skills, local mocks can speed up testing:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --json '{"message": "Check my calendar"}' --mock-oauth
charm run . --json '{"message": "Use a skill"}' --mock-skills
```

## Debugging

Add `--debug` for extra logs:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input "Hello" --debug
```


# charm validate
Source: https://docs.charmos.io/cli/validate



Validate a Charm agent before running or publishing it.

## Usage

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm validate [path]
```

If no path is provided, Charm validates the current directory.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm validate .
```

## What It Checks

Validation catches common project issues, including:

* missing `charm.yaml`,
* invalid manifest schema,
* unsupported adapter type,
* invalid auth provider names,
* missing or invalid entry point,
* absolute paths that will not work in cloud runtimes,
* pricing configuration issues,
* policy configuration issues,
* interface and state schema issues.

## When to Run It

Run validation:

* after editing `charm.yaml`,
* before `charm push`,
* before opening a PR for a template,
* before testing in Docker.

## Fixing Errors

Common fixes:

* Make sure `charm.yaml` is at the project root.
* Confirm `runtime.adapter.entry_point` points to an importable object.
* Use supported lifecycle values: `serverless`, `interactive`, or `daemon`.
* Declare secrets as environment variables instead of hardcoding them.
* Use relative paths instead of machine-specific absolute paths.

## Next Step

After validation passes, run locally:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input "Hello"
```


# .charmignore
Source: https://docs.charmos.io/guides/charmignore



`.charmignore` controls which files are excluded when `charm push` bundles your project.

## Why It Matters

Exclude files that are large, private, generated, or irrelevant to runtime execution.

## Example

```gitignore theme={"theme":{"light":"min-light","dark":"min-dark"}}
.env
.venv/
node_modules/
__pycache__/
.git/
dist/
build/
*.log
*.csv
```

## Best Practices

* Never publish secrets.
* Exclude virtual environments.
* Exclude local datasets unless the agent truly needs them.
* Exclude build caches.
* Keep bundles small and reproducible.

## Before Publishing

Use:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm push . --dry-run
```

to inspect what will be uploaded.


# Community Templates
Source: https://docs.charmos.io/guides/community-templates



`charm init` scaffolds new agents from a remote manifest — not from files bundled inside the installed `charmos` wheel. That lets the community add templates without waiting for an SDK release.

## How it works

When you run `charm init`, the CLI fetches:

```
https://raw.githubusercontent.com/CharmAIOS/charm-community-plugin/main/templates/registry.json
```

Each manifest entry lists files (as JSON strings) to write into the new project directory. After a PR merges to **`main`**, the template is available globally on the next `charm init`.

Offline fallback: if the manifest cannot be fetched, the CLI scaffolds a minimal Python template.

## Contributing a template

You **do not** write Python loader code — only a JSON entry in the manifest.

### Step 1: Prepare your template entry

> \[!TIP]
> **Discoverability:** Templates merged into this manifest are automatically displayed in the **[Charm Store Templates Registry](https://store.charmos.io/templates)** for the whole community to discover and scaffold.

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "id": "my-sales-agent",
  "description": "Sales outreach agent starter",
  "author": "Your Name",
  "tags": ["sales", "outreach"],
  "github_url": "https://github.com/YourOrg/your-repo",
  "post_init_message": "  ├── charm.yaml\n  ├── .charmignore\n  └── src/\n      └── main.py\n\nNext: charm push",
  "files": [
    {
      "path": "charm.yaml",
      "content": "version: \"0.4.2\"\n\npersona:\n  name: \"My Sales Agent\"\n  description: \"A sales agent starter.\"\n  version: \"0.1.0\"\n\ninterface:\n  input:\n    type: object\n    required: [message]\n    properties:\n      message: { type: string, title: Message }\n  output:\n    type: string\n\nruntime:\n  adapter:\n    type: custom\n    entry_point: src.main:agent\n  lifecycle: serverless\n"
    },
    {
      "path": ".charmignore",
      "content": ".env\n.venv\n__pycache__/\n*.pyc\n"
    },
    {
      "path": "src/__init__.py",
      "content": ""
    },
    {
      "path": "src/main.py",
      "content": "def agent(inputs):\n    msg = inputs.get('message', 'hello')\n    return f'Sales draft for: {msg}'\n"
    }
  ]
}
```

**Tips:**

* `id` must be unique **kebab-case** — used as `charm init my-agent --template my-sales-agent`
* `author`, `tags`, and `github_url` help users discover your template in the Store Registry.
* Include `version: "0.4.2"` in `charm.yaml` content (required contract version)
* Use `type: custom` (or `python`, an alias) for standard Python agents — not a fictional adapter name unless you document a required plugin
* Escape newlines as `\n` and quotes as `\"` inside JSON strings
* Rich templates can include `interface.ui` for Store widgets — see [Input Forms](/guides/interface)

### Step 2: Open a pull request

1. Fork [CharmAIOS/charm-community-plugin](https://github.com/CharmAIOS/charm-community-plugin)
2. Append your object to the `templates` array in `templates/registry.json`
3. Submit a PR for review

After merge to `main`, your template appears in `charm init` (interactive menu or `--template <id>`).

## Templates vs runtime plugins

|                     | Community template                                  | Adapter plugin               |
| ------------------- | --------------------------------------------------- | ---------------------------- |
| Delivers            | Starter files for `charm init`                      | New `runtime.adapter.type`   |
| Registration        | Manifest PR                                         | `charm.adapters` entry point |
| Custom Docker image | Only if template's `charm.yaml` sets `custom_image` | Required on cloud            |

## Related

* [Extensibility Overview](/guides/extensibility)
* [Build Your First Agent](/quickstart/first-app)
* [Configuration](/guides/manifest)


# Custom Adapters
Source: https://docs.charmos.io/guides/custom-adapters



Use this guide when you are a **plugin author** integrating a new Python framework (AG2, AutoGen, an internal runtime, etc.) — not when you only need a plain Python function agent.

> **Using plain Python only?** You probably want the built-in **`custom`** adapter from `charm init --template python`. See [Custom Python Adapter](/adapters/custom). This guide is for registering a **new adapter name** via entry points.

## How discovery works

Charm loads adapters from Python **`entry_points`** in the `charm.adapters` group. The name you register becomes a valid `runtime.adapter.type` in `charm.yaml`.

Official adapters (`langchain`, `crewai`, `openclaw`, `custom`, …) use the same mechanism in the `charmos` package. Third-party packages add more names without forking core.

### 1. Get the Boilerplate

> \[!TIP]
> **Fastest Path:** You do not need to write this from scratch. Use the official **[charm-adapter-template](https://github.com/CharmAIOS/charm-adapter-template)** repository on GitHub. Click **Use this template**, rename the folder, and jump straight to implementing your `invoke` method.

If you are doing it manually, start by scaffolding a plain project:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm init my-ag2-agent --template python
cd my-ag2-agent
```

This scaffolds `charm.yaml`, `src/main.py`, and `.charmignore`. You will add a **separate installable package** (or a `pyproject.toml` in the same repo) for the adapter plugin.

### 2. Implement `BaseAdapter`

Your class must inherit from `charm.adapters.base.BaseAdapter` and implement `invoke`.

```python theme={"theme":{"light":"min-light","dark":"min-dark"}}
from typing import Any, Dict, List, Optional
from charm.adapters.base import BaseAdapter

class Ag2Adapter(BaseAdapter):
    def invoke(
        self, inputs: Dict[str, Any], callbacks: Optional[List[Any]] = None
    ) -> Dict[str, Any]:
        # self.agent is the object imported from runtime.adapter.entry_point
        result = self.agent.run(**inputs)
        return {
            "status": "success",
            "output": result,
        }
```

The loader constructs your adapter as `AdapterClass(agent_instance=..., config=...)` after importing the user's entry point from `charm.yaml`.

Return a dict with `"status": "success"` and `"output"` for standard Store rendering, or include structured keys like `_charm_render_type` (see [Output Renderers](/guides/output-renderers)).

### 3. Register via entry points

In your plugin package's `pyproject.toml`:

```toml theme={"theme":{"light":"min-light","dark":"min-dark"}}
[project]
name = "charm-adapter-ag2"
version = "0.1.0"
dependencies = ["charmos"]

[project.entry-points."charm.adapters"]
ag2 = "charm_adapter_ag2.adapter:Ag2Adapter"
```

Install locally while developing:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pip install -e ./path/to/charm-adapter-ag2
pip install -e ./path/to/my-ag2-agent   # if separate
```

Verify discovery:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
python -c "from importlib.metadata import entry_points; print([e.name for e in entry_points(group='charm.adapters')])"
```

`charm validate` should accept `runtime.adapter.type: ag2` after your package is installed.

### 4. Configure `charm.yaml`

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
version: "0.4.2"

persona:
  name: "My AG2 Agent"
  description: "Agent using a third-party adapter plugin"
  version: "0.1.0"

interface:
  input:
    type: object
    required: [message]
    properties:
      message: { type: string }
  output:
    type: string

runtime:
  adapter:
    type: ag2
    entry_point: src.main:my_agent
  lifecycle: serverless
```

### 5. Cloud execution requires a custom image

The cloud runner **will automatically `uv pip install` your adapter if it is listed in the user's `requirements.txt`**. However, if your adapter depends on massive libraries (like PyTorch or large LLM frameworks), `uv pip install` might timeout during Cloud Run startup.

For heavy adapters, you should provide a custom image:

1. Build a Docker image based on [charm-base](https://github.com/CharmAIOS/Charm/pkgs/container/charm-base) or an official runner image
2. `RUN uv pip install charm-adapter-ag2` (or `pip install`) inside the Dockerfile
3. Set `runtime.custom_image` to the pushed image URI

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  custom_image: "ghcr.io/your-org/my-ag2-runtime:prod"
  adapter:
    type: ag2
    entry_point: src.main:my_agent
```

### 6. Submit to the Charm Store

To make your adapter discoverable by the global Charm community:

1. Fork the [charm-community-plugin](https://github.com/CharmAIOS/charm-community-plugin) repository.
2. Edit `adapters/registry.json` to add your package name (`charm-adapter-ag2`).
3. Submit a Pull Request.

Once merged, your adapter will instantly appear in the **Charm Store Plugins Gallery**, allowing users to one-click copy the install command.

See [Custom Runtimes](/guides/custom-runtimes) for registry and IAM notes.

## Local testing

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Validates adapter type (plugin must be installed in local env)
charm validate .

# Runs agent logic locally (uses local env, not necessarily your custom image)
charm run . --input "hello"

# Simulates cloud container (uses custom_image from charm.yaml)
charm run . --docker --input "hello"
```

## Related

* [Extensibility Overview](/guides/extensibility)
* [Custom Runtimes](/guides/custom-runtimes)
* [Custom Python Adapter](/adapters/custom) — built-in path, no entry points
* [Write a Custom Adapter](/oss/adapter) — contributing official adapters to the SDK repo


# Custom Runtimes
Source: https://docs.charmos.io/guides/custom-runtimes



Use a **custom runtime** when the official Charm base images are not enough — extra system packages, pre-baked models, a private fork of `charmos`, or a **third-party adapter/telemetry/memory plugin** baked into the image.

`runtime.custom_image` tells the cloud runner which container image to pull. When set, it **overrides** the default adapter→image mapping from [Base Images](/platform/base-images).

## When you need this

| Goal                                | Typical setup                                                                       |
| ----------------------------------- | ----------------------------------------------------------------------------------- |
| Extra Python/system deps only       | `type: custom` + `custom_image`                                                     |
| Third-party adapter plugin          | `type: your_plugin` + `custom_image` with plugin installed                          |
| Telemetry plugin on cloud           | Typically **no custom\_image needed** (runner auto-installs via `requirements.txt`) |
| Private or pinned `charmos` version | Extend base image and install your SDK build                                        |

You do **not** need `custom_image` for a normal `charm init` Python agent that runs on the default `runner-base` image.

## 1. Create a Dockerfile

Extend the official base image:

> \[!WARNING]
> **You must inherit from an official Charm base image.** The cloud runner injects a bootstrap script and expects `bash`, `python3`, and the core `charmos` SDK to be pre-installed. Do not build from scratch (e.g., `FROM ubuntu` or `FROM python:3.11`).

```dockerfile theme={"theme":{"light":"min-light","dark":"min-dark"}}
FROM ghcr.io/charmaios/charm-base:latest

# System dependencies (example)
RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg \
    && rm -rf /var/lib/apt/lists/*

# Third-party plugin packages (examples)
RUN uv pip install charm-adapter-ag2 charm-telemetry-datadog
```

Build and push to a registry the runner can reach:

> \[!CAUTION]
> **Always build for `linux/amd64`**. The cloud runners (Google Cloud Run / Fly.io) run on `amd64` architecture. If you are on an Apple Silicon Mac (M1/M2/M3) and build without the `--platform linux/amd64` flag, your agent will crash with an `exec format error`.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
docker build --platform linux/amd64 -t ghcr.io/your-org/my-agent-runtime:prod .
docker push ghcr.io/your-org/my-agent-runtime:prod
```

For Google Artifact Registry:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
gcloud auth configure-docker us-central1-docker.pkg.dev
docker tag ghcr.io/your-org/my-agent-runtime:prod \
  us-central1-docker.pkg.dev/YOUR_PROJECT/charm-images/my-agent-runtime:prod
docker push us-central1-docker.pkg.dev/YOUR_PROJECT/charm-images/my-agent-runtime:prod
```

## 2. Declare the image in `charm.yaml`

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
version: "0.4.2"

persona:
  name: "My Custom Agent"
  description: "Runs on a custom runtime image"
  version: "0.1.0"

interface:
  input:
    type: object
    required: [input]
    properties:
      input: { type: string }
  output:
    type: string

runtime:
  custom_image: "ghcr.io/your-org/my-agent-runtime:prod"
  adapter:
    type: custom
    entry_point: src.main:agent
  lifecycle: serverless
```

The runner bundles your **agent source code** at execute time; the **image** supplies the environment (Python deps, plugins, system libs).

## 3. Publish and run

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm validate .
charm push .
```

Users trigger runs from the Store; the runner pulls `custom_image` and executes your bundle inside that container.

## Registry access

| Registry visibility        | Requirement                                                             |
| -------------------------- | ----------------------------------------------------------------------- |
| Public (GHCR public, etc.) | Runner pulls without extra IAM                                          |
| Private                    | Grant the cloud runner service account **read** access to your registry |

> **Note on dynamic installation**: The cloud runner **does** run `uv pip install -r requirements.txt` at boot time for lightweight dependencies (like Telemetry and Memory plugins). However, if your agent requires heavy ML packages, long compile times, or system-level dependencies (like `ffmpeg`), you **must** use a `custom_image` to avoid the 300-second boot timeout.

## Community Plugins

You can discover custom runtimes built by the community in the **Charm Store (Plugins Tab)**.

If you have built a custom runtime that others might find useful (e.g., an image pre-configured with Chromium, specialized ML models, or custom data pipelines), you can submit it to the official registry:

1. Fork the [charm-community-plugin](https://github.com/CharmAIOS/charm-community-plugin) repository.
2. Edit `runtimes/registry.json` to include your image's metadata and URL.
3. Submit a Pull Request.

Once merged, your runtime will instantly appear in the Charm Store for others to use via the `custom_image` field.

## Related

* [Extensibility Overview](/guides/extensibility)
* [Custom Adapters](/guides/custom-adapters)
* [Base Images](/platform/base-images)


# Debugging
Source: https://docs.charmos.io/guides/debugging



Use this guide to troubleshoot common local and cloud execution issues.

## Start with Validation

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm validate .
```

Fix manifest and entry point issues before debugging runtime behavior.

## Run with Debug Logs

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input "Hello" --debug
```

## Common Issues

### 1. Import or Entry Point Error

Check `runtime.adapter.entry_point` and make sure the module/object exists.

### 2. Missing Environment Variable

Declare required keys in `charm.yaml` and provide local values in `.env`.

### 3. Timeout

Reduce long-running work or move persistent behavior to daemon lifecycle.

### 4. Out of Memory

Avoid loading large local models or large datasets into memory.

### 5. Works Locally but Fails in Cloud

Run Docker sandbox mode:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input "Hello" --docker
```

Then check cloud logs:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm logs --path .
```

## Getting Help

If you are blocked, open an issue or ask in Discord with validation output, logs, and reproduction steps.


# Docker Sandbox
Source: https://docs.charmos.io/guides/docker-sandbox



Docker sandbox mode runs your agent in a local container so you can catch runtime issues before publishing.

## Prerequisites

* Docker Desktop or Docker Engine.
* `charmos[runner]` installed.

## Run in Docker

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input "Hello" --docker
```

With JSON:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --json '{"message": "Hello"}' --docker
```

## Mock OAuth and Skills

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --json '{"message": "Check my calendar"}' --docker --mock-oauth
charm run . --json '{"message": "Use a tool"}' --docker --mock-skills
```

## Why Use It

Docker mode helps catch:

* missing dependencies,
* Linux/runtime differences,
* hardcoded local paths,
* missing environment variables,
* base image and adapter incompatibilities.

## Limits

Local Docker is close to the cloud runtime, but not identical. Always run a staging or Store smoke test before relying on production behavior.


# Extensibility Overview
Source: https://docs.charmos.io/guides/extensibility



Charm separates a **small stable core** from **community-owned extensions**. Not every extension works the same way — some are runtime Python plugins, some are store contributions, and some are manifest PRs.

Use this page to pick the right path before you start building.

## Extension paths at a glance

| What you want to add                              | Registration                         | Runs where      | Needs `custom_image` on cloud?     | Needs store deploy?                    |
| ------------------------------------------------- | ------------------------------------ | --------------- | ---------------------------------- | -------------------------------------- |
| [Custom adapter plugin](/guides/custom-adapters)  | `charm.adapters` entry point         | Agent container | **Yes**                            | No                                     |
| [Custom runtime only](/guides/custom-runtimes)    | `runtime.custom_image` in YAML       | Agent container | **Yes**                            | No                                     |
| [Telemetry exporter](/guides/telemetry-exporters) | `charm.telemetry` entry point        | Agent container | **Typically No** (dynamic install) | No                                     |
| [Memory backend](/guides/state-and-memory)        | `charm.memory` entry point           | Agent container | **Typically No** (dynamic install) | No                                     |
| [Input form widgets](/guides/interface)           | `interface.ui` in YAML               | Store UI        | No                                 | **Typically No** (dynamic ESM install) |
| [Output renderers](/guides/output-renderers)      | `_charm_render_type` in agent output | Store UI        | No                                 | **Typically No** (dynamic ESM install) |
| [Starter templates](/guides/community-templates)  | PR to `charm-community-plugin`       | `charm init`    | No                                 | No (manifest merge)                    |

## Two kinds of “custom” (important)

These names overlap — they are **not** the same thing:

| Term                               | Meaning                                                                                                                       |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **`runtime.adapter.type: custom`** | Built-in Charm adapter for plain Python agents (`CharmCustomAdapter` in core). Good default for `charm init` projects.        |
| **`runtime.custom_image`**         | Docker image override for the cloud runner. Required for heavy dependencies, custom system packages, or third-party adapters. |
| **Third-party adapter plugin**     | New adapter name (e.g. `ag2`, `plugin_test`) registered via `[project.entry-points."charm.adapters"]`.                        |

Scenario: you can use **`type: custom`** with **`custom_image`** (extra deps, no new adapter class).\
Scenario: you can use **`type: ag2`** with **`custom_image`** (new adapter plugin + image that installs it).

## Recommended workflow for plugin authors

1. **Start from a normal agent** — `charm init my-agent --template python`
2. **Add a pip package** with your adapter/telemetry/memory classes and `pyproject.toml` entry points
3. **Point `charm.yaml` at your plugin** — `runtime.adapter.type: your_plugin_name`
4. **Add to requirements.txt** (if lightweight like Telemetry or Memory) **OR** Build a `custom_image` (if heavy like Adapters)
5. **Set `runtime.custom_image`** in `charm.yaml` (if you built a Docker image)
6. **`charm validate`** → **`charm push`** → run on the Store

> **Note:** The cloud runner **will** execute `uv pip install -r requirements.txt` at runtime. For lightweight plugins, this is all you need. For heavy plugins (like third-party adapters), you must bake them into a `custom_image` to avoid boot timeouts.

## Built-in vs third-party

| Layer              | Built-in (no plugin package)                               | Third-party (plugin author)       |
| ------------------ | ---------------------------------------------------------- | --------------------------------- |
| Python agent logic | `charm init` + `type: custom`                              | Same                              |
| Adapter type       | `custom`, `langchain`, `openclaw`, …                       | New name via entry points         |
| Runtime image      | Official `runner-*` images                                 | Your `custom_image`               |
| Store form widgets | `text`, `textarea`, `file`, `select`, `checkbox`, `slider` | New widgets → community plugin PR |
| Rich output UI     | Built-in `_charm_render_type` values                       | New types → community plugin PR   |

## Cloud prerequisites

For any **custom image** on production:

1. Push the image to a registry the runner can pull (Artifact Registry, GHCR, etc.)
2. Grant the runner service account **read** access to that registry (if private)
3. Declare `runtime.custom_image` in `charm.yaml` — the runner selects it over default adapter images

See [Base Images](/platform/base-images) and [Custom Runtimes](/guides/custom-runtimes).

## Next steps

* [Custom Adapters](/guides/custom-adapters) — third-party framework integration
* [Custom Runtimes](/guides/custom-runtimes) — Docker image overrides
* [Telemetry Exporters](/guides/telemetry-exporters)
* [State & Memory](/guides/state-and-memory)
* [Input Forms (UI Schema)](/guides/interface)
* [Output Renderers](/guides/output-renderers)
* [Community Templates](/guides/community-templates)

For core contributors merging adapters into the official SDK, see [Write a Custom Adapter](/oss/adapter) (in-repo process).


# How to Build Input Forms (UI Schema)
Source: https://docs.charmos.io/guides/interface



The `interface` block in `charm.yaml` defines the JSON Schema for user inputs. The optional `interface.ui` block maps fields to Store form widgets.

For all manifest fields, see the [Manifest Reference](/references/manifest).

## Text inputs

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
interface:
  input:
    type: object
    required: [message]
    properties:
      message:
        type: string
        title: Message
        description: What should the agent do?
  output:
    type: string
```

## Validation rules

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
      depth:
        type: integer
        title: Search Depth
        default: 3
        minimum: 1
        maximum: 5
```

## Built-in UI widgets

Map fields to Store components with `interface.ui`:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
  ui:
    message: { "ui:widget": "textarea" }
    upload: { "ui:widget": "file" }
```

**Supported built-in widgets today:**

| Widget     | Description                                                                  |
| ---------- | ---------------------------------------------------------------------------- |
| `text`     | Single-line input (default). Shows number spinner if type is integer/number. |
| `textarea` | Multi-line input                                                             |
| `file`     | File upload — runner receives the uploaded file path in inputs               |
| `select`   | Dropdown menu based on the `enum` property in your schema                    |
| `checkbox` | Boolean toggle switch                                                        |
| `slider`   | Slider based on `minimum` and `maximum` schema properties                    |

Legacy templates may use `x-ui-widget` on individual properties; the Store still resolves those for backward compatibility.

Unknown widget names fall back to `text`.

## Access inputs in code

```python theme={"theme":{"light":"min-light","dark":"min-dark"}}
def agent(inputs):
    message = inputs.get("message")
    depth = inputs.get("depth", 3)
    return f"Processed: {message} (depth={depth})"
```

File fields are injected by the runner/store pipeline — use the key name from your schema.

## Adding custom UI Widgets (Community Plugins)

If you need a specialized input widget (like a code editor, color picker, or map selector), you can build and share it dynamically using the Charm Community Plugin registry.

1. **Build a React Component**: Your component must implement the `FieldProps` interface and be exported as the default export.
2. **Publish**: Publish your component as an ESM-compatible NPM package.
3. **Register**: Submit a Pull Request to the [charm-community-plugin](https://github.com/CharmAIOS/charm-community-plugin) repository. Add your widget to `widgets/registry.json`.

Once your PR is merged, any agent developer can use your widget instantly by specifying its `id` in their `ui:widget` config. The Charm Store will dynamically download and render your NPM package on the fly—no platform redeploys required!

## Related

* [Extensibility Overview](/guides/extensibility)
* [UI Protocol Reference](/platform/ui-protocol)
* [Output Renderers](/guides/output-renderers)


# Local Execution
Source: https://docs.charmos.io/guides/local-run



Run agents locally while you iterate on code and manifest changes.

## Simple Input

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input "Hello"
```

## Structured JSON Input

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --json '{"message": "Hello", "tone": "friendly"}'
```

Use field names that match `interface.input.properties` in `charm.yaml`.

## Test Case File

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input-file tests.json
```

Example:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
[
  {
    "name": "Greeting",
    "input": {
      "message": "Hello"
    }
  }
]
```

## Environment Variables

For local development, put non-production values in `.env`:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENAI_API_KEY=...
TAVILY_API_KEY=...
```

Never commit `.env` files containing secrets.

## Docker Mode

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input "Hello" --docker
```

Use Docker mode before publishing when dependencies or runtime behavior may differ from your host machine.


# CLI Reference
Source: https://docs.charmos.io/guides/onboarding



The Charm CLI (`charmos`) is the definitive tool to scaffold, test, validate, and deploy intelligent agents to the Charm ecosystem. Built with a focus on developer experience, it brings the entire Charm Cloud Runner capability down to your local machine.

## Installation

Install or upgrade the CLI globally via pip. We recommend using Python 3.10 or newer.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pip install -U charmos
```

> \[!TIP]
> **Zero-Latency Update Checker**
> The CLI automatically checks PyPI for updates in the background. If a new version is available, it will display a seamless non-blocking notification in your terminal.

***

## Global Options

Every command in the Charm CLI supports standard global modifiers for debugging and system info.

| Option      | Shorthand | Description                                                                                                                                                                                                                       |
| :---------- | :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--help`    |           | Display detailed, interactive documentation and parameter lists for any command (e.g., `charm run --help`).                                                                                                                       |
| `--debug`   |           | Elevates the internal logging context. Prints raw HTTP server payloads, intercepts internal exceptions to print full stack traces, and provides verbose outputs. Crucial for debugging `Connection Error` or deployment failures. |
| `--version` | `-v`      | Prints the currently installed version of `charmos` and exits.                                                                                                                                                                    |

***

## Authentication (`charm auth`)

Manages your connection to the Charm Developer portal. You must be authenticated to push agents to the platform or read secure execution logs.

### `charm auth login`

Opens a secure local OAuth server and redirects your browser to authenticate your CLI session with your Charm account.

### `charm auth whoami`

Prints the email address and token status of the currently authenticated developer.

### `charm auth manual`

If you are operating in a headless environment (e.g., SSH, CI/CD pipeline) where a browser cannot be opened, use this command to paste a Personal Access Token directly.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm auth manual --token <YOUR_TOKEN>
```

### `charm auth logout`

Purges the local credential configuration (`~/.charm/config.toml`).

***

## Project Initialization (`charm init`)

Scaffolds a new Charm Agent project. It auto-generates the required `charm.yaml` manifest and injects the necessary boilerplate code based on the chosen runtime adapter.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Initialize interactive wizard
charm init --interactive

# Initialize a new code-based agent instantly
charm init my-new-agent --template python
```

| Option          | Default  | Description                                                                                                                                                      |
| :-------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[name]`        | `.`      | The directory path to scaffold the project into. Use `.` for the current directory.                                                                              |
| `--template`    | `python` | The starting template. Valid options: `python`, `openclaw`, `research-agent`, `code-review-agent`, `customer-support-agent`, `data-pipeline-agent`, `slack-bot`. |
| `--create`      |          | Generate only a single file from a template instead of scaffolding a full folder (e.g. `--create charm.yaml`).                                                   |
| `--interactive` | `false`  | Launch the interactive TUI prompt to visually guide you through project setup.                                                                                   |

***

## Local Development (`charm run`)

The most powerful command in your local workflow. `charm run` allows you to execute your agent locally using identical boundaries to the Cloud Runner simulator.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Run in interactive CLI chat mode
charm run

# Run a headless JSON payload test
charm run --json '{"query": "Summarize the latest AI trends"}'

# Simulate the exact cloud container environment locally
charm run --docker --mock-oauth
```

| Option          | Shorthand | Description                                                                                                                                                                             |
| :-------------- | :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[path]`        | `.`       | Path to the Charm project root.                                                                                                                                                         |
| `--input`       | `-i`      | Send a simple string text input to the agent.                                                                                                                                           |
| `--json`        |           | Send a complex, deeply-nested raw JSON payload.                                                                                                                                         |
| `--input-file`  | `-f`      | Provide a path to a JSON file containing a list of structured test cases to bulk-run logic tests.                                                                                       |
| `--docker`      |           | **Advanced:** Boots a real-time local Docker container strictly mimicking the production `ucmind/runner-base` environment, mounting your code, and outputting server-sent events (SSE). |
| `--mock-oauth`  |           | Injects dummy OAuth tokens (`GOOGLE_OAUTH_TOKEN`, etc.) into your environment.                                                                                                          |
| `--mock-skills` |           | Forces the executor to bypass actual MCP skill connections for isolated unit testing.                                                                                                   |

***

## Validation (`charm validate`)

Performs a rigorous local static analysis of your project. This command executes prior to `charm push` but can be run manually to lint your setup.

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

**Checks Performed:**

1. **Schema Validation:** Ensures `charm.yaml` strictly conforms to the UAC specification.
2. **Path Portability:** Scans internal Python files for hardcoded absolute paths (e.g., `/Users/dev/...`) which will instantly crash when deployed to the cloud runner.
3. **Entry Point Verification:** For Python and Custom adapters, it imports your `main.py` locally and maps the signature to ensure your `agent(inputs, callbacks)` conforms exactly to the required parameters.

***

## Deployment (`charm push`)

Bundles your source code, computes the `.charmignore` exclusions, and securely deploys your agent globally onto the Charm Store.

When your deployment is completed, the CLI will trigger an auto-restart for existing installations and automatically copy your dedicated Store Distribution URL directly into your operating system's clipboard.

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

| Option      | Description                                                                                                                                               |
| :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[path]`    | Path to the Charm project root (defaults to `.`).                                                                                                         |
| `--dry-run` | Executes the entire build process to display exactly which files will be packaged and the resulting bundle size in Megabytes, but halts before uploading. |

> \[!WARNING]
> Charm enforces a strict **maximum bundle size of 50.0 MB**. If you are bundling heavy machine-learning checkpoint files or non-essential directories (like `node_modules` or `.venv`), use `.charmignore` to exclude them.

***

## Telemetry (`charm logs`)

Securely tails the cloud execution logs of your specific agent without forcing context-switches to the web-based Studio dashboard.

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

| Option    | Shorthand | Description                                                                   |
| :-------- | :-------- | :---------------------------------------------------------------------------- |
| `--limit` | `-l`      | The number of recent historical log events to fetch (max 500). Default is 50. |

> \[!NOTE]
> **Authentication Check**
> The `charm logs` command requires the invoking machine to possess a valid authentication token belonging to the creator or an authorized owner of the agent. Unauthorized requests will result in a `403 Access Denied` response.


# How to Render Rich UI
Source: https://docs.charmos.io/guides/output-renderers



The Charm Store **Universal Renderer** maps structured agent output to React components — bar/line/pie charts, data grids, metric cards — without you writing frontend code.

For full payload schemas, see the [UI Protocol Reference](/platform/ui-protocol).

## Built-in render types (no store changes)

Return a JSON object with `_charm_render_type` set to one of:

| Type          | Use case                |
| ------------- | ----------------------- |
| `bar_chart`   | Categorical comparisons |
| `line_chart`  | Trends over time        |
| `pie_chart`   | Part-to-whole           |
| `data_grid`   | Tabular results         |
| `metric_card` | KPI-style metrics       |

These work for any published agent — **no store deploy required**.

## Custom Python agents

```python theme={"theme":{"light":"min-light","dark":"min-dark"}}
def agent(inputs):
    return {
        "_charm_render_type": "bar_chart",
        "title": "Quarterly Sales",
        "data": [
            {"name": "Q1", "value": 15000},
            {"name": "Q2", "value": 22000},
        ],
    }
```

With the built-in **`custom`** adapter, return the dict directly from your entry point. With a third-party adapter, return `{"status": "success", "output": {...}}` or ensure your adapter forwards structured output.

## Framework adapters (LangChain, CrewAI, OpenClaw)

Configure the model to emit JSON matching the schema. Example for OpenClaw:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  adapter:
    type: openclaw
  config:
    system_prompt: |
      Return your final answer as JSON only:
      {
        "_charm_render_type": "metric_card",
        "title": "Analysis Results",
        "metrics": [
          {"label": "Confidence", "value": "98.5", "unit": "%"}
        ]
      }
```

Adapters parse JSON final messages and forward structure to the Store.

## Metric card example

```python theme={"theme":{"light":"min-light","dark":"min-dark"}}
return {
    "_charm_render_type": "metric_card",
    "title": "Performance",
    "metrics": [
        {"label": "Active Users", "value": 1204, "change": 12, "unit": "users"},
        {"label": "Error Rate", "value": "0.3", "unit": "%"},
    ],
}
```

## Markdown and HTML fallback

Return a plain string for standard Markdown rendering. HTML and SVG snippets are sanitized (scripts stripped):

```python theme={"theme":{"light":"min-light","dark":"min-dark"}}
def agent(inputs):
    return "### Status\n\nAll systems operational."
```

## Streaming text + rich final

Use `CharmEmitter` for intermediate markdown, then return structured JSON as the final result:

```python theme={"theme":{"light":"min-light","dark":"min-dark"}}
from charm.core.io import CharmEmitter

def agent(inputs):
    CharmEmitter.emit_delta("Analyzing dataset...\n")
    return {
        "_charm_render_type": "metric_card",
        "title": "Results",
        "metrics": [{"label": "Score", "value": 98, "unit": "%"}],
    }
```

## Sharing Custom Output Renderers with the Community

You can now build and share your own custom UI components (like a specialized stock chart, a unique data grid, or a 3D molecule viewer) without waiting for a store deployment! Charm supports dynamic ESM module loading for community output renderers.

To share a custom renderer:

1. **Build a React Component**: Write a React component that takes a `payload` prop and export it as your default export.
2. **Publish to NPM**: Package your component and publish it to NPM. Ensure your package is ESM compatible.
3. **Register in the Community Plugin**: Submit a Pull Request to the [charm-community-plugin](https://github.com/CharmAIOS/charm-community-plugin) repository. Add your renderer's details (including the `id` which corresponds to your `_charm_render_type`, and the `npm_package` name) into `renderers/registry.json`.

Once your PR is merged, the Charm Store will dynamically fetch your component from `esm.sh` directly in the browser whenever an agent emits your `_charm_render_type`!

You can also browse all community renderers on the **Plugins** page in the Charm Store.

## Related

* [UI Protocol Reference](/platform/ui-protocol)
* [Extensibility Overview](/guides/extensibility)
* [Input Forms (UI Schema)](/guides/interface)


# Developer Guide
Source: https://docs.charmos.io/guides/overview



This guide covers the normal workflow for building Charm agents.

## Developer Workflow

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
Initialize -> Configure -> Develop -> Validate -> Run -> Publish -> Observe
```

### 1. Initialize

Start from a template:

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

See [Build Your First Agent](/quickstart/first-app).

### 2. Configure

Edit `charm.yaml` to define identity, inputs, runtime, pricing, auth, and policies.

See [Configuration](/guides/manifest).

### 3. Develop

Write agent logic in the entry point declared in the manifest.

See [Local Execution](/guides/local-run).

### 4. Validate

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm validate .
```

See [Validation](/guides/validate).

### 5. Run

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input "Hello"
```

Use Docker mode to simulate the cloud runtime.

### 6. Publish

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm push .
```

See [Publishing](/guides/push).

### 7. Observe

Use Store, Studio, and CLI logs to inspect production behavior.

## Extending Charm

For adapters, runtimes, telemetry, memory, UI, templates, and renderers, start with [Extensibility Overview](/guides/extensibility).


# Publishing
Source: https://docs.charmos.io/guides/push



Publishing uploads a versioned agent bundle to Charm Store.

## Authenticate

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm auth login
```

## Validate

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm validate .
```

## Dry Run

Preview without publishing:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm push . --dry-run
```

## Publish

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm push .
```

## What Gets Bundled

Charm bundles the project source, manifest, and dependency files needed to run your agent.

Use `.charmignore` to exclude:

* `.env`,
* virtual environments,
* large local datasets,
* build output,
* cache directories,
* private files.

## Versioning

Each published version should use a unique `persona.version` in `charm.yaml`.

## After Publishing

* Open the Store listing.
* Run a smoke test.
* Confirm required OAuth or API keys are available.
* Check logs if the run fails.


# Custom Memory Storage
Source: https://docs.charmos.io/guides/state-and-memory



By default, Charm uses **local file-backed memory** (`runtime.memory.provider: local`). On the cloud runner, workspace files are persisted under a managed workspace path (backed by cloud storage for serverless/daemon workloads).

For Redis, PostgreSQL, or other backends, install a **memory plugin** or use the built-in `supabase` provider where configured.

## Configuring a provider

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  adapter:
    type: langchain
    entry_point: src.main:agent
  memory:
    provider: redis
    config:
      url: "redis://localhost:6379/0"
```

The cloud runner sets `CHARM_MEMORY_PROVIDER` from this block so runtime code can resolve the active backend.

Built-in provider names today:

| Provider          | Source                                    |
| ----------------- | ----------------------------------------- |
| `local` (default) | Core — file-backed                        |
| `supabase`        | Core — when Supabase memory is configured |
| Custom names      | `charm.memory` entry points               |

### Underlying Checkpoint Mechanism

When using an external provider like `supabase`, Charm leverages thread identifiers (`thread_id`) and checkpoint namespaces to continuously sync state to the database. Upon waking up or migrating across devices, the runtime automatically queries the most recent state checkpoint. This architecture provides zero-downtime perception and seamless cross-device continuity without additional developer overhead.

## Creating a memory plugin

### 1. Implement `BaseMemoryStore`

```python theme={"theme":{"light":"min-light","dark":"min-dark"}}
from typing import Any, Dict, List
import json
import redis
from charm.core.storage import BaseMemoryStore

class RedisMemory(BaseMemoryStore):
    def __init__(self, config: Dict[str, Any]):
        super().__init__(config)
        self.client = redis.Redis.from_url(
            self.config.get("url", "redis://localhost:6379/0")
        )

    def load_messages(self, thread_id: str) -> List[Dict[str, Any]]:
        raw = self.client.get(f"charm:memory:{thread_id}")
        return json.loads(raw) if raw else []

    def save_messages(self, thread_id: str, messages: List[Dict[str, Any]]) -> None:
        self.client.set(f"charm:memory:{thread_id}", json.dumps(messages))

    def get_langgraph_checkpointer(self) -> Any:
        return None
```

### 2. Register via entry points

```toml theme={"theme":{"light":"min-light","dark":"min-dark"}}
[project.entry-points."charm.memory"]
redis = "charm_memory_redis.store:RedisMemory"
```

### 3. Use in `charm.yaml`

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  memory:
    provider: redis
    config:
      url: "${REDIS_URL}"
```

## Using memory from agent code

```python theme={"theme":{"light":"min-light","dark":"min-dark"}}
import os
from charm.core.storage import StorageManager

def agent(inputs):
    thread_id = inputs.get("__charm_thread_id__", "default")
    provider = os.getenv("CHARM_MEMORY_PROVIDER", "local")

    store = StorageManager.get_provider(provider, {})
    history = store.load_messages(thread_id)

    history.append({"role": "user", "content": str(inputs)})
    store.save_messages(thread_id, history)

    return {"status": "success", "output": f"Turns: {len(history)}"}
```

`StorageManager` caches the active provider for the process. Pass the same `config` dict shape as `runtime.memory.config` when constructing plugins that need connection settings.

## Cloud deployment

Unlike heavy adapters, **Memory plugins are typically lightweight** (e.g. `redis`, `pymongo`). This means the Charm Cloud Runner can install them dynamically at boot time without timing out.

**You do NOT need a `custom_image` to use most Memory Providers!**

1. Add the package to your agent's `requirements.txt`:

```txt theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm-memory-redis
```

2. Enable it in `charm.yaml`:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  memory:
    provider: redis
    config:
      url: "${REDIS_URL}"
```

3. Ensure **`policies.allow_internet_access`** (or network policy) allows reaching your database.
4. Provide connection secrets via environment variables — not in committed `charm.yaml`.

If your memory plugin requires heavy native packages (e.g. `psycopg2-binary` takes longer), you should bake it into a `runtime.custom_image` instead.

If the configured plugin is not found at runtime, Charm **falls back to local file memory** and logs a warning.

## Share with the Community

Once your memory provider is working and published to PyPI, you can list it in the official **Charm Store**!

Submit a Pull Request to the [charm-community-plugin](https://github.com/CharmAIOS/charm-community-plugin) repository to add your package to `memory/registry.json`. Your integration will immediately appear on the [Plugins](/plugins) page for other developers to discover.

## Related

* [Extensibility Overview](/guides/extensibility)
* [Custom Runtimes](/guides/custom-runtimes)
* [Threads](/platform/threads)


# Telemetry Exporters
Source: https://docs.charmos.io/guides/telemetry-exporters



Charm dispatches execution lifecycle events (run start/end, tool calls, LLM tokens, errors) to a **`TelemetryManager`** inside the agent container. By default, events stream to stdout for the cloud runner to forward as SSE. You can add **custom exporters** to forward the same events to Datadog, LangSmith, Sentry, etc.

> Telemetry plugins run **inside the agent container**, not in the store or cloud-runner API process.

> \[!TIP]
> **Want to build a new exporter?** Use the [charm-telemetry-template](https://github.com/CharmAIOS/charm-telemetry-template) to bootstrap your project. It includes the correct entry points and `BaseTelemetryExporter` setup.

## 1. Implement `BaseTelemetryExporter`

Subclass `charm.core.telemetry.BaseTelemetryExporter`. **All abstract hook methods must be implemented** (use `pass` for hooks you do not need):

```python theme={"theme":{"light":"min-light","dark":"min-dark"}}
import os
from typing import Any, Dict
from charm.core.telemetry import BaseTelemetryExporter

class DataDogExporter(BaseTelemetryExporter):
    def __init__(self) -> None:
        self.api_key = os.getenv("DATADOG_API_KEY", "")

    def on_run_start(self, run_id: str, inputs: Dict[str, Any]) -> None:
        pass

    def on_run_end(self, run_id: str, outputs: Dict[str, Any]) -> None:
        pass

    def on_error(self, run_id: str, error: Exception) -> None:
        pass

    def on_tool_start(self, tool_name: str, input_str: str) -> None:
        pass

    def on_tool_end(self, tool_name: str, output: str) -> None:
        pass

    def on_tool_error(self, tool_name: str, error: BaseException) -> None:
        pass

    def on_llm_new_token(self, token: str) -> None:
        pass

    def on_agent_action(self, tool: str, tool_input: str) -> None:
        pass
```

## 2. Register via entry points

```toml theme={"theme":{"light":"min-light","dark":"min-dark"}}
[project.entry-points."charm.telemetry"]
datadog = "charm_telemetry_datadog.exporter:DataDogExporter"
```

## 3. Opt in from `charm.yaml`

Exporters are **opt-in** — list the entry point **names** you want loaded:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  adapter:
    type: custom
    entry_point: src.main:agent
  telemetry:
    - datadog
```

The default `CharmEmitterExporter` always runs; listed plugins are added to the dispatch list.

## 4. Zero-Config Cloud Deployment

Unlike heavy adapters, **Telemetry plugins are typically lightweight** (e.g. `requests`, API clients). This means the Charm Cloud Runner can install them dynamically at boot time without timing out.

**You do NOT need a `custom_image` to use a Telemetry Exporter!**

1. Add the package to your agent's `requirements.txt`:

```txt theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm-telemetry-datadog
```

2. Enable it in `charm.yaml`:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  telemetry:
    - datadog
```

3. **Inject secrets via environment variables** (e.g. `DATADOG_API_KEY`) through the Store agent settings or runner env resolution — never hard-code keys in `charm.yaml`.

When you deploy, the runner will execute `uv pip install -r requirements.txt` in a fraction of a second, and your agent will start sending telemetry immediately.

## 5. Share with the Community

Once your telemetry exporter is working and published to PyPI, you can list it in the official **Charm Store**!

Submit a Pull Request to the [charm-community-plugin](https://github.com/CharmAIOS/charm-community-plugin) repository to add your package to `telemetry/registry.json`. Your integration will immediately appear on the [Plugins](/plugins) page for other developers to discover.

## Related

* [Extensibility Overview](/guides/extensibility)
* [Observability](/platform/observability)
* [Custom Runtimes](/guides/custom-runtimes)


# Validation
Source: https://docs.charmos.io/guides/validate



Validation checks whether your project is ready to run and publish.

## Run Validation

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm validate .
```

## What Validation Covers

* `charm.yaml` exists.
* Manifest schema is valid.
* Adapter type is supported.
* Entry point is importable or executable.
* Auth providers are recognized.
* Policies and pricing are well-formed.
* Paths are portable.
* Interface schema is valid.

## Common Fixes

* Put `charm.yaml` at the project root.
* Match `runtime.adapter.entry_point` to your actual module/object.
* Use relative paths.
* Declare required environment variables.
* Update `persona.version` before publishing a new version.

## Before Publishing

Always run:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm validate .
charm run . --input "Hello"
```


# Version Control & Upgrades
Source: https://docs.charmos.io/guides/version-control



Charm versions are driven by the agent manifest and the published bundle.

## Agent Version

Update `persona.version` in `charm.yaml` when publishing a new agent version:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
persona:
  version: "0.2.0"
```

Use semantic versioning where possible:

* patch: bug fixes,
* minor: new compatible features,
* major: breaking changes.

## Agentic Merge Upgrade Process

Charm uses an intelligent "Agentic Merge" approach for OTA updates to preserve your local workspace modifications while applying new bundle changes.

For detailed information on how this process works under the hood, including execution logic and fallback mechanisms, see the [Agentic Merge documentation](../platform/agentic-merge).

## Upgrade Safety

Before publishing:

* run validation,
* test locally,
* test Docker mode for runtime changes,
* document breaking changes,
* keep previous version available for rollback.

## Daemon Agents

Daemon agents may need restart or upgrade handling because they run persistently. Test daemon upgrades in preview before production.

## Best Practices

* Publish small changes.
* Avoid changing input schemas without migration notes.
* Keep changelog entries user-facing.
* Use Git tags for important releases.


# Charm
Source: https://docs.charmos.io/index



<img alt="Charm Banner" />

<div>
  Bring your AI agents to everyday users
</div>

<CardGroup>
  <Card title="Get Started" icon="rocket-launch" href="quickstart/install">
    Install the Charm CLI and publish your first AI agent in minutes.
  </Card>

  <Card title="Onboarding" icon="terminal" href="guides/onboarding">
    Walk through the onboarding guide.
  </Card>

  <Card title="Templates" icon="book-open" href="templates/overview">
    Start from a prebuilt template.
  </Card>
</CardGroup>

## What is Charm?

**Charm** is a unified application layer that provides a standardized architecture for distributing, running, and scaling AI agents across heterogeneous ecosystems — turning them into real, commercial-ready applications with a single manifest file and a few CLI commands.

### Why Charm?

* **Ecosystem Agnostic**: Bring your own framework such as CrewAI, LangChain, LangGraph, OpenClaw, or plain Python functions, Charm wraps them all with the same runtime contract.
* **No Infrastructure**: The Cloud Runner handles isolated container execution, secrets injection, and scaling. You write agent logic, not deployment pipelines.
* **Server-Driven UI**: Return Markdown or structured JSON from your agent and the Store renders timelines, comparison tables, viral cards, and article layouts automatically - no frontend code needed.
* **Built-In Monetization**: Set pricing in `charm.yaml` and Charm handles checkout, subscriptions, balance checks, and payouts.
* **Open Source**: Charm Core, CLI, and runtime adapters are fully open source. Community contributions drive every part of the ecosystem.

## Who needs Charm?

* **AI Developers** who have a working agent in CrewAI, LangChain, OpenClaw, or custom Python and want to ship it as a product without building infrastructure.
* **AI Builders** who want to monetize agents through the Charm Store with built-in billing, OAuth, and a hosted runtime.
* **Everyday users** who want agents as apps, not infrastructure. Zero setup, no API keys, and no need to understand how they work. Just natural interaction with the agents you need.

## What do you need?

* **Python 3.10+** and `pip` or [`uv`](https://github.com/astral-sh/uv) for package management.
* **Docker Desktop** (optional) if you want to test agents locally in an isolated container sandbox that mirrors the cloud runtime.
* **A Charm account** for publishing to the Store — sign up at [store](\{store_url}).

## How it works

<Frame>
  <img alt="How it works" />
</Frame>

***

## Start Here

<Tabs>
  <Tab title="OS">
    <CardGroup>
      <Card title="Configuration" icon="gear" href="guides/manifest">
        Define everything about your agent in a single charm.yaml manifest.
      </Card>

      <Card title="Run & Test" icon="terminal" href="guides/local-run">
        Execute your agent locally or simulate the cloud environment in Docker.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Platform">
    <CardGroup>
      <Card title="Charm Store" icon="store" href="platform/store">
        Publish agents as hosted web apps.
      </Card>

      <Card title="Charm Studio" icon="chart-line" href="platform/studio">
        Monitor executions, revenue, and more from your agent center.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

## Highlight Features

<CardGroup>
  <Card title="Secrets Management" icon="key" href="platform/keys">
    Fully managed secrets for your agents.
  </Card>

  <Card title="OAuth" icon="shield-halved" href="platform/oauth">
    Integrate with Google, GitHub, and more.
  </Card>

  <Card title="Ambient Desktop Companion" icon="display" href="platform/ambient-desktop-companion">
    Run agents in your desktop as a native companion.
  </Card>

  <Card title="Payments" icon="money-bill-1" href="platform/app">
    Set flexible pricing model in charm.yaml.
  </Card>
</CardGroup>

## Community & Resources

<CardGroup>
  <Card title="Charm Store" icon="house" href="{store_url}">
    Browse and run published agents on the live storefront.
  </Card>

  <Card title="Contact Us" icon="envelope" href="https://charmos.io/contact">
    Reach the core team for partnership, support, or enterprise inquiries.
  </Card>

  <Card title="Discord" icon="discord" href="https://discord.gg/gdakynHUEb">
    Get help, share agents, and discuss ideas with other builders.
  </Card>

  <Card title="Blog" icon="blog" href="https://charmos.io/blog">
    Follow platform updates, feature announcements, and builder spotlights.
  </Card>
</CardGroup>


# Write a Custom Adapter
Source: https://docs.charmos.io/oss/adapter



Adapters connect agent frameworks to Charm's runner protocol (`invoke`, streaming, tools, errors).

> **Building a third-party plugin without forking Charm?** See [Custom Adapters](/guides/custom-adapters) (entry points + custom image). This page is for **core contributors** adding official adapters to the `charmos` package.

## When to add an adapter to core

Add to the SDK when the framework is widely used and should ship with official runner images and first-class docs. Niche or experimental integrations should stay as **entry-point plugins** in separate packages.

## Community plugin path (preferred for most authors)

1. Publish a pip package with `[project.entry-points."charm.adapters"]`
2. Ship a Docker image with that package installed
3. Set `runtime.custom_image` + `runtime.adapter.type` in `charm.yaml`

No changes to the Charm GitHub repo required.

## Core contributor path

1. Study the closest adapter in `src/charm/adapters/`
2. Implement `BaseAdapter`
3. Register in `pyproject.toml` under `[project.entry-points."charm.adapters"]`
4. Add/update Dockerfile if a dedicated runner image is needed
5. Add tests and adapter docs under `docs/adapters/`
6. Update `charm-community-plugin/templates/registry.json` if a new starter template is warranted

## Testing

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm validate path/to/example
charm run path/to/example --input "Hello"
charm run path/to/example --docker --input "Hello"
```

## Related

* [Extensibility Overview](/guides/extensibility)
* [Custom Adapters](/guides/custom-adapters)
* [Adapter overview](/adapters/overview)


# Create a Base Image
Source: https://docs.charmos.io/oss/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.


# Code of Conduct
Source: https://docs.charmos.io/oss/code-of-conduct



Charm is an open-source project for people building AI agents, tools, documentation, runtime infrastructure, and developer workflows. We want contributors to feel safe asking questions, proposing changes, reviewing code, and disagreeing constructively.

This page explains the standards expected in Charm community spaces, including GitHub repositories, pull requests, issues, discussions, Discord, docs contributions, release planning, and other project-managed channels.

## Our Pledge

We pledge to make participation in Charm respectful, inclusive, and productive for contributors of all backgrounds and experience levels.

Maintainers and contributors are expected to act with empathy, patience, professionalism, and care for the broader community.

## Expected Behavior

* Be respectful and constructive.
* Keep feedback focused on the work, not the person.
* Assume good intent, but be willing to adjust when your words or actions cause harm.
* Ask clarifying questions before escalating disagreement.
* Credit others for ideas, bug reports, designs, and contributions.
* Help newcomers find the right docs, issues, discussions, or maintainers.
* Respect project scope, maintainer time, and review boundaries.
* Disclose conflicts of interest when relevant to a technical or governance decision.

## Unacceptable Behavior

* Harassment, threats, intimidation, or personal attacks.
* Discriminatory language or behavior.
* Sexualized language, imagery, or attention.
* Publishing private information without clear permission.
* Repeatedly derailing technical discussions.
* Insulting, dismissive, or bad-faith review behavior.
* Spam, trolling, or deliberately disruptive activity.
* Pressure to bypass security, review, release, or safety processes.
* Any behavior that makes the project unsafe for contributors.

## Reporting a Concern

If you experience or witness behavior that violates this code of conduct, contact the maintainers privately:

* Email: [team@charmos.io](mailto:team@charmos.io)
* Discord: privately contact a Charm maintainer if email is unavailable.

Please include:

* What happened.
* Where it happened.
* Who was involved.
* Any relevant links, screenshots, or timestamps.
* Whether there is an immediate safety concern.

Do not post sensitive reports publicly in GitHub issues or Discord channels.

## Enforcement

Maintainers may take action to protect the community, including:

* clarifying expectations,
* editing or removing comments,
* closing or locking issues and pull requests,
* requesting a behavior change,
* issuing a warning,
* temporarily restricting participation,
* permanently banning a participant from project spaces.

Enforcement decisions should be proportionate to the behavior, the impact on others, and any pattern of repeated conduct.

## Appeals

If you believe an enforcement action was made in error, email [team@charmos.io](mailto:team@charmos.io) with context. A maintainer who was not directly involved in the original decision should review the appeal when possible.

## Security Reports

Security vulnerabilities should be reported through the private process in [`SECURITY.md`](https://github.com/CharmAIOS/Charm/blob/main/SECURITY.md), not through public issues or public community channels.


# Code Style & Standards
Source: https://docs.charmos.io/oss/code-style



This page documents the expected code quality standards for Charm contributions.

## General Principles

* Keep changes focused.
* Prefer readable code over clever code.
* Match nearby patterns.
* Add tests for behavior changes.
* Avoid unrelated refactors in feature or bugfix PRs.

## Python

Use this repository's configured tooling from `pyproject.toml`.

Expected checks may include:

* linting,
* formatting,
* type checking,
* tests.

## Tests

Use focused tests for the changed behavior. Critical paths such as auth, billing, runner execution, package publishing, and migrations should have stronger coverage.

## Imports and Dependencies

* Avoid adding dependencies unless necessary.
* Prefer standard library or existing project dependencies.
* Keep runtime dependencies separate from development-only dependencies.

## Docs and Examples

If a public API, CLI command, manifest field, or template behavior changes, update docs in the same PR or leave a clear follow-up issue.


# Contributing Guide
Source: https://docs.charmos.io/oss/contributing



Thanks for helping improve Charm. Contributions can include code, templates, docs, tests, bug reports, and product feedback.

## How to Contribute

1. Fork the repository.
2. Create a branch for your change.
3. Make the smallest focused change that solves the problem.
4. Run relevant checks.
5. Open a pull request.

## Pull Request Expectations

Every PR should include:

* what changed,
* why it is needed,
* how reviewers can validate it,
* screenshots or logs for UI/runtime changes,
* docs updates when behavior changes,
* migration or deploy notes when relevant.

## Good First Contributions

* Fix docs gaps.
* Improve examples.
* Add tests around existing behavior.
* Clarify error messages.
* Improve templates.

## Community Standards

Before contributing, please review the [Code of Conduct](/oss/code-of-conduct). It explains expected behavior, unacceptable behavior, and how to report a concern privately.

## Local Setup

See [Development Environment](/oss/dev-setup).


# Development Environment
Source: https://docs.charmos.io/oss/dev-setup



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.


# Docs Versioning
Source: https://docs.charmos.io/oss/docs-versioning



This page defines the planned versioning model for Charm documentation.

Docs versioning keeps users from reading instructions that do not match their installed SDK or deployed platform version.

## Planned Model

* `latest`: follows mainline docs.
* `vX.Y`: pinned docs for stable package releases.
* Older versions: retained according to the support policy.

## Required Links

* SDK package version.
* GitHub Release.
* Changelog entry.
* Upgrade notes.

## Source of Truth

Until a formal version switcher is implemented, `latest` docs should describe the current supported public behavior. Release notes should call out version-specific differences.

## Version Mapping

Each stable docs version should map to:

* a Git tag,
* a package version,
* a changelog entry,
* upgrade notes when needed.

## Retention Policy

Initial recommendation:

* Keep `latest`.
* Keep the most recent stable minor release.
* Keep one previous stable release line when breaking changes exist.

Older versions can be archived once they are no longer supported.

## Deprecation Notices

When behavior changes, old pages should link to the new recommended path and clearly mark deprecated commands, fields, or workflows.


# Improve Documentation
Source: https://docs.charmos.io/oss/documentation



Charm docs are built from MDX files under `docs/`.

## Run Docs Locally

From the docs directory:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
npx mintlify dev
```

Then open the local URL printed in the terminal.

On Windows, enable Developer Mode or run the terminal as Administrator if Mintlify fails to create symlinks.

## File Structure

* `docs/docs.json`: Mintlify configuration and navigation.
* `docs/docs.json` `variables`: substituted in MDX content (for example `{store_url}` in pages).
* Navbar `href` values in `docs.json` must be literal URLs; Mintlify validates them as URIs and does not substitute `{variable}` placeholders there. Keep them in sync with `variables.store_url` and `variables.discord_url`.
* `docs/quickstart`: onboarding.
* `docs/templates`: starter templates.
* `docs/guides`: developer workflow guides.
* `docs/cli`: command reference.
* `docs/platform`: platform features.
* `docs/oss`: contributor and open-source pages.

## Add a Page

1. Create a `.mdx` file.
2. Add frontmatter with `title` and `description`.
3. Add the page path to `docs/docs.json`.
4. Run Mintlify locally.
5. Open a PR.

## Writing Style

* Start with the user goal.
* Use short sections.
* Include copy-pasteable commands.
* Link related pages.
* Avoid hidden assumptions.


# Governance
Source: https://docs.charmos.io/oss/governance



This page will document how Charm makes open-source project decisions.

Charm's governance model should make it clear who reviews changes, how releases are approved, and how contributors can participate.

## Planned Sections

* Maintainers.
* Workstream owners.
* Review expectations.
* Release approval.
* Security escalation.
* Community standards.

## Maintainers

Maintainers are responsible for:

* reviewing pull requests,
* protecting project quality,
* triaging issues,
* approving releases,
* enforcing community standards,
* coordinating security fixes.

The initial maintainer list should be published before the first formal open-source release.

## Workstream Ownership

Charm should assign owners for:

* SDK and package publishing,
* runner and infrastructure,
* Store and web app,
* docs and templates,
* database migrations,
* security and disclosure.

## Decision Making

Small changes can be approved through normal pull request review. Larger changes should include:

* a design note or issue,
* affected repositories,
* migration/deploy impact,
* compatibility risks,
* rollout plan.

## Release Approval

Production-impacting releases should have approval from the release owner and the relevant workstream owner.

## Community Standards

All participation is covered by the [Code of Conduct](/oss/code-of-conduct).


# Community & Open Source
Source: https://docs.charmos.io/oss/overview



Charm is open source so agent builders can inspect, extend, and improve the core developer experience around packaging, running, publishing, and monetizing AI agents.

## What You Can Contribute

Contributions can include:

* SDK and CLI improvements.
* Agent templates.
* Runtime adapters.
* Documentation.
* Bug fixes.
* Test coverage.
* Platform integration ideas.
* Developer experience improvements.

## Start Here

* Read the [Contributing Guide](/oss/contributing).
* Set up your [Development Environment](/oss/dev-setup).
* Review the [Code of Conduct](/oss/code-of-conduct).
* Browse open issues on GitHub.

## Community Channels

* GitHub: code, issues, pull requests, release history.
* Discord: discussion, support, early feedback.
* Docs: public guides and contributor reference.

## License

Charm is licensed under the GNU AGPL v3.0. Review the repository license before redistributing or embedding Charm in another product.

## Project Direction

The open-source roadmap focuses on:

* reliable SDK releases,
* clear templates,
* predictable runtime behavior,
* contributor-friendly docs,
* secure publishing and deployment workflows.


# Release Process
Source: https://docs.charmos.io/oss/release-process



Charm releases should be repeatable, auditable, and driven by CI instead of local maintainer machines.
The Python SDK package is published as `charmos` on PyPI.

## Release Flow

1. Merge approved changes.
2. Confirm required checks pass on `main`.
3. Review the generated draft GitHub Release.
4. Bump the package version in `pyproject.toml`.
5. Publish to TestPyPI for a package dry run.
6. Create and push a `vX.Y.Z` tag.
7. Let GitHub Actions publish to PyPI from the tag.
8. Publish the GitHub Release and update docs links if needed.

## Required Checks

* `lint`
* `typecheck`
* `tests`
* `package-build`
* `docs-validation`
* `build-validation`
* `release-label`
* TestPyPI publish for release candidates.

## Package Publishing

Official package releases must be published from GitHub Actions.
Do not upload wheels or source distributions from a local maintainer machine for official releases.

Preferred model:

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
git tag vX.Y.Z -> GitHub Actions -> build -> verify -> publish to PyPI
```

The publish workflow validates that the Git tag matches the version in `pyproject.toml`.
For example, `version = "0.4.22"` must be released from tag `v0.4.22`.

## Trusted Publishing Setup

Charm uses PyPI Trusted Publishing through GitHub OIDC.
This avoids storing long-lived PyPI API tokens in GitHub secrets.

Configure these trusted publishers in PyPI:

* PyPI project: `charmos`
* Owner: `CharmAIOS`
* Repository: `Charm`
* Workflow: `publish-pypi.yml`
* Environment: `pypi`

Configure these trusted publishers in TestPyPI:

* TestPyPI project: `charmos`
* Owner: `CharmAIOS`
* Repository: `Charm`
* Workflow: `publish-testpypi.yml`
* Environment: `testpypi`

In GitHub repository settings, create two environments:

* `testpypi` for package dry runs.
* `pypi` for production package publishing.

The `pypi` environment should require maintainer approval.

## TestPyPI Dry Run

Use TestPyPI before publishing a production package:

1. Confirm the release branch is merged into `main`.
2. Run the `Publish to TestPyPI` workflow manually.
3. Confirm the workflow builds both package artifacts.
4. Confirm the package appears on TestPyPI.
5. Install from TestPyPI in a clean virtual environment:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
python -m venv .venv-testpypi
source .venv-testpypi/bin/activate
python -m pip install --upgrade pip
python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ charmos
charm --help
```

TestPyPI is allowed to skip already-published files for the same version.
If you need a fully fresh dry run, bump to the next release candidate version before testing.

## Production PyPI Release

After the TestPyPI dry run succeeds:

1. Confirm `pyproject.toml` contains the intended version.
2. Confirm the draft GitHub Release has the correct changelog.
3. Create and push the version tag:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
git checkout main
git pull
git tag vX.Y.Z
git push origin vX.Y.Z
```

4. Wait for `Publish to PyPI` to complete.
5. Install the published package in a clean environment:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
python -m venv .venv-pypi
source .venv-pypi/bin/activate
python -m pip install --upgrade pip
python -m pip install charmos
charm --help
```

6. Publish the GitHub Release for the same tag.

## Hotfixes

Hotfixes should be narrow and traceable:

1. Identify the broken release or deploy.
2. Create a patch branch.
3. Apply the smallest safe fix.
4. Run required checks.
5. Run the TestPyPI dry run.
6. Publish a patch release or redeploy.
7. Document the fix in release notes.

## Rollback Options

* Revert and redeploy.
* Roll back a Cloud Run revision.
* Publish a patch package.
* Yank a bad PyPI package if appropriate.
* Apply a database mitigation migration.

PyPI does not allow reusing a deleted version.
If a package is broken, publish a new patch version rather than trying to replace the same version.


# Agentic Merge
Source: https://docs.charmos.io/platform/agentic-merge



OTA updates use an intelligent **Agentic Merge** approach to allow agents like OpenClaw to handle their own version upgrades. This mechanism ensures that any local customizations you have made are not blindly overwritten by a new software bundle.

## Overview

When an upgrade is triggered, the system does not simply replace your workspace with the new bundle. Instead, it calculates the differences (diff) between the old bundle and the new bundle, and then delegates the task of applying those differences to the local AI agent itself.

This approach mimics how a human developer resolves merge conflicts, allowing the agent to adapt the changes to your specific environment and customizations.

## Core Process & Logic

The Agentic Merge process involves the following key stages:

### 1. Trigger & Intercept

During an upgrade, the runner intercepts the payload and looks for an upgrade diff (`__charm_upgrade_diff__`). When detected, the `OpenClaw Adapter` activates Agentic Merge mode and logs:
`"🔧 Upgrade payload intercepted. Launching Agentic Merge Mode."`

### 2. Preserve Workspace State

In a normal startup, the workspace is seeded directly from the downloaded bundle. However, during an upgrade, this step is intentionally bypassed.
This is critical because the workspace must retain the **previous version's** files alongside any user customizations. If the workspace were seeded with the new bundle, the diff would not match the file contents, causing the merge to fail.

### 3. Pre-upgrade Snapshot (Safety Backup)

Before the agent alters any files, the system creates a backup of the current workspace state.
If the environment provides a `CHARM_UPGRADE_SNAPSHOT_VERSION`, a `.tar.gz` archive is saved to a hidden `.snapshots/` directory. This ensures a one-command rollback path if the merge fails.

### 4. Agent Execution

The OpenClaw Adapter injects the upgrade differences into a prompt template (e.g., `Execute upgrade with diff: {upgrade_diff}`).
The OpenClaw agent receives this instruction and acts on the diff. It intelligently applies the necessary changes to the existing files, respecting any custom modifications you may have made previously.

### 5. Completion & Rollback

* **Success:** Once the agent successfully applies the changes, the adapter prepends `UPGRADE_COMPLETE:` to the final output. This acts as a sentinel signal for the runner to finalize the version increment.
* **Rollback:** If an unrecoverable error occurs, the runner uses the `CHARM_ROLLBACK_SNAPSHOT_PATH` to clear the workspace and extract the snapshot, instantly reverting the agent to its last known healthy state.

## Summary

The OTA Agentic Merge is a robust workflow combining:

1. Snapshot backups
2. Preventing blind code overwrites
3. LLM-driven intelligent conflict resolution
4. Strict completion signals and rollback safety nets


# Ambient Desktop Companion
Source: https://docs.charmos.io/platform/ambient-desktop-companion



Charm Desktop is your **invocation assistant**, bringing AI agents directly into your current workflow without the need to switch contexts or open a browser window.

## Instant Access, Anywhere

With Charm Desktop running silently in your system tray, your agents are always just a keystroke away.

Press <kbd>Alt</kbd> + <kbd>Shift</kbd> + <kbd>Space</kbd> from anywhere in your operating system to instantly summon the mini-chat interface. This ambient design ensures you can maintain focus on your primary task, querying an agent or delegating work without breaking your flow.

## Fluid Context Switching

Different tasks require different experts. The desktop companion allows you to dynamically switch between different agents on the fly.

## Core Capabilities

* **Always-on Availability**: Lives in your system tray, ready to assist at a moment's notice.
* **Global Shortcut**: Use <kbd>Alt</kbd>+<kbd>Shift</kbd>+<kbd>Space</kbd> to toggle the window.
* **Deep Handoff**: Seamlessly add your agents discovered on the Charm Store to the desktop environment.
* **Native Notifications**: Agents can run long-running tasks in the background and alert you via OS-native notifications when they require input or have completed their work.
* **Local Context Advantage**: Desktop agents can be granted secure, localized context—such as reading local files or interacting with your hardware—when your use case demands it.


# Pricing Models
Source: https://docs.charmos.io/platform/app



Pricing is configured in `charm.yaml` and displayed on the Store listing.

## Basic Shape

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
pricing:
  model: "free"
  amount: 0
```

## Pricing Models

| Model          | Description                                              |
| -------------- | -------------------------------------------------------- |
| `free`         | No charge to install or run beyond platform usage rules. |
| `one_time`     | One purchase grants access.                              |
| `subscription` | Recurring access, usually monthly or annual.             |

## Subscription Example

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
pricing:
  model: "subscription"
  amount: 9.99
  billing_period: "monthly"
  trial:
    enabled: true
    days: 7
```

## Choosing a Price

Consider:

* how often the agent is used,
* whether it depends on costly tools,
* the value of the output,
* support expectations,
* whether the agent is experimental or production-ready.

## Notes

Pricing metadata should match the actual value and reliability of the agent. Misleading pricing or unclear usage expectations can lead to poor user trust.


# Base Images
Source: https://docs.charmos.io/platform/base-images



Charm runs agents inside managed container environments. In the decoupled architecture, base images are automatically selected based on your `adapter_type` to ensure the smallest footprint and fastest cold-start times.

## Automatic Selection

The Charm Cloud Runner automatically provisions the correct base image by reading your `charm.yaml` file:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  adapter:
    type: "langchain" # Automatically maps to the LangChain Base Image
```

Valid default mappings include:

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

## Custom Images

> \[!TIP]
> **Community Plugins**: Instead of building your own image from scratch, you can discover pre-built custom runtimes with tools like FFmpeg or Chromium in the [Community Plugins Registry](https://github.com/CharmAIOS/charm-community-plugin).

If the default images do not meet your needs (e.g., you need specialized system libraries, custom rendering engines, or are building your own adapter), you can override this behavior by providing a `custom_image` URL.

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  adapter:
    type: "custom"
  custom_image: "ghcr.io/your-org/your-custom-runtime:latest"
```

When `custom_image` is declared, the Cloud Runner completely ignores the adapter mapping and boots your provided Docker image directly.

Third-party adapter plugins (registered via `charm.adapters` entry points) **require** a `custom_image` that installs the plugin package — see [Custom Adapters](/guides/custom-adapters).

> **Note**: The legacy `runtime.mode` configuration (`standard` or `full`) is now deprecated and ignored by the Cloud Runner.

## Related Pages

* [Execution Modes](/platform/execution-modes)
* [Base Image Contributions](/oss/base-image)
* [Building Custom Runtimes](/guides/custom-runtimes)


# Execution Modes
Source: https://docs.charmos.io/platform/execution-modes



Charm supports three execution lifecycles. Choose the lifecycle that matches how your agent should behave for users.

## Configure Lifecycle

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  lifecycle: "serverless"
```

Valid values:

* `serverless`
* `interactive`
* `daemon`

## Comparison

| Lifecycle     | Best For                                | Runtime Behavior                 | State              |
| ------------- | --------------------------------------- | -------------------------------- | ------------------ |
| `serverless`  | One-off tasks, reports, transformations | Start, run, stop                 | Short-lived        |
| `interactive` | Chat, streaming, multi-turn UX          | Route through interactive worker | Thread-based       |
| `daemon`      | Background workers, bots, monitors      | Long-lived machine               | Persistent process |

## Serverless

Serverless is the default lifecycle. Use it for tasks that can complete within a bounded execution window.

Examples:

* summarize a document,
* generate a report,
* transform data,
* call external APIs.

## Interactive

Interactive agents stream responses back to the user and work well for conversational interfaces.

Use this for:

* chat agents,
* multi-turn assistants,
* agents that need immediate UI feedback.

## Daemon

Daemon agents run as long-lived machines. Use them when the agent needs to keep running after the initial request.

Use this for:

* Slack or Discord bots,
* monitors,
* scheduled or event-driven agents,
* persistent background workflows.

## Choosing a Mode

Start with `serverless` unless you specifically need streaming or always-on behavior. Move to `interactive` for chat UX and to `daemon` for background processes.


# Features
Source: https://docs.charmos.io/platform/features



This page is a placeholder index for Charm's platform feature documentation.

Use this page as a map of the major product capabilities available to agent builders and users.

### Server-Driven UI

Charm uses the `interface` section of `charm.yaml` to render user input forms and structure agent output. This lets builders ship useful app surfaces without writing a full frontend for every agent.

See [UI Protocol](/platform/ui-protocol).

### Managed Keys and Secrets

Agents can declare required environment variables in the manifest. The platform resolves managed keys at runtime instead of requiring users to hardcode secrets.

See [Keys](/platform/keys).

### OAuth Integrations

Agents can require user-authorized accounts such as Google or GitHub. Charm Store prompts users to connect accounts, and the runner injects provider tokens into the runtime.

See [OAuth](/platform/oauth).

### Threads and Memory

Threaded runs allow interactive agents to keep conversation context and display prior messages in the Store UI.

See [Threads](/platform/threads).

### Observability and Run History

Charm records runs, status events, logs, and usage metadata so creators can debug production behavior.

See [Observability](/platform/observability).

### Payments and Creator Revenue

Charm supports pricing metadata, wallet balance checks, checkout flows, and creator revenue tracking for commercial agents.

See [Billing](/platform/platform) & [Earn as You Go](/platform/earn-as-you-go).

### Interactive Runs

Interactive lifecycle agents stream real-time responses through the interactive worker.

See [Interactive Agent Template](/templates/interactive).

### Daemon Runs

Daemon lifecycle agents run as long-lived machines for persistent background behavior.

See [Daemon Agent Template](/templates/daemon).

### Ambient Desktop Companion

Charm's desktop companion direction is intended for agents that need local context, file access, hardware awareness, or persistent desktop workflows.

See [Ambient Desktop Companion](/platform/ambient-desktop-companion).


# Tool API Keys
Source: https://docs.charmos.io/platform/keys



When building your Charm Agents, you may rely on various external APIs and tools (e.g., search engines, web scrapers, data platforms). The Charm ecosystem securely provisions these credentials dynamically at runtime, ensuring your agent always has the access it needs—without hardcoding secrets into your bundles.

## Declaring Required Keys

Starting from UAC schema version `0.4.2`, your agent's required environment variables are split logically into `models` and `tools` within your `charm.yaml` manifest:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
# charm.yaml
version: "{manifest_version}"
# ...
runtime:
  adapter:
    type: "openclaw"
    environment_variables:
      models:
        - "OPENAI_API_KEY"
      tools:
        - "SERPER_API_KEY"
        - "FIRECRAWL_API_KEY"
```

* **`models`**: Used for your underlying LLM API keys (e.g., `OPENAI_API_KEY`, `GEMINI_API_KEY`).
* **`tools`**: Used for your External Services and MCP Skills (e.g., Web REST API keys, Data providers).

> \[!IMPORTANT]
> **Never hardcode API keys in your source code.** The Charm Cloud Runner securely resolves and injects these variables directly into your agent's execution container from the user's secure vault at runtime.

## Pre-Supported Tool Keys

The Charm Store automatically analyzes your `tools` definition array upon deployment. Currently, the Global Platform natively supports the following Tool Keys right out of the box:

* `TAVILY_API_KEY` (Tavily Search Engine)
* `FIRECRAWL_API_KEY` (Firecrawl Web Scraper)
* `SERPER_API_KEY` (Serper Google Search API)
* `BROWSERLESS_API_KEY` (Browserless Headless Chrome Integration)
* `JIGSAW_STACK_API_KEY` (JigsawStack)
* `BRAVE_API_KEY` (Brave Web Search)

If your agent only relies on keys from this whitelisted repository, your deployment pipeline to the Charm Store will be processed automatically without delay.

## Pushing Custom APIs or New Keys

We know developers build custom tools and push the boundaries of agent capabilities. If you are building a custom runtime skill or utilizing an API key not currently on the supported list, here is how you get it supported:

1. **Declare the exact key**: Define your unique, custom key (e.g., `MY_CUSTOM_TOOL_KEY`) in the `tools` array of your `charm.yaml`.
2. **Publish your Agent**: Run `charm publish` to push your bundle to the Charm Store.
3. **Automated Pending State**: The Charm pre-flight systems will intercept the deployment request upon detecting an unknown API requirement, and temporarily park your agent in a `Pending_Platform_Support` status.
4. **ChatOps Approval**: An automated alert is dispatched to the Charm Infrastructure Team via Discord. The team evaluates the compatibility requirements.
5. **Auto-Resume & Publication**: Once our team reviews and approves the key, your agent gets instantaneously verified and published. Your unique tool key is subsequently seeded into the global repository, meaning all future deployments involving this key will be instantly validated!

> \[!TIP]
> Need an API key approved faster for a time-critical deployment? Don't hesitate to directly reach out to the core team in our [Community Discord server](https://discord.gg/gdakynHUEb).


# Store Listing
Source: https://docs.charmos.io/platform/listing



A strong Store listing helps users understand what your agent does, when to use it, and what they will get back.

## Listing Metadata

Store metadata comes from `persona` in `charm.yaml`:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
persona:
  name: "Research Assistant"
  version: "0.1.0"
  description: "Create concise research briefs from a topic."
  authors: ["Your Name"]
  tags: ["productivity", "research"]
```

## Description

Use `description` for a short one-line summary. Use `full_description` for:

* use cases,
* examples,
* limitations,
* expected output,
* setup requirements.

## Assets

Recommended assets:

* square icon,
* wide banner,
* screenshots or examples when supported.

## Tags

Choose tags that match what users are searching for. Avoid stuffing unrelated tags.

## Version Updates

Update `persona.version` when you publish a new agent version. Use release notes or changelog entries for user-visible changes.


# OAuth & Identity
Source: https://docs.charmos.io/platform/oauth



OAuth lets an agent ask the user to connect an external account before the agent runs.

## Configure OAuth

Declare providers in `charm.yaml`:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
auth:
  providers:
    - name: "google"
      scopes:
        - openid
        - https://www.googleapis.com/auth/userinfo.email
```

The provider `name` should match the integration key configured in the OAuth provider layer.

## User Flow

1. The Store reads `auth.providers` from the published version.
2. If the user has not connected the provider, the Store opens an auth modal.
3. The user completes OAuth.
4. The runner fetches the provider token for that user.
5. The token is injected into the agent runtime.

## Runtime Tokens

Provider access tokens are exposed as environment variables such as:

* `GOOGLE_ACCESS_TOKEN`
* `GITHUB_ACCESS_TOKEN`
* `SLACK_ACCESS_TOKEN`

Do not print or store these tokens in agent output.

## Local Testing

Use mock OAuth locally when you need to test token-dependent code without a full provider connection:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --json '{"message": "Test"}' --mock-oauth
```

## Production Notes

Production OAuth requires provider-side configuration, such as Google Cloud OAuth consent screen settings and redirect URIs.


# Observability & Logs
Source: https://docs.charmos.io/platform/observability



Charm records execution data so builders can debug and improve published agents.

## What You Can Inspect

* Run status.
* Runtime logs.
* Status events.
* Errors.
* Token or usage metadata when available.
* Revenue and billing events where applicable.

## CLI Logs

Use:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm logs --path . --limit 50
```

This is the fastest way to inspect recent cloud behavior from your terminal.

## Studio

Charm Studio provides a web dashboard for run history, usage, debugging, and revenue visibility.

## Debugging Production Issues

When a cloud run fails:

1. Confirm the same input works locally.
2. Run `charm validate`.
3. Check logs.
4. Confirm required environment variables or OAuth connections.
5. Test in Docker if the issue looks runtime-specific.

## Telemetry Architecture

Charm utilizes an event-driven `TelemetryManager` built into the `CharmEmitter` system. When an agent runs, the SDK dispatches a standard set of lifecycle events (e.g., token generation, tool usage, errors) to the internal event bus.

By default, these events are serialized to `stdout` where the Charm Cloud Runner captures them and broadcasts them to end-users via Server-Sent Events (SSE).

### Pluggable Exporters

To support enterprise observability, Charm allows registering external Telemetry Exporters via Python entry points. The `TelemetryManager` iterates through all activated plugins defined in your `charm.yaml` and executes their lifecycle hooks in isolation, ensuring that a crash in a telemetry exporter does not halt your agent's execution.

### Standard Lifecycle Hooks

The following methods are dispatched by the `BaseTelemetryExporter` interface:

* `on_run_start(run_id, inputs)`: Fired when an agent begins execution.
* `on_run_end(run_id, outputs)`: Fired upon successful completion.
* `on_error(run_id, error)`: Fired if the agent crashes globally.
* `on_tool_start(tool_name, input_str)`: Fired when an agent invokes a tool/skill.
* `on_tool_end(tool_name, output)`: Fired when a tool returns a result.
* `on_tool_error(tool_name, error)`: Fired if a tool invocation raises an exception.
* `on_llm_new_token(token)`: Fired as the LLM streams characters.
* `on_agent_action(tool, tool_input)`: Generic action tracing.

> **Note:** If you want to build your own exporter, see the [Custom Telemetry Exporters Guide](/guides/telemetry-exporters).

## Access Control

Execution logs and telemetry data are only visible to authorized project owners and maintainers in the Charm Studio.


# Ecosystem
Source: https://docs.charmos.io/platform/overview



The Charm Platform turns agent projects into hosted applications. It provides the runtime, publishing, billing, authentication, and observability layers around your agent code.

## What the Platform Includes

Charm is made of several coordinated surfaces:

* **Charm CLI**: creates, validates, runs, and publishes agents.
* **Charm Store**: hosts published agents and user-facing app pages.
* **Cloud Runner**: executes serverless and interactive agents in isolated runtimes.
* **Daemon Runtime**: runs long-lived agents on Fly.io-backed machines.
* **Studio and Observability**: tracks runs, logs, usage, and revenue.
* **Docs and Templates**: help builders create compatible agents quickly.

## Core Capabilities

### 1. Isolated Execution

Agents run in managed environments so users do not need to provision infrastructure for every app.

### 2. Secrets and OAuth

Charm can inject platform-managed API keys and user-authorized OAuth tokens into the runtime when declared in `charm.yaml`.

### 3. Server-Driven UI

The manifest defines the input schema and output expectations so the Store can render a usable app without custom frontend code.

### 4. Billing and Monetization

Charm supports wallet balance checks, pricing metadata, subscriptions or one-time purchase flows, and creator revenue tracking.

### 5. Observability

Runs, logs, traces, and status events help creators understand how their agents behave in production.

## Runtime Lifecycles

* **Serverless**: short-lived task execution.
* **Interactive**: real-time streaming conversations.
* **Daemon**: always-on or long-running background agents.

See [Execution Modes](/platform/execution-modes) for details.

## Infrastructure

Charm currently uses a combination of:

* Google Cloud Run for the runner services,
* Supabase for auth and application data,
* Fly.io for daemon machines,
* Docker images for standard and full runtimes.

The exact production architecture may evolve, but the developer-facing contract is the manifest, CLI, and Store publishing flow.


# Billing & Payouts
Source: https://docs.charmos.io/platform/platform



Charm billing connects user payments, wallet usage, subscriptions, and creator revenue.

## Billing Surfaces

Billing can include:

* wallet balance,
* checkout,
* subscriptions,
* one-time purchases,
* creator revenue,
* payout processing.

## Payment Provider

Charm uses Stripe-backed flows for payments and webhook-driven billing events.

## Creator Revenue

Creator-facing revenue can come from:

* agent sales,
* subscriptions,
* usage-based revenue programs,
* platform-defined payout rules.

## Operational Notes

Billing changes are considered critical-path changes. They should include:

* tests,
* idempotency checks,
* staging validation,
* rollback or mitigation notes.

## Related Pages

* [Pricing Models](/platform/app)


# Skills & MCP Tools
Source: https://docs.charmos.io/platform/skills



Skills extend an agent with external tools or MCP-compatible capabilities.

## When to Use Skills

Use skills when your agent needs capabilities beyond normal Python code, such as:

* browser tools,
* service integrations,
* local automation wrappers,
* MCP servers,
* reusable task-specific tooling.

## Configure Skills

Skills belong under `runtime.skills` in `charm.yaml`.

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  skills:
    - name: "my-skill"
      source: "git:https://github.com/example/my-skill"
```

## Source Types

Supported sources may include:

* Git repositories.
* HTTPS zip archives.
* NPM packages.
* PyPI packages.
* Local development sources.

## Runtime Mode

Many MCP skills require browser or system-level dependencies. If your skill fails to load due to missing dependencies, you may need to use `adapter.type: openclaw` or provide a `custom_image` that includes those binaries.

## Best Practices

* Pin versions where possible.
* Document required secrets.
* Keep skill dependencies small.
* Test with Docker before publishing.


# Charm Store
Source: https://docs.charmos.io/platform/store



Charm Store is the user-facing marketplace for published Charm agents.

## What Users See

Store listings can include:

* agent name and description,
* author,
* tags,
* pricing,
* supported inputs,
* run history or app UI,
* OAuth requirements,
* install or execute actions.

Users can also access the [Community Plugins Registry](https://github.com/CharmAIOS/charm-community-plugin) via the top navigation bar to discover custom runtimes, adapters, and tools built by the open-source community.

## What Developers Publish

Developers publish an agent bundle and manifest with:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm push .
```

The Store reads metadata from `charm.yaml`, including:

* `persona`,
* `pricing`,
* `interface`,
* `auth`,
* `runtime`.

## Execution

When a user runs an agent, the Store sends the request to the runner. The runner validates auth, billing, runtime mode, environment variables, and bundle location before starting execution.

## Developer Checklist

* Use clear names and descriptions.
* Keep input fields understandable for non-technical users.
* Validate the manifest before publishing.
* Test the Store page after publishing.

Continue with [Publish](/quickstart/publish).


# Charm Studio
Source: https://docs.charmos.io/platform/studio



**Charm Studio** is a comprehensive analytics and observability dashboard designed for Agent developers. It provides deep insights into how your published agents are performing, who is using them, and how much revenue they are generating.

## Core Features

The Studio is divided into three main sections:

### 1. Analytics (Data & Insights)

This section gives you a bird's-eye view of your agent's performance through high-level metrics and detailed trend charts.

* **Key Metrics:** View your agent's Total Runs, Average Duration, Estimated Cost, and overall Success Rate.
* **Trend Graphs:** Track Execution Runs and New Installations over time (7 days, 30 days, or 6 months).
* **Behavioral Insights:**
  * **Token Usage:** A distribution chart showing how tokens are being consumed by underlying LLMs.
  * **Top Errors:** Identifies the most frequent causes of execution failure, helping you debug and improve your agent.
  * **Latency Distribution:** Shows a histogram of how long tasks typically take to complete.
  * **Session Depth:** Reveals user engagement by tracking how many conversational turns happen per session.

### 2. Usage & Logs

For granular debugging and auditing, the Usage tab provides paginated, invocation-level logs.

* **Invocation Details:** See exactly who called your agent, when, and what the outcome was.
* **Resource Tracking:** Detailed breakdown of LLM Tokens vs. Tool Tokens used, alongside the specific cost of that single run.
* **Event Timeline:** View the exact sequence of events (status updates, tool calls, etc.) that occurred during the execution.

### 3. Earnings (Creator Economy)

If your agent is monetized, the Earnings tab helps you track your financial performance. For more details on how monetization works, see the [Earn As You Go](../platform/earn-as-you-go) guide.

* **Wallet & Balance:** Integrates directly with **Stripe Connect** to show your available and pending balances.
* **Revenue:** A ledger of transactions and payouts related to user subscriptions or pay-per-use interactions with your agent.


# Threads & State
Source: https://docs.charmos.io/platform/threads



Threads represent ongoing user-agent sessions. They are especially important for interactive agents that need conversation history.

## What Threads Provide

* Multi-turn context.
* Message history.
* Run grouping.
* Follow-up questions.
* User-visible conversation state.

## Thread IDs

The Store passes a thread ID when a run belongs to an existing conversation. Agents can use this ID to associate output with a specific user session.

## State Snapshots

Some runtimes may receive state snapshots or history payloads. Agents should treat these as user/session context, not as global memory.

## Cross-Device Rehydration

Threads act as the critical key for enabling seamless cross-device continuity. When a user authenticates on a new device (e.g., moving from the Web Gateway to the Desktop App) and provides an existing `thread_id`, the platform automatically queries the database to rehydrate the complete execution history and session state. This allows interactive agents to resume conversations without losing context.

## Workspace Isolation

The cloud runner dynamically provisions highly isolated workspaces using the pattern `/workspace/{user_id}/{agent_id}/{thread_id}`.

* Serverless and interactive runs treat each thread as an isolated sandbox, ensuring that generated artifacts, uploaded files, and local memory (`MEMORY.md`) remain strictly segregated per user session.
* Daemon agents may share a longer-lived workspace depending on implementation.

## Use Cases

* Chat assistants.
* Iterative research.
* Follow-up edits.
* Support conversations.


# UI Protocol
Source: https://docs.charmos.io/platform/ui-protocol



## Overview

Charm Store uses a Server-Driven UI architecture.
Agents are required to return either spec-compliant JSON or standard Markdown.
Outputs are rendered into native UI components automatically by the Charm Universal Renderer.

### Standard Markdown

Supports direct string streaming with rich formatting, including titles, lists, code blocks, bold/italic text, and links.

### Structured JSON (Explicit Rendering)

The preferred way to trigger rich UI is to explicitly declare a `_charm_render_type` in your JSON output. This bypasses heuristic guessing and guarantees consistent, robust rendering.

#### Chart Components

```jsonc theme={"theme":{"light":"min-light","dark":"min-dark"}}
// 1. Bar Chart
{
  "_charm_render_type": "bar_chart",
  "title": "Revenue by Region",
  "data": [
    { "name": "NA", "value": 125000 },
    { "name": "EU", "value": 85000 }
  ]
}

// 2. Line Chart (Sparkline style)
{
  "_charm_render_type": "line_chart",
  "title": "User Growth",
  "data": [
    { "name": "Mon", "value": 10 },
    { "name": "Tue", "value": 25 },
    { "name": "Wed", "value": 40 }
  ]
}

// 3. Pie Chart
{
  "_charm_render_type": "pie_chart",
  "title": "Traffic Sources",
  "data": [
    { "name": "Organic", "value": 45 },
    { "name": "Direct", "value": 30 }
  ]
}
```

#### Data Grid

Renders a clean, scrollable table. Automatically extracts column headers from the keys of the first row object.

```jsonc theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "_charm_render_type": "data_grid",
  "title": "Recent Transactions",
  "rows": [
    { "id": "TX-1", "amount": "$450", "status": "Paid" },
    { "id": "TX-2", "amount": "$120", "status": "Pending" }
  ]
}
```

#### Metric Card

Renders a dashboard-style grid of metric cards with optional trend indicators.

```jsonc theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "_charm_render_type": "metric_card",
  "title": "Performance Dashboard",
  "metrics": [
    { "label": "Active Users", "value": 1204, "change": 12, "unit": "users" },
    { "label": "Churn Rate", "value": "2.4", "change": -0.5, "unit": "%" }
  ]
}
```

### Structured JSON (Heuristic Rendering)

If an explicit `_charm_render_type` is not provided, the Charm Store will attempt to infer the best UI representation based on the presence of certain keys.

#### Viral Card

Purpose-built for sharing and revealing underlying mechanisms.

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
// Trigger condition: JSON must include "type": "viral_card"

{
  "type": "viral_card",
  "content": {
    "cover_mode": true,        // Whether to enable the “reveal” cover mode
    "cover_data": {
      "title": "CONFIDENTIAL", // Title displayed on the cover (e.g. SECRET, TOP SECRET)
      "subtitle": "VIBE CHECK",// Subtitle displayed on the cover
      "cover_image": "https://..." // (Optional) Background image for the cover
    },
    "image_url": "https://...",    // Final result image shown after reveal (or when downloaded)
    "description": "This is your analysis result...", // Text description displayed below the card
    "action": {
      "type": "smart_share_trigger", // Fixed value, triggers native share/download logic
      "label": "REVEAL & SHARE"      // Button label
    },
    "metadata": {
      "sticker_link": "https://..."  // (Optional) Link automatically copied to clipboard when sharing (e.g. IG “Add Yours”)
    }
  }
}
```

#### Universal Timeline

Render a sequence of events as a vertical timeline.

```jsonc theme={"theme":{"light":"min-light","dark":"min-dark"}}
// Trigger condition (heuristic detection):
// Return an Array where each object contains any of the following keywords: date, time, year, timestamp

[
  {
    "date": "2024-01-15",
    "event": "Project Kickoff",
    "description": "Initial meeting with stakeholders.",
    "location": "Taipei HQ"
  },
  {
    "date": "2024-02-01",
    "event": "Alpha Release",
    "status": "success" // Will automatically render a green check icon
  }
]

// Special style keywords:

// Content containing "error", "fail", "conflict" → Red warning style
// Content containing "success", "complete", "solve" → Green success style
// Content containing "announce", "tweet", "report" → Blue informational style
```

#### Comparison View

Render multiple objects as a responsive comparison table.

```jsonc theme={"theme":{"light":"min-light","dark":"min-dark"}}
// Trigger condition (heuristic detection):
// Return an Array where the object keys contain comparison-related keywords: vs, competitor, price, feature, target

[
  {
    "Feature": "AI Model",
    "Charm_OS": "GPT-4o + Claude 3.5",
    "Competitor_X": "GPT-3.5"
  },
  {
    "Feature": "Viral Sharing",
    "Charm_OS": "Native Support",
    "Competitor_X": "None"
  }
]

// This array will be rendered as a responsive comparison table
```

#### Optimization Diff

Display the differences between content before and after optimization, suitable for copywriting revision or code refactoring agents.

```jsonc theme={"theme":{"light":"min-light","dark":"min-dark"}}
// Trigger condition (heuristic detection):
// Return an Object containing keys related to both "original" and "optimized" content

// Original-related keys: original, before, weakness
// Optimized-related keys: optimized, after, rewrite

{
  "section": "Instagram Bio Rewrite",
  "original_content": "I like coffee and coding.",      // Original content
  "optimized_version": "Fueled by caffeine.\nBuilding the future of AI.\nCheck my vibe below.",  // Optimized content
  "reason": "Added emojis and line breaks for better readability." // Explanation for the optimization
}
```

#### Universal Article

Suitable for long-form content, automatically extracts headings and optimizes formatting.

```jsonc theme={"theme":{"light":"min-light","dark":"min-dark"}}
// Trigger condition (heuristic detection):
// Return an Object containing a title (or headline) and content (or body)
// The content length must exceed 150 characters

{
  "title": "The Future of AI Agents",          // Title or headline
  "author": "Charm Intelligence",            // Optional metadata
  "body": "Artificial Intelligence is evolving from chatbots to autonomous agents...",  // Main content (long-form, >150 characters)
  "key_takeaways": [                          // Array will be automatically rendered as a list
    "Agents act autonomously",
    "Memory is crucial"
  ]
}
```

### Custom UI (HTML & SVG via Markdown)

The Charm Universal Renderer is built on top of Markdown. The renderer natively supports **HTML and SVG elements**, safely sanitized via DOMPurify. This enables agents to deliver custom UI by returning valid HTML or SVG strings inside their markdown response.

*For code examples on how to dynamically stream HTML or SVG strings from your agent, see the [How to Render Rich UI](/guides/output-renderers) guide.*

> **Security Note:** The Charm Store frontend uses DOMPurify to strip `<script>`, `<iframe>`, and other potentially malicious vectors. Supported capabilities are constrained to static HTML, CSS classes (Tailwind is supported on the Store), and SVGs.

### Best Practices

* **Explicit is better than implicit:** Use `_charm_render_type` whenever possible instead of relying on heuristics.
* **Keep JSON flat:** Minimize deep nesting. The Universal Renderer performs best with flat objects.
* **Use standard keywords:** When using heuristic detection, using standard English field names (e.g., `date` instead of `d_time`) ensures the correct UI is triggered.
* **Mix in Markdown:** You can still use Markdown syntax in JSON string values. The renderer will parse it correctly.


# Build Your First Agent
Source: https://docs.charmos.io/quickstart/first-app



Create your first Charm agent, run it locally, and show how the project is structured.

## 1. Create a Project

Run:

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

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
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](/references/manifest).

## 4. Run Locally

If the template accepts a simple text input, run:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input "Hello world"
```

If your template expects structured JSON, run:

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

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

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

* Learn how publishing works in [Publish](/quickstart/publish).
* Browse starter projects in [Templates](/templates/overview).
* Review platform execution modes in [Execution Modes](/platform/execution-modes).


# Installation
Source: https://docs.charmos.io/quickstart/install



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`](https://github.com/astral-sh/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.

## Install with uv

For agent development:

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

For local runner and Docker sandbox testing:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
uv add "charmos[runner]"
```

## Install with pip

For agent development:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pip install charmos
```

For local runner and Docker sandbox testing:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pip install "charmos[runner]"
```

## Verify the CLI

Run:

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

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

## Optional: Create a Project Virtual Environment

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
python -m venv .venv
```

On macOS or Linux:

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

Then install Charm:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pip install "charmos[runner]"
```

## Optional: Docker Sandbox

Charm can run agents locally in a container that more closely matches the cloud runtime.

To use sandbox mode:

1. Install `charmos[runner]`.
2. Start Docker.
3. Run your agent with `--docker`.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input "Hello from Docker" --docker
```

## Next Step

Continue to [Build Your First Agent](/quickstart/first-app).


# Quickstart
Source: https://docs.charmos.io/quickstart/overview



Use this path when you want to move from an empty folder to a published Charm agent with the fewest decisions.

Charm projects are built around a manifest file, `charm.yaml`, and an adapter-specific entry point. The CLI uses those files to run your agent locally, validate it, package it, and publish it to Charm Store.

## Planned Flow

1. Install the Charm CLI.
2. Create or clone a starter agent.
3. Run the agent locally.
4. Validate `charm.yaml`.
5. Publish the agent.
6. Open it in Charm Store.

## Pages

* [Installation](/quickstart/install)
* [Build Your First Agent](/quickstart/first-app)
* [Publish](/quickstart/publish)

## Recommended First Template

Start with the Python template if you are new to Charm:

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

After that, try another scaffold (`openclaw`, `research-agent`, and others—see [Starter Templates](/templates/overview)), or read these **configuration guides** (not separate `charm init` template IDs):

* [Interactive Agent](/templates/interactive) for real-time chat-style apps.
* [Daemon Agent](/templates/daemon) for always-on background agents.
* [OAuth integration](/templates/oauth-integration) for agents that need user-authorized external accounts.


# Publish
Source: https://docs.charmos.io/quickstart/publish



Please make sure to review our current technical specifications and limitations before publishing, to ensure your agent can run stably on the Charm Cloud Runner.

### Runtime Environments

Charm automatically selects the optimal container base image depending on your framework (`adapter.type`). See [Base Images](/platform/base-images) for more information on available runtimes and how to inject your own custom Docker image.

### Technical Constraints

Please read this section carefully. Most deployment failures are caused by violating these rules.

1. **No Heavy Local Models / GPU Support**
   * **Do NOT** load local LLMs (e.g., Ollama, Llama.cpp) or large embedding models (e.g., HuggingFace transformers > 500MB) into memory.
   * The runtime environments **do not have GPU access (No CUDA)**.
   * **Solution**: Use cloud APIs (OpenAI, Anthropic, Groq, HuggingFace Inference API) for all inference tasks.

2. **Resource Limits**
   * Memory varies by execution mode:
     * **Serverless**: **2 GB RAM**, 2 vCPU.
     * **Daemon**: **1 GB RAM**, 1 shared vCPU.
   * Attempting to load large datasets or models beyond these limits will cause an OOM (Out Of Memory) crash.
   * The default execution timeout for serverless jobs is **600 seconds** (10 minutes), but you can customize this via `policies.execution_timeout_seconds` in your `charm.yaml`.
   * **Solution**: If your agent needs to run 24/7 or maintain persistent state, configure `lifecycle: "daemon"` in your `charm.yaml`.

3. **No Inbound Ports in Serverless Mode**
   * In `serverless` mode, **do NOT** start servers that listen on inbound ports (e.g., `flask run`, `express`, `fastapi`). The serverless runner is designed for task execution, not hosting web services — any process waiting for inbound HTTP requests will timeout.
   * **Note**: This restriction does **not** apply to `daemon` mode, which runs a persistent VM with full networking capabilities.

4. **System Package Installation**
   * While `apt-get` is technically available inside the container, installing system packages at runtime is **strongly discouraged** for serverless jobs because packages are not persisted between invocations and will significantly slow down each cold start.
   * **Solution**: If you need system binaries like **FFmpeg** or **Chrome**, use an adapter that provides them (e.g., `adapter.type: "openclaw"` includes FFmpeg, Node.js, and browser libraries) or provide your own `custom_image` in `charm.yaml` with everything pre-installed.

5. **No Absolute Paths**
   * The runner executes in a dynamic container. **Do NOT** use hardcoded paths like `/Users/me/project/...`.
   * **Solution**: Use relative paths (e.g., `./data/...`) or `os.getcwd()`.

> If you hit any issues, feel free to open an [issue](https://github.com/CharmAIOS/Charm/issues/new/choose) or ask in our [community](\{discord_url}). It really helps us make the docs and product better.

## Zero-Ops Publishing

Register your agent on the Charm Store.

> If you’re using uv, please prefix all commands with uv run.

#### Authentication

Sign in to the Charm platform and link your account.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm auth login
```

#### Preparing your UAC manifest

Refer to the [Manifest Configuration Guide](/guides/manifest) and [Manifest Reference](/references/manifest) for guidance on how to author a charm.yaml.

#### Local Validation & Development

Step A: Static Analysis

Use Pydantic to validate that the YAML fields conform to the UAC schema.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm validate .
```

Step B: Local Execution

See [Local Run](../guides/local-run) for detailed information.

#### Publishing

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


# Platform API Reference
Source: https://docs.charmos.io/references/api



This reference is auto-generated from the Charm Cloud Runner OpenAPI specification. Use the sidebar to browse individual endpoints grouped by domain.

## Endpoint Groups

| Group        | Description                                               |
| ------------ | --------------------------------------------------------- |
| **Execute**  | Start an agent run with SSE streaming output.             |
| **Agents**   | CRUD operations for agent registrations.                  |
| **Versions** | Upgrade, rollback, and list agent versions.               |
| **Runs**     | Inspect, complete, cancel, and track run progress.        |
| **Threads**  | Query run history within a conversation thread.           |
| **Studio**   | Dashboard analytics: stats, installs, errors, usage logs. |
| **Billing**  | Wallet, subscriptions, transactions, and Stripe webhooks. |
| **Daemons**  | Manage long-running daemon agent processes.               |

## Authentication

API routes use different auth models depending on the caller:

* **Supabase bearer token** — user-facing requests from Charm Store / Studio.
* **Runner secret** — internal callbacks from the Cloud Runner.
* **Cron secret** — scheduled maintenance jobs.
* **Stripe webhook secret** — payment event verification.

## Base URL

```
{api_base_url}
```

## OpenAPI Spec

The raw specification powering this reference is available at [`openapi.json`](/openapi.json). You can import it into Postman, Insomnia, or any OpenAPI-compatible tool.


# Manifest Reference
Source: https://docs.charmos.io/references/manifest



`charm.yaml` is the manifest that tells Charm how to display, run, price, and publish an agent.

## Annotated Reference

This is a fully annotated example to understand specific capabilities or customization options.

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

# ==================================================================
# Charm Agent Manifest (Annotated Reference)
# ==================================================================

version: "{manifest_version}"  # [System] The UAC Spec version (Do not change manually).

# ------------------------------------------------------------------
# 1. Identity & Store Metadata
# ------------------------------------------------------------------
persona:
  name: "My Charm Agent" # Display Project Name (Max 50 chars)
  version: "0.1.0" # [Agent] Your Agent's Semantic Version. Update this when publishing updates.
  description: "A short description of this agent." # Tagline (Card view, Max 100 chars)
  
  # Full description supports Markdown. Used for the Info Page.
  full_description: |
    # My Charm Agent
    ...
  # Describe usage, available capabilities, and expected deliverables.
    
  authors: ["Brand, Company, or Individual Name"]
  tags: ["research", "productivity"] # We use tags to categorize agents for users, so please make sure your first tag is one of Productivity, Developer, Creative, Learning, Lifestyle, Search & News, or Others.
  license: "MIT"
  
  # Assets for the Storefront
  assets:
    icon: "https://your-site.com/assets/icon.png" # 512x512 Square
    banner: "https://your-site.com/assets/banner.png"  # 1200x600 Wide

pricing:
  model: "free"  # Options: free, subscription, one_time.
  amount: 0      # Price in USD. Ignored when model is 'free'.
  # billing_period: "monthly" # Options: monthly, annual (for subscription)
  # trial:
  #   enabled: true
  #   days: 7

# ------------------------------------------------------------------
# 2. UI Generation
# ------------------------------------------------------------------
# Defines the input form shown to users.
# It uses standard JSON Schema.
interface:
  input:
    type: "object"
    required: ["topic"] # Mandatory fields
    properties:
      # Example 1: Simple Text Input
      topic:
        type: "string"
        title: "Research Topic"
        default: "AI Agents"
      
      # Example 2: Large Text Area
      details:
        type: "string"
        title: "Extra Details"
        description: "Paste any background info here."
      
      # Example 3: File Upload
      # The Runner will download the file and inject the filename into this variable.
      document:
        type: "string"
        title: "Upload Document"

      # Example 4: Number Input
      depth:
        type: "integer"
        title: "Search Depth"
        default: 3
        minimum: 1
        maximum: 5

  # Maps input fields to frontend UI components
  ui:
    details: { "ui:widget": "textarea" }
    document: { "ui:widget": "file" }

  output:
    type: "object"
    description: "The structure of the final result."

  # Optional: For agents that persist state across runs
  state:
    format: "json"
    schema:
      type: "object"
      properties:
        history:
          type: "array"
      additionalProperties: false

# ------------------------------------------------------------------
# 3. Runtime Configuration
# ------------------------------------------------------------------
runtime:
  adapter:
    # - crewai / langchain / langgraph : Standard Python Frameworks
    # - openclaw : Configuration-driven Agent
    # - custom : Pure Python functions
    type: "crewai"
    
    # --------------------------------------------------------------
    # ENTRY POINT: Where is your agent object?
    # Format: <python_module_path>:<variable_or_function_name>
    # --------------------------------------------------------------
    # [Case A] For Frameworks (CrewAI, LangChain): Point to the agent instance.
    entry_point: "src.main:my_crew"
    
    # [Case B] For Custom (Pure Python): Point to a function or class instance.
    entry_point: "src.my_script:run_pipeline"

    # [Case C] For OpenClaw: Optional (uses default host if empty)
    entry_point: ""
    
    # --------------------------------------------------------------
    # SECURE ENV VARS: List keys your agent needs.
    # DO NOT put values here. The Runner injects them securely.
    # --------------------------------------------------------------
    environment_variables:
      models:
        - "OPENAI_API_KEY"
      tools:
        - "SERPER_API_KEY"

  # --------------------------------------------------------------
  # ENGINE CONFIG: For OpenClaw or specific engines
  # --------------------------------------------------------------
  config:
    system_prompt: "You are an expert researcher."
    model: "gpt-4o"
    temperature: 0.0
    auto_install_dependencies: true

  # --------------------------------------------------------------
  # SKILLS & MCP TOOLS
  # --------------------------------------------------------------
  skills:
    
    # [Source: Git] 
    - name: "research-flow"
      source: "git:https://github.com/openclaw/skill-researcher"
      version: "main" # Or Commit Hash / Tag (If you want to pin the version)

    # [Source: Zip] 
    - name: "finance-analyst"
      source: "https://clawhub.ai/download/skills/finance-v1.2.0.zip"

    # [Source: NPM] 
    - name: "google-search"
      source: "npm:@modelcontextprotocol/server-google-search"

    # [Source: PyPI] 
    - name: "local-time"
      source: "pip:mcp-server-time"
  
  # --------------------------------------------------------------
  # Memory & State Storage (Optional)
  # --------------------------------------------------------------
  memory:
    provider: "local" # Options: local, redis, postgres (Requires custom memory plugin)
    
  # --------------------------------------------------------------
  # Observability (Optional)
  # --------------------------------------------------------------
  telemetry:
    - "datadog" # Enable custom telemetry exporters
  
  # --------------------------------------------------------------
  # Base Image
  # --------------------------------------------------------------
   # Override standard images with your own custom Docker image
  # custom_image: "ghcr.io/your-org/my-agent-image:latest"

  # --------------------------------------------------------------
  # Execution Mode
  # --------------------------------------------------------------
   # "serverless": Runs once and shuts down. Perfect for one-time tasks, async workflows, or heavy batch processing.
   # "interactive": Built for continuous dialogue. Keeps context alive for seamless, back-and-forth interactions.
   # "daemon": 24/7 always-on. Ideal for monitoring, event listeners, or continuous background services.
  lifecycle: "serverless"

# ------------------------------------------------------------------
# 4. Authentication
# ------------------------------------------------------------------
# Declare if your agent needs user's OAuth tokens.
# NOTE: Use the official scope strings defined by the provider.
auth:
  providers:
    # [OAuth: Google]
    - name: "google"
      scopes: 
        - "https://www.googleapis.com/auth/calendar.readonly"
        - "https://www.googleapis.com/auth/gmail.send"

    # [OAuth: GitHub]
    - name: "github"
      scopes: 
        - "repo"
        - "read:user"

# ------------------------------------------------------------------
# 5. Governance (Policies)
# ------------------------------------------------------------------
policies:
  allow_internet_access: true
  max_steps: 20
  # Optional: Override serverless run timeout for this agent (seconds).
  # execution_timeout_seconds: 600
```

### Field Reference Table

| Section   | Field                  | Type    | Description                                                               |
| --------- | ---------------------- | ------- | ------------------------------------------------------------------------- |
| Persona   | name                   | String  | Public display name of the agent.                                         |
|           | version                | String  | The semantic version of the agent (e.g., 1.0.0).                          |
|           | description            | String  | Short tagline for search results and cards.                               |
|           | assets.icon            | URL     | 512x512px PNG/JPG image.                                                  |
| Pricing   | model                  | Enum    | free, subscription, one\_time.                                            |
|           | amount                 | Number  | Price in USD. Ignored if free.                                            |
|           | billing\_period        | Enum    | monthly, annual (for subscription).                                       |
|           | trial.enabled          | Boolean | Whether trial is offered.                                                 |
|           | trial.days             | Integer | Number of trial days.                                                     |
| Interface | input                  | Schema  | Standard JSON Schema defining user inputs.                                |
|           | ui                     | Object  | Maps input keys to UI widgets (e.g. textarea, file).                      |
|           | state                  | Schema  | Optional JSON Schema defining persistent state.                           |
| Runtime   | adapter.type           | Enum    | crewai, langchain, langgraph, custom, openclaw.                           |
|           | entry\_point           | String  | Python path (module:obj). Optional for openclaw.                          |
|           | environment\_variables | Object  | Map of 'models' and 'tools' requiring Env keys (e.g., OPENAI\_API\_KEY).  |
|           | config                 | Object  | Engine-specific configuration (e.g. OpenClaw system\_prompt, model).      |
|           | skills                 | List    | List of MCP Skills to mount.                                              |
|           | custom\_image          | String  | Custom Docker image URI for the runtime environment.                      |
|           | memory                 | Object  | Configuration for persistent memory and state storage (e.g., provider).   |
|           | telemetry              | List    | List of telemetry exporter names to enable.                               |
|           | mode                   | Enum    | standard (Default), full. Selects the container environment (Deprecated). |
| Auth      | providers              | List    | List of OAuth providers.                                                  |
| Policies  | max\_steps             | Integer | Maximum execution steps to prevent infinite loops.                        |


# References
Source: https://docs.charmos.io/references/overview



This section will collect reference material that should be easy to scan and stable across releases.

## Planned Reference Areas

* CLI commands.
* SDK package APIs.
* `charm.yaml` manifest schema.
* Runner and platform API surfaces.
* Adapter and lifecycle compatibility.

## Available References

* [SDK Reference](/references/sdk): public Python package surface and versioning guidance.
* [Platform API Reference](/references/api): API groups used by the Store, runner, billing, and integrations.
* [Manifest Reference](/references/manifest): `charm.yaml` fields and configuration model.
* [CLI Commands](/cli/init): command-specific reference pages.

## Reference Philosophy

Guides explain how to complete a workflow. References explain exact fields, commands, endpoints, and compatibility expectations.

When adding new public behavior, update the relevant reference page or leave an explicit placeholder until generated docs are available.


# SDK Reference
Source: https://docs.charmos.io/references/sdk



This page is the landing page for Charm's Python SDK reference. It is intentionally concise until generated API reference pages are added.

## Planned Sections

* Installation.
* Public modules.
* Agent interfaces.
* Runtime helpers.
* Adapter APIs.
* Version compatibility.

## Install

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pip install {cli_package}
```

For runner and local sandbox support:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pip install "charmos[runner]"
```

## Public Surfaces

The stable SDK surface should include:

* CLI commands exposed through `charm`.
* Manifest validation models.
* Runtime adapters.
* Runner protocol helpers.
* Template scaffolding.

Internal implementation modules may change without a public compatibility guarantee until the open-source release policy is finalized.

## Compatibility

SDK compatibility is tied to the `version` field in `charm.yaml`.

When publishing a package release, update:

* package version,
* docs version,
* changelog,
* manifest compatibility notes.

## Future Generated Docs

This page should eventually link to generated Python API documentation from docstrings or type annotations.


# Code Review Agent
Source: https://docs.charmos.io/templates/code-review



Use this template for agents that inspect code changes and return review feedback.

## Use Case

* Pull request summaries.
* Risk analysis.
* Style and maintainability feedback.
* Test gap suggestions.

## Typical Inputs

* Repository or diff content.
* Review focus.
* Language or framework.
* Optional style guide.

## Runtime Notes

Code review agents often need access to repository files, diffs, or pasted snippets. Keep the input schema explicit so users know what context to provide.

## Development Flow

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm init my-review-agent --template code-review-agent
cd my-review-agent
charm validate .
charm run . --json '{"code": "def example(): pass", "focus": "security"}'
```

## Publishing Checklist

* Output separates findings by severity.
* The agent avoids exposing secrets from reviewed code.
* The prompt encourages actionable review comments.


# Customer Support Agent
Source: https://docs.charmos.io/templates/customer-support



Use this template for agents that triage customer requests, draft replies, or guide users through support workflows.

## Use Case

* FAQ answering.
* Ticket triage.
* Reply drafting.
* Troubleshooting flows.

## Typical Inputs

* Customer message.
* Product area.
* Urgency.
* Optional account or context fields.

## Runtime Notes

Support agents should produce clear, empathetic, and safe responses. If the agent depends on private account data, declare OAuth or API key requirements explicitly.

## Development Flow

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm init support-agent --template customer-support-agent
cd support-agent
charm validate .
charm run . --json '{"message": "I cannot log in"}'
```

## Publishing Checklist

* Tone is appropriate for customer-facing output.
* The agent asks clarifying questions when needed.
* Sensitive account actions require human confirmation.


# Daemon Agent Template
Source: https://docs.charmos.io/templates/daemon



Daemon agents are always-on or long-lived agents. They are used when a task should keep running beyond a single request, maintain state between events, or respond to external triggers.

There is **no** `charm init --template daemon` starter. Use a daemon-oriented scaffold such as `slack-bot` or `customer-support-agent`, or start from `openclaw` and set `runtime.lifecycle: daemon` as required.

## Use Case

Use this lifecycle for agents that need persistent background execution, scheduled behavior, or long-lived state.

## Prerequisites

* Charm CLI.
* A daemon-capable adapter such as OpenClaw.
* Production runner configured with Fly.io daemon settings.

## Configuration Surface

Document these fields:

* `runtime.lifecycle: daemon`
* `runtime.adapter.type`
* `policies`

Example:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  adapter:
    type: "openclaw"
  lifecycle: "daemon"
```

## How Daemon Runs Work

1. The runner receives a daemon lifecycle request.
2. The runner prepares the agent bundle and environment variables.
3. A machine is created or reused in the configured Fly.io app.
4. The daemon process starts and continues running until paused, restarted, or terminated.

## Auto-Recovery & Persistence

**Fault Tolerance:** Daemon machines deployed on the cloud runner are equipped with automatic recovery capabilities. If the underlying Fly.io machine goes `offline` or is `stopped` due to infrastructure scaling or resource reassignment, the runner detects this state upon the next interaction and automatically issues a `restart` command to resurrect the container.

**Important:** Because daemon machines may restart automatically, you must pair them with an external `runtime.memory.provider` (such as Supabase or Redis) to persist state. When state is safely externalized, auto-restarts remain entirely transparent to the end user.

## Production Requirements

The production runner must be configured with:

* `FLY_API_TOKEN`
* `FLY_APP_NAME`
* optional `FLY_REGION`

The Fly app acts as the machine pool for daemon agents. Individual daemon machines are created by the runner through the Fly Machines API.

## Run and Publish

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm validate .
charm push
```

## Operational Notes

* Daemon agents can cost more than serverless agents because machines may stay alive.
* Always test pause, restart, and terminate behavior.
* Avoid hardcoded local paths.
* Keep secrets in platform-managed environment variables, not source code.


# Data Pipeline Agent
Source: https://docs.charmos.io/templates/data-pipeline



Use this template for agents that transform, validate, summarize, or route structured data.

## Use Case

* CSV or JSON cleanup.
* Data validation.
* ETL-style transformations.
* Report generation.
* API-to-API data movement.

## Typical Inputs

* File or data payload.
* Transformation instructions.
* Output format.
* Validation rules.

## Runtime Notes

Data pipeline agents should keep memory and runtime limits in mind. For large files or long-running jobs, consider splitting the workflow or using a daemon-oriented design.

## Development Flow

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm init data-agent --template data-pipeline-agent
cd data-agent
charm validate .
charm run . --json '{"data": "name,age\\nAlice,30", "task": "clean", "output_format": "csv"}'
```

## Publishing Checklist

* Input schema describes accepted data.
* Output format is predictable.
* Errors are returned clearly.
* Large local files are excluded from bundles with `.charmignore`.


# Hermes Agent Template
Source: https://docs.charmos.io/templates/hermes



The Hermes Agent template creates a ready-to-publish agent powered by [Nous Research Hermes Agent](https://github.com/NousResearch/hermes-agent). It runs as a daemon with persistent memory, self-improving skills, and cross-session recall.

## Create

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm init my-hermes-agent --template hermes-agent
```

## What You Get

```
my-hermes-agent/
├── charm.yaml           # lifecycle: daemon, adapter: hermes
├── .charmignore
├── requirements.txt     # charm-adapter-hermes dependency
└── src/
    ├── __init__.py
    └── main.py           # AIAgent instance — customize here
```

## Prerequisites

* Charm CLI installed.
* An LLM API key (OpenRouter, OpenAI, or Anthropic).
* For production: a daemon-capable runner (Fly.io backend configured).

## Configuration

Set your API key before running:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
export OPENROUTER_API_KEY="sk-or-..."
```

### Changing the model

Edit `src/main.py` or set the environment variable:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
export CHARM_HERMES_MODEL="anthropic/claude-sonnet-4-20250514"
```

### Key charm.yaml fields

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  adapter:
    type: "hermes"
    entry_point: "src.main:agent"
  lifecycle: "daemon"       # persistent container on Fly.io
```

## Run Locally

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run --input '{"query": "Hello, who are you?"}'
```

## Publish

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm validate .
charm push
```

## Why Daemon?

Hermes agents store conversation history, auto-generated skills, and user models in an SQLite database. The `daemon` lifecycle ensures this data persists across interactions by mounting a shared workspace (`CHARM_WORKSPACE_DIR`). Without daemon mode, the database would be lost after each serverless invocation.

## Further Reading

* [Hermes Adapter reference](/adapters/hermes)
* [Daemon Agent lifecycle](/templates/daemon)
* [charm-adapter-hermes on GitHub](https://github.com/CharmAIOS/charm-adapter-hermes)


# Interactive Agent Template
Source: https://docs.charmos.io/templates/interactive



Interactive agents are designed for real-time conversations and streaming responses. They are routed through Charm's interactive worker instead of the standard serverless execution path.

There is **no** `charm init --template interactive` starter. Use any scaffold (for example `python`), then set `runtime.lifecycle: interactive` in `charm.yaml` as shown below.

## Use Case

Use this lifecycle for chat-style agents that need low-latency streaming, thread history, and real-time user interaction.

## Prerequisites

* Charm CLI.
* A supported interactive runtime.
* Published version available in Charm Store for end-to-end UI testing.

## Configuration Surface

Document these fields:

* `runtime.lifecycle: interactive`
* `runtime.adapter.type`
* `interface.input`
* `runtime.adapter.environment_variables`

Example:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  adapter:
    type: "custom"
    entry_point: "src.main:agent"
    environment_variables:
      models:
        - OPENAI_API_KEY
  lifecycle: "interactive"
```

## How Interactive Runs Work

1. The Store sends the user's message to the runner.
2. The runner authenticates the user and creates a run record.
3. The runner forwards the request to the interactive worker.
4. The worker streams assistant output back to the browser.
5. Completion callbacks persist the run and messages.

## Local and Staging Testing

* Use the Store UI to test thread behavior.
* Confirm the published version has `runtime.lifecycle: interactive`.
* Confirm the runner has `CHARM_INTERACTIVE_WORKER_URL` configured in staging or production.
* Confirm required environment variables are available to the worker.

## Run and Publish

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm validate .
charm push
```

## Limitations

Interactive agents should return quickly and stream user-facing output. Long-running background tasks are a better fit for [Daemon Agent](/templates/daemon).


# OAuth Integration Agent Template
Source: https://docs.charmos.io/templates/oauth-integration



There is **no** `charm init --template oauth-integration` starter in the CLI. OAuth is configured in `charm.yaml` with `auth.providers` on top of any scaffold template (for example `python` or `openclaw`).

OAuth integration agents require a user to connect an external account before the agent runs. Charm uses the `auth.providers` block in `charm.yaml` to declare those requirements.

## Use Case

Use this pattern when an agent needs user-authorized access to external services such as Google, GitHub, Slack, or Notion.

## Prerequisites

* Charm CLI.
* Nango configured for the provider.
* Store and runner configured with matching Nango environment variables.

## Configuration Surface

Document these fields:

* `auth.providers`
* `auth.providers[].name`
* `auth.providers[].scopes`
* provider-specific access token environment variables

Example:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
auth:
  providers:
    - name: google
      scopes:
        - openid
        - https://www.googleapis.com/auth/userinfo.email
        - https://www.googleapis.com/auth/userinfo.profile
```

When a user opens the agent, Charm Store checks whether the required provider connection exists. If not, it prompts the user to connect through OAuth.

## Runtime Environment

After the user connects an account, the runner can inject provider tokens into the agent runtime. For example:

* `GOOGLE_ACCESS_TOKEN`
* `GITHUB_ACCESS_TOKEN`
* `SLACK_ACCESS_TOKEN`

The exact token name depends on the provider name.

## Production Requirements

OAuth requires both the Store and runner to use the same Nango environment:

* `NEXT_PUBLIC_NANGO_HOST`
* `NEXT_PUBLIC_NANGO_PUBLIC_KEY`
* `NANGO_SERVER_URL`
* `NANGO_SECRET_KEY`

Provider settings must also be configured in the provider dashboard, such as Google Cloud OAuth client settings for Google integrations.

## Run and Publish

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm validate
charm push
```

## Testing Checklist

* The agent version includes `auth.providers` in `charm.yaml`.
* The Store shows the OAuth connection modal.
* The provider redirects back successfully.
* The runner logs show that the provider token was injected.
* The agent handles missing or expired tokens gracefully.


# OpenClaw Skill Agent
Source: https://docs.charmos.io/templates/openclaw



Use this template for OpenClaw agents that rely on tools, skills, browser automation, or computer-use style workflows.

## Use Case

* Browser automation.
* Tool-rich research.
* MCP skill orchestration.
* Desktop-like workflows.
* Long-running agents with daemon lifecycle.

## Runtime Configuration

OpenClaw agents natively use the heavy openclaw runtime image:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  adapter:
    type: "openclaw"
```

Use daemon lifecycle when the agent should stay alive:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  lifecycle: "daemon"
```

## Development Flow

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm init openclaw-agent --template openclaw
cd openclaw-agent
charm validate .
```

## Publishing Checklist

* Required skills and environment variables are declared.
* Browser or system dependencies are supported natively by the OpenClaw adapter.
* Long-running behavior is tested as a daemon.
* Output is understandable to end users.


# Starter Templates
Source: https://docs.charmos.io/templates/overview



Templates are starter projects that give you a working `charm.yaml`, source file, and dependency setup for a common agent pattern.

Use a template when you want to start from a known runtime shape instead of wiring a manifest from scratch.

## Create from a Template

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

Then run:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
cd my-agent
charm validate .
charm run . --input "Hello"
```

## Template Categories

The first seven rows are **CLI scaffolding templates**: use `charm init <dir> --template <id>` with the exact IDs in each linked page (for example `research-agent`, not `research`). Run `charm init --help` or `charm init . --interactive` to see all IDs.

The last three rows are **configuration guides** for common lifecycles and OAuth. They are not separate `charm init` template names—start from any scaffold above and adjust `charm.yaml`.

| Template                                              | Best For                                  | Runtime Shape                        |
| ----------------------------------------------------- | ----------------------------------------- | ------------------------------------ |
| [Python Agent](/templates/python)                     | Minimal custom Python agents              | Serverless                           |
| [Research Agent](/templates/research)                 | Topic research and synthesis              | Serverless                           |
| [Code Review Agent](/templates/code-review)           | Developer workflow automation             | Serverless                           |
| [Customer Support Agent](/templates/customer-support) | Support triage and response drafting      | Daemon                               |
| [Data Pipeline Agent](/templates/data-pipeline)       | Structured processing and data workflows  | Serverless                           |
| [Slack Bot](/templates/slack-bot)                     | Chat and workspace automation             | Daemon or integration-oriented       |
| [OpenClaw Skill Agent](/templates/openclaw)           | Browser/tools-heavy agent execution       | Full runtime                         |
| [Interactive Agent](/templates/interactive)           | Real-time chat and streaming              | Interactive                          |
| [Daemon Agent](/templates/daemon)                     | Always-on background agents               | Daemon                               |
| [OAuth integration](/templates/oauth-integration)     | Agents requiring user-authorized accounts | Any lifecycle (via `auth.providers`) |

## Choosing a Template

* Choose **Python** first if you are learning Charm.
* Choose **OpenClaw** when the agent needs tool-rich browser or desktop-style automation.
* Read the **Interactive**, **Daemon**, and **OAuth integration** guides when you need those runtime or auth shapes, then apply them to your manifest (possibly starting from `python`, `openclaw`, `slack-bot`, or `customer-support-agent`).

## What Every Scaffolding Template Includes

* `charm.yaml` manifest.
* Agent entry point.
* Dependency file.
* Example input schema.
* Runtime adapter configuration.

After selecting a template, review the manifest before publishing. The manifest controls how the Store renders inputs and how the runner executes your agent.


# Python Agent Template
Source: https://docs.charmos.io/templates/python



The Python template is the simplest way to build a Charm agent. It is a good fit for agents that call APIs, transform text, run lightweight data processing, or wrap an existing Python function.

## Use Case

Use this template for a minimal Python agent with a small dependency surface.

## Prerequisites

* Python 3.10+.
* Charm CLI.
* Optional: Docker for isolated local runs.

## Configuration Surface

The important `charm.yaml` fields are:

* `persona`
* `interface`
* `runtime.adapter`
* `runtime.lifecycle`
* `policies`

Typical runtime configuration:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  adapter:
    type: "custom"
    entry_point: "src.main:agent"
  lifecycle: "serverless"
```

The entry point should resolve to an object or callable that the runner can invoke.

## Expected Project Shape

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
my-agent/
├── charm.yaml
├── requirements.txt
└── src/
    └── main.py
```

## Local Development

Run with a simple input:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input "Summarize this idea"
```

Run with JSON input:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --json '{"message": "Summarize this idea"}'
```

Validate before publishing:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm validate .
```

## Run and Publish

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run
charm validate
charm push
```

## When to Choose Another Template

* Use [Interactive Agent](/templates/interactive) for streaming chat.
* Use [Daemon Agent](/templates/daemon) for always-on execution.
* Use [OpenClaw Skill Agent](/templates/openclaw) for heavy browser or tool automation.


# Research Agent
Source: https://docs.charmos.io/templates/research



The research agent template is for agents that gather information, synthesize findings, and return a structured answer or report.

## Use Case

Use this template for:

* market research,
* competitor summaries,
* topic briefs,
* literature-style summaries,
* internal knowledge gathering.

## Typical Inputs

A research agent usually accepts:

* research `query` (required in the shipped template),
* desired `depth` (`brief`, `detailed`, `comprehensive`),
* audience,
* optional source constraints,
* output format.

## Runtime Notes

Research agents often call external search, scraping, or browser tools. Declare required tool keys in `runtime.adapter.environment_variables` and avoid hardcoding credentials.

Example:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  adapter:
    environment_variables:
      tools:
        - TAVILY_API_KEY
        - FIRECRAWL_API_KEY
```

## Development Flow

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm init my-research-agent --template research-agent
cd my-research-agent
charm validate .
charm run . --json '{"query": "AI agent marketplaces", "depth": "detailed"}'
```

## Publishing Checklist

* Input schema is clear for non-technical users.
* Output format is predictable.
* Tool keys are declared in the manifest.
* The agent handles missing or low-quality search results.


# Slack Bot
Source: https://docs.charmos.io/templates/slack-bot



Use this template for agents that respond to Slack events or provide always-on workspace automation.

## Use Case

* Team assistant bots.
* Alert triage.
* Scheduled updates.
* Internal workflow automation.

## Runtime Mode

Slack bots are usually daemon-style agents because they need to stay available for events.

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
runtime:
  lifecycle: "daemon"
```

## Required Configuration

You will typically need:

* Slack app credentials.
* Bot token or OAuth connection.
* Event routing configuration.
* A production daemon runtime.

## Development Flow

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm init slack-agent --template slack-bot
cd slack-agent
charm validate .
```

## Publishing Checklist

* Slack credentials are not hardcoded.
* Events are idempotent.
* The bot handles missing permissions gracefully.
* Daemon lifecycle is tested in staging before production.