Cloud Deploy — leafmesh-deploy

leafmesh-deploy ships with create-leafmesh and deploys a scaffolded project to AWS, Azure, or GCP with one command — no Terraform, no YAML pipelines.

cd my-project          # any scaffolded LeafMesh project
leafmesh-deploy --plan      # show what will be created — no API calls
leafmesh-deploy --apply     # build image, push, create services
leafmesh-deploy --destroy   # tear everything down

What It Creates

Provider	Compute	Secrets	Registry
`aws` (default)	App Runner	Secrets Manager	ECR
`azure`	Container Apps	Key Vault	ACR
`gcp`	Cloud Run	Secret Manager	Artifact Registry

The deployer builds your project's Dockerfile, pushes the image, stores your .env config as a cloud secret, and stands up a managed container service wired to read those secrets at runtime. The result is a public HTTPS endpoint running your mesh.

Prerequisites

Docker running locally (the image is built from your project's Dockerfile)
Cloud credentials already on the box — zero interactive prompts:
- AWS: aws configure, env vars, or an IAM role
- Azure: az login
- GCP: gcloud auth application-default login
Provider SDKs — AWS support (boto3) is included. For the others:

# Azure
pip install azure-identity azure-mgmt-resource azure-mgmt-containerregistry \
            azure-mgmt-keyvault azure-mgmt-appcontainers azure-keyvault-secrets

# GCP
pip install google-auth google-cloud-artifact-registry \
            google-cloud-secret-manager google-cloud-run google-cloud-iam

Configuration: `.env.deploy`

The deployer reads .env.deploy (preferred) or .env from the project root. Required keys — plan fails fast with a clear list if any are missing:

LEAFMESH_LICENSE_KEY=XXXX-XXXX-...
LEAFMESH_ENV_TOKEN=...            # the environment token Studio showed (required from 2.4.507)
OPENAI_API_KEY=sk-...
REDIS_URL=redis://your-redis-host:6379
# The agency's name in the store (LeafMesh.from_store() starts this agency)
LEAFMESH_AGENCY_NAME=my-agency
# The vault key: required (every instance must use the same key; the mesh never makes one, 2.4.507)
LEAFMESH_VAULT_KEY=...

# Optional
ANTHROPIC_API_KEY=sk-ant-...
# The webhook signing secret: carried to the cloud when set. Without it the
# mesh starts, but signed webhooks answer 503 (2.4.507)
LEAFMESH_WEBHOOK_SECRET=...

The deploy carries the team the project was created from. Before the first start it loads the team into the store, only if the store is empty (leafmesh config import --if-empty), so it never overwrites a configuration that is already there.

Secret values are never echoed in full — plan output shows only the last 4 characters.

AWS (default)

leafmesh-deploy --plan                      # us-east-1 by default
leafmesh-deploy --region eu-west-1 --apply

Creates an ECR repository, pushes the image, stores the config bundle in Secrets Manager, and deploys an App Runner service with two IAM roles: an access role (image pull) and an instance role (runtime secret reads).

Azure

leafmesh-deploy --provider azure \
  --subscription-id <sub-id> \
  --resource-group leafmesh-prod \
  --location eastus \
  --apply

--subscription-id and --resource-group are required on the first apply; afterwards they're read from the state file. Creates ACR, a Key Vault with your config, and a Container App with a managed identity granted Key Vault read access.

GCP

leafmesh-deploy --provider gcp --project my-gcp-project --apply

--project is required on the first apply. Default region is us-central1. Note: GCP region names have no hyphen before the digit — us-east1, not us-east-1. Creates an Artifact Registry repository, Secret Manager secrets, a dedicated runtime service account, and a public Cloud Run service.

Asking Your Cloud Admin for Access

If your account can't create these resources, print the exact policy the deployer needs and hand it over:

leafmesh-deploy --print-policy                    # AWS IAM policy JSON
leafmesh-deploy --print-policy --provider azure   # Azure RBAC definition
leafmesh-deploy --print-policy --provider gcp     # GCP role definition

The policies are scoped to leafmesh-* resource names — they don't grant blanket access to your cloud account.

State

Everything created is recorded in .leafmesh-deploy/<provider>.json inside the project (the scaffolder already gitignores it). Re-running --apply updates in place; --destroy reverses exactly what the state file records. Region, subscription, and project settings recorded in state win on re-runs, so you only pass them once.

If a destroy partially fails, the state file keeps the resources that weren't deleted and the command exits non-zero — re-run --destroy to finish, and never assume cleanup succeeded on a failed run.

Exit Codes

Code	Meaning
0	Success
2	Configuration error (missing env keys, missing flags, bad project dir)
6	Partial destroy — some resources remain; state preserved; re-run
130	Cancelled (Ctrl-C) — never treat an interrupted apply as success

Troubleshooting

"MISSING env keys" — add the listed keys to .env.deploy or .env.

"Docker not found in PATH" — install/start Docker Desktop; the image build happens locally.

Credential errors — the deployer never prompts; run the provider's login (aws configure / az login / gcloud auth application-default login) first.

"State file is corrupted" — the deployer refuses to run rather than treat corruption as a fresh start (your cloud resources may still exist). Inspect or restore .leafmesh-deploy/<provider>.json before re-running.

Scaling Past One Instance

The managed services this deploys (App Runner, Container Apps) scale by instance count. To run more than one instance safely, add two settings to your .env.deploy:

LEAFMESH_WORKERS_MODE=1
REDIS_URL=redis://your-shared-managed-redis:6379

LEAFMESH_WORKERS_MODE=1 is what makes a multi-instance fleet safe: events are handled exactly once across instances, the scheduler and listeners run on a single instance at a time, session state is locked across instances, and a paused human-in-the-loop wait resumes on another instance if one restarts. All instances must share one managed Redis. The agency's configuration lives in that store, so every instance runs the latest saved version. With a single instance you can leave it off. See Scaling.

Next Steps

Production Setup — hardening checklist
Docker Deployment — self-managed container deploys
Kubernetes Deployment — for existing clusters
Templates Overview — what you just deployed

LeafMesh — YAML-native multi-agent orchestration platform