Metadata-Version: 2.4
Name: charter-daemon
Version: 0.0.1
Summary: Long-lived Charter worker daemon that multiplexes local runs over one gateway connection.
Project-URL: Homepage, https://github.com/charter-tool/charter-daemon
Project-URL: Repository, https://github.com/charter-tool/charter-daemon
Project-URL: Issues, https://github.com/charter-tool/charter-daemon/issues
Project-URL: Changelog, https://github.com/charter-tool/charter-daemon/blob/main/CHANGELOG.md
Author: Paulo Alvarado Garcia
License: MIT
License-File: LICENSE
Keywords: agent,automation,charter,daemon,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9
Requires-Dist: charter-core>=0.0.1
Requires-Dist: click>=8.0
Requires-Dist: pydantic>=2.0
Description-Content-Type: text/markdown

# charter-daemon

**Long-lived worker that multiplexes Charter runs over one gateway connection.**
The local `charter` CLI hands off `--detached` runs to this daemon over a
Unix-domain socket; the daemon keeps a single outbound WebSocket to
[charter-gateway](https://github.com/charter-tool/charter-gateway) so runs and
their events flow through one authenticated channel regardless of how many
runs are in-flight.

charter-daemon is part of the [Charter](https://github.com/charter-tool/charter)
toolchain: workflow-as-code with the discipline of a CI pipeline — typed
inputs, explicit checkpoints, durable state, and an auditable record of what
happened.

## How it fits in

```
charter (CLI) ──unix socket──> charter-daemon ──websocket──> charter-gateway
                                     │
                                     └── ManagedRun (charter-core)
```

- **Project-scoped:** one daemon instance serves one Charter project root.
- **Host-installed:** runs alongside the `charter` CLI on the same machine.
- **One gateway connection per daemon:** backpressure and authentication are
  concerns of the gateway, not of each individual run.

The project runtime in `.charter/.venv` is required when detached workflow
runs execute project-installed integrations or workflow-local Python code,
but not just to start the daemon process.

## Install

```bash
pip install charter-daemon
```

Requires Python 3.11+ and a compatible `charter-core`.

## Run

```bash
charter-daemon start --project-path /path/to/project \
                     --gateway http://127.0.0.1:8765
```

Run `charter-daemon --help` for the full option list. Typical deployments
bring up `charter-gateway` alongside the daemon via the
[charter-localdev](https://github.com/charter-tool/charter-localdev) Docker
Compose stack.

## Development

```bash
uv sync --group dev
uv run pytest
uv run ruff check charter_daemon tests
uv run ruff format charter_daemon tests
```

Install pre-commit hooks once with `uv run pre-commit install`.

## License

Released under the [MIT License](LICENSE). See [CHANGELOG.md](CHANGELOG.md)
for the release history.
