Installation

LeafMesh Installation

LeafMesh is distributed via PyPI. A valid licence key is needed once, to connect each new environment (2.4.538). Your licence key is used once to connect a new environment, and never stored on your servers.

Quick Install

pip install leafmesh

That gives you the core runtime and every LLM provider — OpenAI, Anthropic, Google, Bedrock, Vertex and Microsoft Foundry all work with no extra install.

Channels, listeners, knowledge backends, storage drivers and MCP are optional extras. If you want all of them in one command:

pip install 'leafmesh[all]'

Use [all] when you don't yet know which features you'll enable — it is the batteries-included option and the one we recommend for a first project. See Optional Extras for the individual names and for the one group [all] deliberately leaves out.

You will be told if something is missing. From v2.4.131 LeafMesh checks your config against what's installed at startup and prints the exact pip install command for anything you declared but can't run. A declared feature with a missing package no longer fails silently.

Project Scaffolding (Recommended)

The fastest way to get started is with the create-leafmesh CLI:

pip install create-leafmesh create-leafmesh --list # browse the 20 ready-made teams create-leafmesh my-project --template customer-support cd my-project

Run it without --template for an interactive arrow-key picker. Every template generates a complete project with:

  • No configuration file (2.4.498+). The team is loaded into the agency's store on the first start, only if the store is empty, and you change it in Studio from then on
  • agency/ — Auto-discovered agent implementations
  • tests/ — Test suite for the template's agents
  • main.py — Entry point script
  • Dockerfile + docker-compose.yml — Container assets
  • .env — Environment variable template
  • requirements.txt — Dependencies

From 2.4.481 the agency's configuration lives in its store (Redis or Postgres), not in a project file. Every Studio save is a new version: Studio's versions page lists each save with a diff, and make default restores one. Every pod runs the latest. The project keeps only its custom code and its .env; LeafMesh.from_store() starts the agency named by LEAFMESH_AGENCY_NAME from the store set in .env. An empty store starts a blank agency, which you build in Studio.

See the Scaffolding CLI guide for all options and the Templates Overview for what each template's agents do. When you're ready for the cloud, the bundled leafmesh-deploy command pushes any scaffolded project to AWS, Azure, or GCP — see Cloud Deploy.

Requirements

System Requirements

  • Python: 3.10 – 3.14
  • Redis: 6.0+ (7.0+ recommended)
  • OS: Linux, macOS, Windows (WSL recommended)
  • Memory: 4GB minimum, 8GB+ recommended

Core Dependencies (Included)

All of these are installed automatically with pip install leafmesh:

  • pydantic>=2.0.0 — Data validation
  • redis>=5.0.0 — State management
  • PyYAML>=6.0.0 — Configuration
  • openai>=1.0.0 — Default LLM provider
  • structlog>=23.0.0 — Structured logging
  • aiohttp>=3.9.0 — Async HTTP
  • Observability — Managed observability pipeline included by default

Optional Extras

Install only what you enable. Every name below is a pip extra:

ExtraWhat it turns on
channelsSlack, Telegram, Teams, email (Discord coming)
slack telegram teamsOne channel at a time
email imapOutbound email, IMAP inbox listening
listenersKafka, SQS, MQTT and IMAP event sources
kafka sqs mqttOne listener at a time
knowledgeAll knowledge backends and document parsing
knowledge-postgres knowledge-pinecone knowledge-mongo knowledge-docsOne backend at a time
postgresPostgres as the persistence backend
schedulerCron wake-ups and scheduled agents
mcpModel Context Protocol servers
allEverything in this table, in one command
pip install 'leafmesh[channels,knowledge]' # pick and choose pip install 'leafmesh[all]' # or take the lot

The AI-framework connectors are the one exception and are not included in [all]:

pip install 'leafmesh[all]' 'leafmesh[crewai]'

crewai, langgraph, autogen, a2a, composio, claude_agent and openai_agents each pin their own versions of shared libraries, and those pins contradict one another — asking pip for all seven at once fails to resolve. You bridge to one framework, so install the one you use. This is also why they can't be core dependencies: pip install leafmesh would fail for everyone.

Redis Setup

# macOS brew install redis && redis-server # Ubuntu/Debian sudo apt-get install redis-server && redis-server # Docker (recommended) docker run -d -p 6379:6379 redis:7-alpine

Environment Variables

# Required on every start, the same on every server (2.4.538) export LEAFMESH_ENV_TOKEN="..." # The environment token Studio showed (Studio › Keys) export LEAFMESH_AGENCY_NAME="my-agency" # The agency's name in the store export LEAFMESH_VAULT_KEY="..." # Vault key: 32 random bytes, URL-safe base64 (2.4.507: required) # The store (REDIS_URL, or LEAFMESH_STORE + REDIS_HOST/REDIS_PORT) is the fourth required setting. # The licence key is NOT one of these: give it once with `leafmesh auth register` (see below). export OPENAI_API_KEY="sk-..." # OpenAI API key (or save it on Infrastructure → Models) # Needed for signed webhooks (/webhook/…, /callback/…, the knowledge refresh) export LEAFMESH_WEBHOOK_SECRET="..." # 32 random bytes, URL-safe base64; never derived (2.4.507) # Optional provider keys export ANTHROPIC_API_KEY="sk-ant-..." # For Claude models export GOOGLE_API_KEY="..." # For Google models # Cloud gateway providers export AWS_ACCESS_KEY_ID="..." # For Bedrock (or use IAM role / ~/.aws/credentials) export AWS_SECRET_ACCESS_KEY="..." export GOOGLE_CLOUD_PROJECT="my-project" # For Vertex AI (or save Vertex under Infrastructure → Models) export GOOGLE_APPLICATION_CREDENTIALS="/path/key.json" # For Vertex AI (or use gcloud auth / GKE SA) # Microsoft Foundry (Azure AI Foundry) export AZURE_FOUNDRY_API_KEY="..." # API key from Azure Portal # export AZURE_FOUNDRY_TOKEN="..." # Or Entra ID Bearer token # Store (set only here, never in the YAML, from 2.4.482) export LEAFMESH_STORE="redis" # redis (default) | postgres export REDIS_HOST="localhost" export REDIS_PORT="6379" # export REDIS_PASSWORD="..." # export REDIS_URL="redis://user:pw@host:6379/4" # Or the whole server in one URL (rediss:// = TLS) # export DATABASE_URL="postgresql://user:pw@host:5432/db?sslmode=require" # Postgres, same idea

A URL (REDIS_URL or DATABASE_URL) names the whole server; the single names fill in anything it leaves out.

Three values the mesh never makes for you (2.4.507). create-leafmesh writes the first two into a new project's .env (random, never printed, never replaced once set). An older project adds the lines by hand.

  • LEAFMESH_VAULT_KEY: the key the built-in vault is encrypted with. The mesh writes no key file and derives no key. With none, the start stops with "no vault key". Every instance of one agency uses the same key. A new key means a new, empty vault. A key file from an older version is still read, and the start says to move it into .env.
  • LEAFMESH_WEBHOOK_SECRET: signs webhooks. It is no longer derived from the licence key. Without it the mesh starts with a warning, and every signed webhook (/webhook/…, /callback/…, the knowledge refresh) answers 503 until it is set.
  • LEAFMESH_ENV_TOKEN: the environment token Studio showed when you created the agency. The mesh does not start without it (LeafMeshLicenseError).

Model keys in the environment keep working, and a key saved on Infrastructure → Models in Studio fills any gap. From 2.4.492, when a model key is in both places, the vault's key is used, and the start log warns: <VAR> is set in the environment and in the vault record '<name>' — the vault's is used; remove it from .env. Every other credential and address (channel tokens, webhook addresses, broker hosts, connector keys) is entered only in the vault, on Studio's Infrastructure page.

The full list of store variables (Redis TLS, Redis Cluster via REDIS_CLUSTER_NODES, Postgres and its pool) is on Persistence.

Security & Hardening Knobs

All optional with safe defaults. Most operators won't need to touch any of these — they're documented here so you can tune them for your compliance regime.

# MCP subprocess allowlist (comma-separated absolute paths or basenames) export LEAFMESH_MCP_COMMAND_ALLOWLIST= # empty = warn-only # Behind a reverse proxy that sets X-Forwarded-For / X-Forwarded-Host export LEAFMESH_TRUST_FORWARDED_FOR=0 # 1 only when such a proxy sits in front # YAML env-var expansion blocklist (prevents YAML from reading credential env vars) export LEAFMESH_YAML_ENV_BLOCKLIST= # unset = default list, "" disables, otherwise prefix list export LEAFMESH_YAML_ENV_BLOCKLIST_EXTRA= # extend the default blocklist # Security headers export LEAFMESH_HSTS_ENABLED=1 export LEAFMESH_REFERRER_POLICY=no-referrer export LEAFMESH_CSP="default-src 'none'; frame-ancestors 'none'; base-uri 'none'"

Trace content is redacted by default (security.telemetry_redact_pii: true since 2.4.480): your input and output content is replaced whole with <redacted bytes:N>, while names, models, tokens, cost, status, errors and timings stay visible. Set it to false in the agency's configuration to keep content readable; credentials are always masked either way. See Configuration API.

The defences that used to have an environment switch to turn them off are now always on: the prompt guardrail, webhook signature checks (timestamp and nonce included), Teams and inbound-email sender verification, and the event-bus mode guard. Their old switches are listed under Upgrading to 2.4.382 – 2.4.386 below.

CORS origins are not configurable via env — use api.cors_origins in the agency's configuration instead. See Configuration → API Server.

Runtime Tuning Moved to config.yaml (v2.4.131)

From 2.4.481 the configuration these settings belong to lives in the agency's store, not in config.yaml; edit it in Studio. See Upgrading to 2.4.481 below.

Timeouts, rate limits, payload ceilings, scheduler cadence and connector toggles used to be environment variables. They are now declared config, and the environment variables are no longer read.

Why: a number that changes how your agency behaves belongs with the rest of your agency's definition — versioned in YAML, visible in Agent Studio, editable through the config API, and the same on every machine. An environment variable is invisible to everyone who wasn't told about it.

If you set any of the variables below, move the value into config.yaml before upgrading. Nothing errors if you don't — the setting simply reverts to its default, which is the failure mode worth watching for.

Environment variable (no longer read)Now declared as
timeouts.llm_hard_timeout_stimeouts.llm_hard_timeout_s
scheduler.cron_min_interval_secondsscheduler.cron_min_interval_seconds
limits.webhook_max_payload_byteslimits.webhook_max_payload_bytes
limits.webhook_rate_limit_maxlimits.webhook_rate_limit_max
limits.webhook_rate_limit_window_slimits.webhook_rate_limit_window_s
limits.webhook_replay_skew_slimits.webhook_replay_skew_s
limits.max_session_history_byteslimits.max_session_history_bytes
limits.knowledge_max_ingest_total_byteslimits.knowledge_max_ingest_total_bytes
limits.knowledge_query_rate_limit_maxlimits.knowledge_query_rate_limit_max
limits.knowledge_query_rate_limit_window_slimits.knowledge_query_rate_limit_window_s
(removed — no replacement)knowledge provider settings.max_docs_per_ingest
(removed — no replacement)knowledge provider settings.max_doc_bytes

The two knowledge document caps became per-provider rather than global: a policy-document index and a scraped-web index rarely want the same ceiling.

# Before — environment # export `timeouts.llm_hard_timeout_s`=300 # export `limits.webhook_rate_limit_max`=120 # After — config.yaml timeouts: llm_hard_timeout_s: 300 limits: webhook_rate_limit_max: 120

Every field is optional. Leave one out and the ADK's own default applies — you only declare what you actually want to change. Full field-by-field reference: Configuration API → Runtime Behaviour Blocks.

The environment variables that remain above are the ones that aren't agency behaviour: secrets, deployment wiring and machine-level security posture.

Upgrading to 2.4.509 (from 2.4.502)

Check this before you upgrade:

  • Three .env values (2.4.507). Add LEAFMESH_VAULT_KEY and LEAFMESH_WEBHOOK_SECRET, and make sure LEAFMESH_ENV_TOKEN is set (see Environment Variables). With no vault key the start stops; with no environment token it stops too; with no webhook secret, signed webhooks answer 503. The webhook secret is no longer derived from the licence key, so give the new secret to every system that signs webhooks to the mesh.
  • After a vault switch the old vault is not read (2.4.507). When you choose another vault for new credentials, credentials in the old one are not moved and not read. Enter each one again in the new vault. See Bring Your Own Vault.
  • connector_config.mode is now after_handoff (2.4.508). A configuration that still says mode is refused at load, and the error gives the new line. A Python helper (n8n(), zapier(), mcp(), composio()) given mode= raises ValueError.
BeforeNow
mode: syncafter_handoff: reply
mode: callbackafter_handoff: wait
—after_handoff: move_on (new)

wait and move_on work on n8n, Zapier and Lindy (Lindy's default is now wait). See After the hand-off.

What's new:

  • Hand-offs answered later don't hold a worker (2.4.508). With wait or move_on, the agent's run ends as soon as the work is sent. The hand-off is kept in the store and survives a restart. When the answer is posted back, the agent runs again with it and its routes follow the answer.
  • Phone-call platforms (2.4.508). ElevenLabs Agents, Vapi, Retell and Bland can be members of the team: the platform makes the call and the outcome comes back by webhook. See Phone-call platforms.
  • New models (2.4.508), at the vendors' prices: gpt-6.1-terra, kimi-k3.1-pro, kimi-k3.1-pro-highspeed, gemini-omni-1.2-flash, and the image models gpt-image-2.6-flare, gpt-image-2.6-sunburst and gemini-nano-banana-2.1 (also gpt-image-2, gpt-image-1.5 and gpt-image-1-mini). Image models are billed by kind of token (text, thinking, image in, image out) from the vendor's own counts.
  • Playground (2.4.508). A person's seat can be tried with plain text; the text is taken as the message.
  • A Service name on custom records (2.4.509). See Custom connections.
  • Open APIs need no sign-in (2.4.509). An API tool whose switched-on endpoints are open to anyone is complete with only its address, and no warning says the sign-in is missing. See API Tools.

Upgrading to 2.4.498

Nothing to change in your project. Install 2.4.509: 2.4.502 fixed a sign-in bug in 2.4.498, and new create-leafmesh projects need 2.4.509. What's new:

  • Works behind company networks. A mesh behind a company proxy that re-signs web traffic now checks its licence through the same proxy and trusts your company's certificate. Before, it signed in but could not start.
  • Revoking is fast. Revoking a mesh in Studio stops it taking new work within minutes, not up to a day later.
  • No wasted spend on a two-agent hand-off. When an agent sends work to another that answers back, the answer is not bounced back again. A setup that would loop (a route with no condition to an agent that answers back) is flagged when the agency loads, with the fix.
  • Clear failures. A failed agent is reported to the system that sent the request as failed, with the reason, instead of a generic server error.
  • Projects with no configuration file. Custom agent code can be registered before start, and a team's configuration can be loaded once without ever being overwritten by a re-run: leafmesh config import --if-empty. This is what create-leafmesh now does.

Upgrading to 2.4.486

Check this before you upgrade:

  • Vault records keep sign-in only. A plain (not secret) query or body row on a record is refused on save, and the message names the page it belongs on. A key may still be sent as a query or body value, as a secret row, and an API tools record's plain body rows (such as client_id or username) stay. A plain query or body row saved before 2.4.486 is no longer sent; the start logs name each one (never its value). Move those values to the page that owns them, for example a webhook's or an API's query values.

New:

  • notify on any agent posts its output to a webhook when it hands its work on, or fails. See Tell your systems when work is done.
  • Tools → Webhooks: a webhook made once, used by an LLM agent through api_tools: [name] or by notify. See API Tools → Webhooks.
  • model_connection picks the vault record an LLM agent's model calls sign in with. See Agent Configuration.
  • Several accounts of one service: each block names its record. See Connections & the Infra Page.
  • Reaching a person is one choice in Studio that writes the existing YAML shapes; there is no new key and existing configs load unchanged. See Human Agents.
  • API entries and models you run on your own server take fixed query values on their page (for example api-version). Keys never go there.
  • Fixed: a human seat with nothing else set used to fail on its first question ("No human interface handler set"). From 2.4.486 it is an Inbox seat; a seat is api only while your code registers a handler with register_human_agent, and start-up names any seat it moves to the Inbox.

Upgrading to 2.4.485

Check these before you upgrade:

  • Connector environment variables are no longer read. An external agent's address, key and ids come only from its vault record (made under Infrastructure → External agents, or Infrastructure → Integrations for Zapier, n8n, Composio and MCP), named with connection:. Model keys and the host's cloud identity stay in .env.
  • The code helpers take a record. n8n(connection="<record>"), zapier("<action from your Zapier MCP server>", connection="<record>") and composio("ACTION", connection="<record>"). An address or key passed in code is refused.
  • tool_categories: ["integration"] is refused. The category's four tools (zapier_action, mcp_call, composio_action, n8n_workflow) were removed; declare the agent's zapier:, mcp:, composio: or n8n: block instead. Other categories are unchanged.
  • A local model's timeout is set only as mesh.local.timeout, no longer from the environment.
  • A human seat can't have scaling.copies. It is refused at load, with an error naming the seat (it would ask the same person the same thing several times). scaling.runs.max is fine.
  • The generic zapier_action, mcp_call, composio_action and n8n_workflow tools are removed. An agent listing one in tools: is refused at load, and the error names the block to use instead: zapier:, mcp:, composio: or n8n:, each picking a vault record.

New:

  • leafmesh agent host-rights changes a claude_agent's host permissions on the host and saves them as a new version; the API never changes them:

    leafmesh agent host-rights <agent> [--cwd DIR] [--allowed-tools a,b] [--permission-mode M] [--clear FIELD] [--yes]

    --permission-mode accepts default, acceptEdits, plan or bypassPermissions; --clear takes cwd, allowed_tools or permission_mode and can be repeated.

  • leafmesh vault rotate-key takes the store from .env; --config is optional and only names the agency.

  • Studio's schema says how each setting applies: every row of /api/schema/mesh and /api/schema/agent has applies — live, reload (automatic, in place, within seconds; a seat's channels count as reload) or process_restart (only evolution_api). restart_required stays, and is true only when applies is process_restart.

Upgrading to 2.4.484

Check this before you upgrade:

  • An agent's parallel settings are one scaling: block. The old keys parallel, max_concurrent, instances and instances_handoff are refused at load — an error, not a warning — and the error shows the scaling: lines to write instead:
BeforeAfter
instances: N + instances_handoff: Hscaling: {copies: {mode: fixed, count: N, handoff: H}}
max_concurrent: Nscaling: {runs: {max: N}} — now counted across all pods (it used to count per pod)
paralleldrop it

runs.max unset means no cap; jobs over the cap wait their turn. New: copies.mode: auto hands out the work item by item, from an input field (work) or the agent's own claim tool (claim_tool), and starts a copy only when there is an item for it, up to max (default 10) — 6 items with max: 10 start 6 copies, never 10. A copy takes the next item with the built-in next_work_item tool. See Agent Configuration → scaling.

New:

  • Saved settings apply without a restart. The Manager and its summarizer take their settings live (rules, timing, routing, model, what it listens to). A change that still needs a reload makes the agency reload itself in place within seconds: brokers, self_healing.enabled, api.cors_origins, lease timing, architecture, auto_discover, consumer_inflight_max, and switching the Manager on or off. Every pod applies a saved change the same way, within about 15 seconds. Only evolution_api's host, port and enabled need a process restart.
  • Studio's Infrastructure page uses these sections: Messaging, Workspace, Models, Cloud access, Knowledge, Integrations, External agents, Brokers & queues, Notifiers, Rooms, Agent identities and Datastores. MCP servers are under Infrastructure → Integrations → MCP (on 2.4.482 they show under External agents). The Tools page still exists (Tools → APIs, MCP servers, Zapier, Composio, n8n): it sets up the server or tool and picks its record; the record itself is made on the Infrastructure page. See Connections & the Infra Page.

Upgrading to 2.4.482

Check these before you upgrade.

  • The store is set only in .env. persistence: and top-level redis: blocks are no longer read; boot logs "persistence block is no longer read" and the block is ignored. Move the values to .env (LEAFMESH_STORE, REDIS_URL or REDIS_HOST / REDIS_PORT / REDIS_PASSWORD ..., or DATABASE_URL / the POSTGRES_* variables) before upgrading — see Persistence. auto_storage, decode_responses and the Postgres pool's idle lifetime are no longer settings; the mesh fixes them. Studio's Infrastructure → Datastores shows whether the store is reachable, its latency, the server, the settings in force and which .env names set them — never the address or password.
  • The four Manager rule sets sit directly under manager:. human_input_rules, timeout_rules, workflow_pause_rules and human_response_rules no longer go under manager.coordination_rules:. A file that still nests them is moved at load, with a warning. coordination_rules stays for its other keys (max_call_depth, agent_rules, reflection_budget — default 2 — and so on).
  • mesh.call_timeout is now timeouts.mesh_call_default_timeout_s (default 300 seconds; some older pages said 30). An old mesh.call_timeout is moved at load, with a warning.

New:

  • A new agency's YAML lists every setting with its default, including the timeouts, scheduler, self_healing, runtime, limits and connectors blocks — see Runtime Behaviour Blocks. Corrected defaults: scheduler.followup_tick_s is 2, manager.max_tokens 4000, manager.chain_completion_timeout 1800 seconds, manager.domain "generic", mesh.reply_stream false.
  • A blank agency starts quietly. With no agents yet, there are no manager, escalation or "no agents" warnings until you add one.
  • A missing provider key gets a plain message: "model 'X' needs the <provider> provider, which has no key here — add one on Infrastructure → Models, then try again".
  • Trace redaction is on by default (since 2.4.480): security.telemetry_redact_pii defaults to true, so your input and output content in a trace is replaced whole with <redacted bytes:N>. Names, models, tokens, cost, status, errors and timings stay visible. It is not per-word PII detection. Set it to false to keep content readable; credentials are always masked either way.
  • null resets a setting. Sending a setting as null in a config save puts it back to its default.

Upgrading to 2.4.481

Check these before you upgrade.

  • The configuration lives in the agency's store. It is kept in your Redis or Postgres, not in a file. Every Studio save is a new version: Studio's versions page lists each save with a diff, and make default restores one. Every pod runs the latest. A project now holds only its custom code and its .env: LeafMesh.from_store() starts the agency named by LEAFMESH_AGENCY_NAME from the store set in .env, and an empty store starts a blank agency that you build in Studio. An existing config.yaml is imported once, then not read; the boot log says so. From then on, edit the configuration in Studio.
  • Credentials and addresses live only in the vault. Keys, tokens, passwords, client ids, addresses (URLs, endpoints, hosts) and header or query rows are entered only on Studio's Infrastructure page. A block picks its record with connection: <name> (a zapier, composio or n8n tool block: vault_connection). An inline value — including a ${ENV:default} reference — is refused at load, and the error names the field and the record to create. A connection name may still come from the environment (connection: "${SLACK_CONNECTION:slack-workspace}"). This covers human seats' webhook_config, manager.escalation targets, brokers, channels, mcp rows, external agents' connector_config, mesh.bedrock / vertex / foundry / local, and knowledge stores and embeddings. Model keys in .env still work; from 2.4.492 a key also in the vault uses the vault's.
  • A missing record never stops boot. If a connection: names a record that does not exist yet, the agent that needs it is switched off with the reason, and works as soon as the record exists — no restart.

New:

  • The simplest human seat needs no webhook. A seat with human_interface: default is an Inbox seat (no webhook or channel needed). Escalating to it is targets: [{type: human_agent, agent: <seat>}]. A seat with nothing set (which means api) needs your own code to answer it, otherwise it fails on its first question.
  • Licence limits block new sessions, not running work. A plan at its limit, or an unpaid invoice, blocks new sessions (HTTP 402); runs in flight carry on.
  • Traces hide LeafCraft's own prompts. LeafCraft's platform prompts show as <platform_prompt:N chars> and raw Manager replies as <elided:N chars>. This is always on and separate from the redaction setting below.

Upgrading to 2.4.450 – 2.4.460

Nothing to change in your config, except one thing in 2.4.460 below. New:

  • Versions of everything that shapes an agent — its settings, mesh settings, playground changes, skills, API tools, Tools-page sources, knowledge, connections and models. Every run records the versions it used and what changed since the agent's previous run; what an agent learned is told what has changed since.
  • Save as draft or as default; make any version the default; every version is kept, paged and searchable.
  • Try a version once before making it the default: one run of one agent, everything else on the default, nothing handed on or learned.
  • Budgets: lean mode when an agent spends ahead of its monthly pace, and a learned ceiling per task.
  • Your Own Models: add a model that runs on your own server, by its interface (vLLM, Ollama, SGLang…), with its address and sign-in on a vault connection. It appears in the model lists, and its calls go where you said. A model whose provider isn't set up now fails with a message naming the provider, instead of going to another provider.
  • 2.4.460: a model can no longer be added "on a provider". A provider's models are already listed. An older entry of that kind is skipped at start, with a warning.
  • Pricing is its own page: price records, tagged to models.
  • A status page shows whether every model, tool and connection the mesh uses is working, from real calls and Tests.
  • Try side by side: the same task on the default and the candidate, with time, tokens, cost and tool calls for each, and every trial kept.
  • A multi-file skill shows one new version the first time it is read after the upgrade (its files are now versioned by what is in them).

Upgrading to 2.4.419 – 2.4.449

Nothing to change in your config. New:

  • API Tools — upload an OpenAPI / Swagger file once and name it on an agent with api_tools: [name]. You switch each endpoint on or off; an endpoint that is off is never used, and the agent says so when a request needs it.
  • One Tools page for APIs, MCP servers, Zapier, Composio and n8n. Add a source once and name it on an agent: mcp: [{server: github}], zapier: [{account: main}]. Rows written out in full keep working.
  • More models: GPT-6 and GPT-5.6, Claude 5.5, Gemini 4 Argon / 3.8 / 3.6 / 3.5 Flash-Lite, and direct connections to OpenRouter, Groq, Cerebras, Kimi, Qwen, GLM, MiniMax and more — see LLM Providers. The Infrastructure page's Test checks every model key.
  • The agent closes its ticket in the same model call as its answer, and is first asked to finish checklist steps it left open — see Shared Board.
  • At the tool-call limit every model answers with what it found instead of failing.
  • Traces show each model loop with its own tokens and cost, and the tools it called inside it; a loop with a failed tool is marked.
  • Gemini 2.5 Pro always thinks: give it max_tokens of 2000–4000 or more.

Upgrading to 2.4.387 – 2.4.418

Check these before you upgrade.

New in 2.4.401 – 2.4.418 (nothing to change in your config):

  • A new external agent, framework: lindy — see External Frameworks.
  • finish_task takes done to tick the last checklist steps, and a request closed as done reads done on the board.
  • Every model call is traced once with its own tokens and cost, so dashboard totals match the spend; the mesh's own background work (lesson passes, experience judging) is traced as the Manager's, never as an agent of its own.
  • A model that ran its tools but wrote no answer is asked once more; Gemini is asked in the conversation itself.
  • Your environment token is never written into a trace; traces name the environment by a fingerprint, and every finished step shows whether it succeeded, what it was given and what it found. A tool call in a trace shows exactly what the model sent and what it got back.
  • Models read structured tool results as JSON.

thinking: true no longer runs code. It gives the agent three text tools only: chain_of_thought, metacognitive_reflection and apply_edits. Code runs in a contained sandbox, behind its own switch. An agent that ran code under thinking needs sandbox: true — see LLM Agents → Running Code.

agents: analyst: sandbox: true # no network, 30s, 5s CPU, 256 MiB, 64 MiB workspace

Tools are for LLM agents. Tool blocks (zapier, composio, n8n, mcp), the playbook, follow-ups and their limits, image output, eager skills and the sandbox are refused at load on human, external and programmatic agents. Remove them from those agents.

Voiceflow and Cognigy are removed. An agent with framework: voiceflow or framework: cognigy is refused at load.

custom_endpoint and custom_headers moved to the mesh. Set the model server once, in mesh.local.endpoint and mesh.local.headers — see LLM Providers. On an agent they are warned about and have no effect.

The board is the mesh's. An agent's own kanban: block is warned about, changes nothing, and is dropped on the next save. The top-level kanban: block is the only board setting; its job may hold letters, digits and _ . : - only. See Shared Board.

Saving from Studio or PATCH. A map field sent as {} is emptied, and a mesh setting sent as null returns to its default.

Also new, with nothing to change on upgrade: Stop and Resume for the whole agency (REST Endpoints), six managed agent platforms, the A2A platforms as their own services, Mistral Agents, Letta and Glean Agents, a monthly budget on any external agent (Per-Agent Budgets), custom connections built as forms (Connections & the Infra Page), the published contract at GET /api/schema/contract, and tool calls that never end as an empty success.

Upgrading to 2.4.382 – 2.4.386

Check these before you upgrade. Each one either refuses to load (and says why, with the line) or changes what a run does.

An agent that reports success: false has failed. The run is treated as failed for routing, the board and the client. Put a business "no" — a declined refund, an ineligible applicant — in your yields, not in success.

Reaching max_tool_calls_per_message is a warning, not a failure. The agent is told its tool calls are used up and answers with what it has; the output carries _warnings. Every call the model makes counts; the ADK's own memory, board and playbook calls do not.

Approval is routing. require_human_confirmation, confirmation_seat and human_escalation_triggers are removed. One that is set on is refused at load; one that is off or empty is dropped. Route the work to a human agent with can_call and a condition instead — see HITL Workflows.

can_call: - agent: finance_lead # a human agent condition: "needs_approval == true"

self_healing is a declared block. Detection is on and actions are off by default. The old fields detection_interval, max_recovery_attempts and recovery_strategies are refused — replace them with the fields in Self-Healing Networks.

self_healing: actions_enabled: true # only if you want restarts and backups cooldown_s: 600 max_actions_per_hour: 3

Environment switches that turned a defence off are no longer read. The defence is always on. Remove them from your environment (boot warns about the webhook and mode-guard ones while they are still set):

No longer readWhat happens now
LEAFMESH_DISABLE_PROMPT_GUARDRAILThe prompt guardrail always runs.
LEAFMESH_WEBHOOK_ALLOW_UNSIGNEDInbound webhooks are always verified; with no signing secret, signed routes refuse.
LEAFMESH_WEBHOOK_ALLOW_LEGACY_HMACSigned webhooks always need X-LeafMesh-Timestamp and X-LeafMesh-Nonce.
LEAFMESH_TEAMS_ALLOW_UNVERIFIEDTeams messages are always verified.
LEAFMESH_EMAIL_ALLOW_UNVERIFIEDInbound email is always verified.
LEAFMESH_DISABLE_MODE_GUARDThe event-bus mode guard always runs: run every process in the same workers mode, or give one its own datastore namespace.

Redacting personal data from traces is now declared config: security.telemetry_redact_pii in config.yaml. The old environment variable for it still works in this release, with a warning, but the config value wins and the variable will be removed.

thinking_budget is read as reasoning_budget, and communication_type: execute as chain (dual on a human agent); both load with a warning.

External agents and budgets. A monthly budget on an external agent now stops it when spent. (In 2.4.382 – 2.4.394 a budget on an external agent whose connector reports no spend was refused at load; from 2.4.395 every external agent can have one, measured or estimated.) See Per-Agent Budgets.

New in 2.4.385 – 2.4.386 (external agents)

Zapier runs through Zapier MCP. Zapier retired AI Actions, the REST API an api_key reached. A Zapier agent with only an api_key now fails with that explanation: set an MCP key (mcp_key). prefer_mcp and instructions are no longer read.

send_fields limits everything that goes. With send_fields set, the conversation history, chain history and rerun note are sent only when you list them.

mode: callback is n8n and Zapier only. On any other framework it is refused at load. (From 2.4.508 this setting is after_handoff; see Upgrading to 2.4.509.)

A claude_agent's cwd, allowed_tools and permission_mode are set in the configuration only. A write through the API that changes them is refused.

PATCH /api/yaml/agents/{name} merges blocks one level deep. Sending part of external_policy or connector_config no longer drops the rest; use PUT to replace the agent whole.

Standard cron forms load. 0 9 * * 7, 6-7, 5#3 and 5L were refused at load though the scheduler runs them; they now load.

Also new, with nothing to change on upgrade: request_form (your own fields on every request), vault-held credentials in connector_config resolved on every call (from 2.4.481 through connection: records), A2A 1.0 alongside 0.3, the 2.x mcp package, the steps an external system ran shown in the trace, feed and lessons, conversations that carry on across calls, live config changes without a restart, and cancelling a session stopping a running external call.

How the mesh signs in (2.4.497)

From 2.4.497 each mesh signs in to LeafCraft with its own identity, in one of two ways:

  • Key pair: a key the mesh makes and keeps in its own vault. There is one per environment, shared by every instance running in that environment.
  • Workload identity: on Azure, the machine's own identity instead of a key. Other clouds will follow.

From 2.4.538, connect a new environment once with your licence key and environment token (leafmesh auth register asks for the key); it is not stored, in files, the vault, logs or the cache. After that the mesh starts on its own sign-in and uses short-lived tokens that it renews itself. LEAFMESH_ENV_TOKEN must be the real token Studio showed.

Without the command, you can put LEAFMESH_LICENSE_KEY=… in .env for that first start only. The mesh then says: "This environment is signed in: LEAFMESH_LICENSE_KEY is no longer needed here and can be removed." Delete the line.

On several servers (Docker or Kubernetes), every server gets the same LEAFMESH_ENV_TOKEN, LEAFMESH_VAULT_KEY, store and LEAFMESH_AGENCY_NAME, and no server holds the licence key. Run the sign-in once as a one-off command with those settings, for example docker run -it --env-file .env my-mesh-image leafmesh auth register; every server then reads the saved sign-in from the shared store. Each mesh is listed in Studio and can be revoked on its own. Older versions signed in with a key built into the ADK; that ends on 5 December 2026.

A new mesh works at once, and your organisation's admins are emailed about each one. If your organisation turns on approval (off by default), an admin approves the new environment in Studio (Keys › Mesh access › Pending approvals): one approval per environment, not per server. Until then the mesh waits with a message saying so; once it is approved, start it again.

After the first start:

What happensLicence key needed?What to do
Restart, new server, scaling outNoNothing
The licence key is replaced in StudioNoNothing; running meshes keep working
The environment token is replaced in StudioNoKeep the old token in running servers; it names their data
The sign-in is revoked in StudioYes, onceRun leafmesh auth register again
The store is wiped or the vault key is lostYes, onceConnect again, as on the first start

Who reaches a mesh, and how:

  • People reach it from Studio, each with their own short-lived pass. Anyone without edit rights in that agency can only look.
  • Other systems, such as your own application, scripts and automation tools, use your organisation's API key. This carries on after 5 December 2026.

From 5 December 2026:

  • Meshes must run 2.4.497 or later.
  • Organisation API keys, agency tokens and environment tokens are shown once, when they are created or rotated, and only as a hint after that. Copy the licence key and environment token when you create the agency: the environment token goes in .env, and the licence key is asked for once, at the first start.

Operators can check and manage the key from the command line. None of these commands ever prints a key.

CommandWhat it does
leafmesh auth statusShows which sign-in is in use, the key's fingerprint, and whether it is registered. --check signs in now and reports the result.
leafmesh auth registerConnects this environment: asks for the licence key (not shown, not kept), registers the mesh's own key with LeafCraft (makes one if there is none), and saves the sign-in in the vault.
leafmesh auth rotateMakes a new key, registers it, switches to it and revokes the old one. If your organisation requires approval, the new key waits until an admin approves it in Studio (Keys › Mesh access). Until then the current key stays in use; running rotate again after approval finishes the switch.

License Activation

When an environment first connects, LeafMesh checks your licence key with the LeafCraft auth backend. If the key is invalid or expired, leafmesh auth register stops with LeafMeshLicenseError. Every later start checks the mesh's own sign-in instead; if the environment has not connected yet, or its sign-in was revoked, the mesh raises LeafMeshLicenseError and refuses to boot.

From 2.4.481, when your plan is at its limit or an invoice is unpaid, new sessions are refused with HTTP 402; runs already in flight carry on.

import asyncio from leafmesh import LeafMesh async def main(): leafmesh = LeafMesh.from_store() await leafmesh.start() # License validated here print("LeafMesh started successfully!") await leafmesh.stop() asyncio.run(main())

License types:

  • Starter — Free tier with basic features
  • Pro — Extended features and retention
  • Enterprise — Full features, dedicated support

Contact info@leafcraft.ai for license inquiries.

Verification

After installation, verify everything works:

import asyncio from leafmesh import LeafMesh async def verify(): leafmesh = LeafMesh.from_store() try: await leafmesh.start() print("LeafMesh started successfully!") print(f"API docs: http://127.0.0.1:18820/docs") finally: await leafmesh.stop() asyncio.run(verify())

Troubleshooting

"This server's clock is N s ahead"

From 2.4.498 a server whose clock is wrong is told so plainly instead of failing sign-in with a confusing error. Keep the server's clock in sync (NTP) and start the mesh again.

"No vault key"

From 2.4.507 the mesh never makes a vault key. Add LEAFMESH_VAULT_KEY to .env (32 random bytes, URL-safe base64) and start again. Use the same key on every instance; a different key opens a new, empty vault.

Signed webhooks answer 503

LEAFMESH_WEBHOOK_SECRET is not set. From 2.4.507 the mesh does not derive one. Add it to .env and start again.

This environment is not signed in yet

LeafMeshLicenseError: This environment is not signed in yet …
  • Run leafmesh auth register once and give the licence key (see How the mesh signs in, above)
  • On several servers, check every server has the same LEAFMESH_ENV_TOKEN, LEAFMESH_VAULT_KEY and store; a server with a different one cannot find the sign-in
  • If your organisation requires approval, an admin approves it in Studio (Keys › Mesh access)
  • Check that your machine has outbound internet access to LeafCraft

New Sessions Refused with 402

Your plan is at its limit or an invoice is unpaid. New sessions are blocked until that is resolved; runs already in flight carry on. Contact info@leafcraft.ai.

Redis Connection Failed

redis-cli ping # Should return "PONG"

Import Errors

pip show leafmesh # Verify installation pip install --upgrade leafmesh # Upgrade to latest

Next Steps

  1. Quick Start Guide — Build your first mesh in 5 minutes
  2. Architecture Guide — How the control plane works
  3. Agent Development — Create custom agents
  4. Examples — Real-world implementations

LeafMesh — YAML-native multi-agent orchestration platform

Last updated: 11/21/2026