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

pip install charter-daemon

Requires Python 3.11+ and a compatible charter-core.

Run

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 Docker Compose stack.

Development

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. See CHANGELOG.md for the release history.