CLI and configuration

The converge CLI runs one or more agent processes with configurable transport, pool, and discovery. Configuration is read from environment variables and, optionally, a file (YAML or TOML). The CLI entrypoint is installed when the package is installed; YAML support requires the cli extra.

Entrypoint

converge <command> [options]

Commands:

  • run: Start one or more agents with generated identities, optional transport (local or TCP), optional pool and discovery, and a long-running loop until interrupted.

Options for run:

  • -c / --config: Path to a config file (YAML or TOML). Default: value of CONVERGE_CONFIG if set.

  • -v / --verbose: Enable DEBUG-level logging.

Examples:

converge run
converge run -c config.yaml -v

Environment variables

Configuration keys can be set via environment variables. Names follow the pattern CONVERGE_<KEY> with <KEY> in uppercase:

Variable

Purpose

CONVERGE_TRANSPORT

Transport type: local (default) or tcp.

CONVERGE_HOST

Host for network transports (default 127.0.0.1).

CONVERGE_PORT

Port for TCP transport (default 8888). With multiple agents and TCP, each agent uses port + index.

CONVERGE_AGENTS

Number of agents to run in this process (default 1). When > 1, a shared pool manager and task manager are created.

CONVERGE_POOL_ID

If set, a pool with this id is created and all agents join it.

CONVERGE_DISCOVERY_STORE

If set to memory, an in-memory discovery store is used and agents register on start; if a path, a file-based store is used.

CONVERGE_STORE_BACKEND

Optional explicit store backend: memory, file, sqlite, or redis.

CONVERGE_STORE_PATH

Backend-specific location/URL (file path, sqlite db path, or redis URL).

CONVERGE_CONFIG

Default config file path (same as -c).

File-based config is merged with env: file values override env when both specify the same key.

Config file format

Supported formats: YAML (.yaml, .yml) and TOML (.toml). YAML parsing requires pyyaml (install from source with pip install -e ".[cli]"). TOML uses the standard library tomllib (Python 3.11+).

The file must evaluate to a single mapping (dict). Keys: transport, host, port, agents, pool_id, discovery_store, store_backend, store_path.

Example YAML (multi-agent with pool and discovery):

transport: local
agents: 3
pool_id: my-pool
discovery_store: memory
store_backend: memory

Example YAML (TCP, single agent):

transport: tcp
host: 0.0.0.0
port: 9000

Example TOML:

transport = "tcp"
host = "127.0.0.1"
port = 8888
agents = 2
pool_id = "workers"
discovery_store = "memory"
store_backend = "sqlite"
store_path = "/tmp/converge.sqlite3"

Example TOML (Redis backend):

transport = "tcp"
host = "0.0.0.0"
port = 9000
agents = 1
store_backend = "redis"
store_path = "redis://localhost:6379/0"

Run behavior

With converge run, the process:

  1. Loads config (env + optional file).

  2. Sets logging level to DEBUG if -v is used.

  3. Creates a store from config. Preferred mode is store_backend + store_path; legacy discovery_store remains supported.

  4. If discovery is enabled (via store_backend or discovery_store), creates DiscoveryService(store=...); each agent registers on start and unregisters on stop.

  5. If agents > 1 or pool_id is set, creates shared PoolManager and TaskManager using the same store instance for recovery consistency.

  6. For each of agents (default 1): generates an identity, creates an Agent and transport (local or TCP with host/port), builds an AgentDescriptor when discovery is used, and constructs an AgentRuntime with pool_manager, task_manager, discovery_service, and agent_descriptor as appropriate.

  7. Starts all runtimes with asyncio.gather, then runs until KeyboardInterrupt.

  8. On interrupt, stops all runtimes cleanly.

To use WebSocket transport or custom persistence, use the Python API (see Quick start and API reference).

Migration from discovery_store

discovery_store remains supported for backward compatibility, but new configs should prefer:

  • store_backend

  • store_path

Migration mapping:

  • discovery_store: memory -> store_backend: memory

  • discovery_store: /path/to/dir -> store_backend: file, store_path: /path/to/dir

When using multi-agent or multi-process coordination, prefer sqlite or redis store backends for better shared-state semantics.