Configuration System

An agency's configuration — agent definitions, routing rules and system options — is written in YAML and validated at load time. From 2.4.481 it is kept in the agency's store (Redis or Postgres), not in a project file.

Where the Configuration Lives

In the store, versioned. Every Studio save is a new version. Studio's versions page lists each save with a diff, and make default restores one.
The same on every pod. Every pod runs the latest version. A saved change reaches the other pods within about 15 seconds and is applied live.
Your project holds only custom code and .env. The .env names the agency (LEAFMESH_AGENCY_NAME) and where its store is.
Loading a team. create-leafmesh --start (or leafmesh config import --if-empty) loads a team into an empty store once and never overwrites it (2.4.498+). New projects have no configuration file. An older project's config.yaml is still imported once, on the first start with an empty store, then ignored. from_yaml() and from_dict() still work.
An empty store starts a blank agency, which you build in Studio.

Starting an Agency

from leafmesh import LeafMesh

# Starts the agency named by LEAFMESH_AGENCY_NAME from the store set in .env
leafmesh = LeafMesh.from_store()

# .env
LEAFMESH_AGENCY_NAME=my_swarm
LEAFMESH_STORE=redis
REDIS_HOST=localhost
REDIS_PORT=6379

Configuration Structure

# Required
name: "my_swarm"                   # Unique swarm identifier
architecture: "managed_mesh"       # Architecture pattern
agents: {}                         # Agent definitions

# Optional
version: "1.0.0"                   # Config version

manager:                           # Automatic coordination & oversight
  enabled: true
  model: "gpt-4o-mini"            # Model used for event classification
  prompt: |                        # Optional: evaluation criteria
    Escalate if the same issue loops more than twice.
  coordination_rules:
    max_response_time: 30

mesh:                              # Mesh communication
  max_retries: 2

observability:                     # Built-in observability
  enabled: true
  tracing_enabled: true
  service_name: "my_swarm"
  metrics_retention_minutes: 1440

self_healing:                      # Agent health watch (see Self-Healing)
  enabled: true                    # watch + notify (default true)
  actions_enabled: false           # restart / backup by itself (default false)

entry_points:                      # Named API endpoints
  - name: "customer_inquiry"
    target: "triage_agent"
    description: "Incoming customer inquiries"

# Runtime behaviour — all optional, all independent (v2.4.131)
timeouts:                          # How long the agency waits
  llm_hard_timeout_s: 300
  mesh_call_default_timeout_s: 60  # Default mesh call wait (was mesh.call_timeout)
scheduler:                         # Cadence of scheduled work
  cron_min_interval_seconds: 60
runtime:                           # Connection liveness, worker coordination
  lease_seconds: 120
limits:                            # Size, rate and concurrency ceilings
  max_parallel_tool_calls: 4
connectors:                        # Outbound connector behaviour
  traceparent_inject: false

From 2.4.482 the store is set only in .env, never in the YAML:

# .env
LEAFMESH_AGENCY_NAME=my_swarm
LEAFMESH_STORE=redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
# TTL for general data (seconds)
REDIS_DEFAULT_TTL=3600
# TTL for sessions (seconds; 7 days, the default)
REDIS_SESSION_TTL=604800

Credentials and addresses (keys, tokens, passwords, URLs, hosts) never go in the configuration either: they are entered only in the vault, on Studio's Infrastructure page, and a block picks its record with connection: <name>. Model keys in .env still work.

Runtime Behaviour Is Declared, Not Environmental

The last five blocks tune how the agency runs. Before v2.4.131 they were environment variables; they're now part of the config like everything else, which means they're versioned with your agency, visible in Agent Studio, and identical on every pod.

Declare only what you want to change — every field is optional, and omitting one keeps the SDK's default. Full field reference with defaults: Configuration API → Runtime Behaviour Blocks.

If you're upgrading from an older version and had LEAFMESH_* tuning variables set, see the migration table — those variables are no longer read, and an unmigrated value quietly reverts to its default.

Validation

Configuration is validated at load time. Validation includes:

Type checking: All fields are type-checked
Required fields: name and agents are required; LLM agents require name and prompt
Default values: Sensible defaults for optional fields (temperature: 0.1, timeouts.mesh_call_default_timeout_s: 300)
File size limits: YAML files are checked against a 10MB limit
YAML syntax: Parse errors are caught with file location
Encoding: UTF-8 encoding is validated
No inline secrets: an inline key, token, password or address (including a ${ENV:default} reference) is refused, naming the field and the vault record to create. A connection name may still come from the environment: connection: "${SLACK_CONNECTION:slack-workspace}" is fine.

Environment-Specific Configuration

Give each environment its own agency: each environment's .env names its agency (LEAFMESH_AGENCY_NAME) and its store, and the same code starts it with LeafMesh.from_store(). Each agency keeps its own versioned configuration.

Development

name: "my_swarm_dev"

agents:
  solver:
    name: "solver"
    model: "gpt-4o-mini"      # Cost-effective for testing
    temperature: 0.1

Its .env:

# .env
LEAFMESH_AGENCY_NAME=my_swarm_dev
LEAFMESH_STORE=redis
REDIS_HOST=localhost
# Short TTL for dev
REDIS_SESSION_TTL=300

Production

name: "my_swarm_prod"

self_healing:
  actions_enabled: true            # let the mesh restart or back up a failing agent
  cooldown_s: 600
  max_actions_per_hour: 3

# Observability is built-in and auto-enabled by your license key

Its .env:

# .env
LEAFMESH_AGENCY_NAME=my_swarm_prod
LEAFMESH_STORE=redis
REDIS_PASSWORD=your-password
REDIS_SESSION_TTL=7200
# Setting this turns on cluster mode
REDIS_CLUSTER_NODES=redis-1:6379,redis-2:6379,redis-3:6379

Runtime Configuration

Changes Apply Live

A saved setting applies without anyone pressing restart (2.4.484). The Manager and its summarizer take their settings live (rules, timing, routing, model, what it listens to). A change that still needs a reload — brokers, self_healing.enabled, api.cors_origins, lease timing, architecture, auto_discover, consumer_inflight_max, or switching the Manager on or off — makes the agency reload itself in place within seconds. Every pod applies a saved change the same way. Only evolution_api's host, port and enabled need a process restart.

Scheduling

Scheduled work is declared on the agent, not registered through a runtime call:

agents:
  collector:
    name: "collector"
    wake_up: "5m"                # or "@daily", or cron: "*/5 * * * *"
    timezone: "Asia/Kolkata"     # optional; defaults to UTC

Edit wake_up through the config API or Agent Studio and the schedule is rebuilt — no restart, no separate scheduling call. Cadences below scheduler.cron_min_interval_seconds (default 60s) are rejected at load.

See Scheduled Agents for expression syntax and catch-up behaviour.

Next Steps

Agent Configuration — Complete agent YAML reference
Architecture — How configuration maps to runtime components
Installation — Setting up your environment

LeafMesh — YAML configuration, versioned in your store