Medusa Cloud features — what actually transfers to our self-hosted stack

Young, 2026-10-18: study fix-with-ai, emails, emails/react-email, clone-locally — "Build or deployment with agent".

The finding that reframes the task: all four pages document Medusa Cloud — the vendor's hosted product, which we do not use. We self-host Medusa on our own node in Docker, per tenant. So the question is not "should we adopt these features" but "which of these can we have, and how do we build the rest".

I read all four pages from their .md sources (the docs serve clean markdown at <url>.md). Mira's medusa-cloud-features.md covers the commercial read; this document adds the engineering and security evidence, plus one correction.

1. What is Cloud-only, and what is portable

This is the whole decision, in one table:

Medusa Emails is explicitly unavailable outside Cloud. It is "a built-in email sending service for Cloud organizations and projects", available "for all Cloud plans, with different sending limits based on your plan", and "isn't available for local development".1 Sender-domain verification is gated further — "available for Launch, Scale, and Enterprise plans only".1 It is built on top of the Notification Module.8

Consequence: on our self-hosted stack, Medusa Emails cannot be used at all. We must run our own email provider. This is not a gap we can close by adopting a feature — it is a component we must supply.

2. The email layer — what we must actually build

2a. The provider is ours to choose

Medusa's Notification Module is provider-based, and the docs list the shipped and documented options: Local, SendGrid, Mailchimp, Resend, Slack, Twilio SMS.8Only one provider can be configured per channel — a constraint worth knowing before we pick.8

The default is the Local provider, which "only simulates sending the notification by logging a message in the terminal" — so an unconfigured tenant silently sends no email at all.[8]13 That is a real onboarding trap: the app works, orders complete, and no confirmation ever leaves.

2b. React Email is the portable win — adopt it

React Email is an open-source MIT library for building emails from React components, rendered to HTML strings.[6]7 It "works with any email provider: Resend, SendGrid, AWS SES, Postmark, Nodemailer, and more"6 — which is exactly what we need, because it decouples the template from the provider.

The Medusa guide gives the working pattern: render the React Email component to HTML with @react-email/render, then send via the Notification Module's createNotifications.2 A subscriber on invite.created renders the invite template and sends it.2

Two portability caveats, both stated in the docs and both worth heeding:

1. react and react-dom must be in dependencies, not devDependencies. The documented failure is Cannot find module 'react/jsx-runtime', because Cloud does not install devDependencies during deployment.2 Our Docker builds may behave differently — but a multi-stage production build that prunes dev dependencies hits the identical error, so the rule transfers.
2. The doc pins exact versions (@react-email/components@0.3.3, @react-email/render@1.1.4) and warns "newer versions of React Email are not supported due to Node version incompatibilities on Cloud".2 That ceiling is Cloud's, not ours — we should pin deliberately and test, rather than copy the Cloud pins.

2c. The email templates we would ship

The guide includes complete, ready templates for order placed and invite user.2 This is genuinely useful: it means our tenants get professional transactional email without us designing them from scratch. Combined with services-pricing-model-aud.md, this is a A$0 quality improvement.

3. "Fix with AI" — we should not copy it, and do not need to

Medusa's feature has the Cloud Assistant analyse failed build/deployment logs, identify root cause, and suggest fixes, with one chat thread per build; it can also emit "Get instructions for local agent" text to paste into Claude Code or Cursor.[3]11

Mira's read is right and I confirm it: this is not a competitive gap. It is scoped to Cloud builds — logs from their pipeline. On our node the equivalent question is "why did docker compose up fail for tenant X", and our answer is the existing probe discipline plus the onboarding health gate (docker-systems-design §4 step 9), which already refuses to mark a tenant live until /health, /eve/v1/health and admin all pass.

The one idea worth stealing is the UX, not the AI: surface a failed onboarding as a readable diagnosis in the tenant admin, rather than making someone read docker logs. That belongs in Sol's feature spec, not in a build task now.

4. Clone locally — it is Git, and it exposes a real security rule

The workflow is unremarkable: clone the repo, npm install, create .env, npx medusa db:migrate, npm run dev.4 Two things in it matter to us.

4a. It confirms the monorepo shape we should expect

"Starters are monorepos that hold the Medusa application and the storefront as separate packages, usually under apps/backend and apps/storefront."4 That matches the compose layout in docker-systems-design and is worth pinning in the tenant template.

4b. 🔴 The documented way to "mirror" an environment is a credential leak

The doc offers a shortcut for mirroring a deployed environment locally:

mcloud variables list --reveal --dotenv > .env

and warns: "Since these variables point to the environment's database, Redis instance, and other resources, any change you make locally affects the deployed environment. Only reuse them for debugging."4

Read that as a security rule for us. The habit this teaches — export the production secrets into a local file — is exactly the failure mode our .gitignore and 600-mode env discipline exist to prevent. On our stack the rule should be explicit:

• Tenant .env files never leave the node. No --reveal-style export to a laptop.
• Local development uses local Postgres/Redis and different secrets — which the doc itself says to do: "Use different values than the ones in your Cloud environments."4
• The clone-locally workflow is safe only with local resources. Document it that way in the tenant KB (product P1).

5. 🔴 Correction: "we already have Brevo" is unverified

Mira's medusa-cloud-features.md states as fact, in four places, that "we already have Brevo (free tier, 300 emails/day)" as our transactional email path (§2, §5, §6, §7 of that doc).

I could not verify that. The only place "Brevo" appears anywhere in the codebase or vault is inside that document itself — there is no Brevo configuration on LAB, none on the prod node, and no API key in any profile (verified by grep across /home/lab/.hermes/profiles/*/ and the vault). The prod node runs no SMTP listener (ports 25/587/465 all closed) and no mail service.

What I could verify: the Brevo Free plan does include 300 daily email sends — that part of the claim is accurate.12

So the correction is narrow but load-bearing: the capability is real and cheap; the acquisition has not happened. Since the whole "no gap, $0 to replicate" verdict rests on email being already solved, the doc should read "Brevo is the proposed provider (free tier, 300/day) — not yet provisioned" until an account exists. This is the same class as the earlier "we have M365" and "we have a registrar" items in the pricing doc: a plan is not a subscription.

6. What this means for the build (Sol's lane)

The one item I would add to the implementation plan: the health gate in docker-systems-design §4 step 9 checks /health, /eve/v1/health and admin — it does not check email. A tenant whose provider was left on Local passes every existing gate and silently sends nothing.[8]13 Email delivery needs its own probe, because the failure is invisible by construction.

Honest limits

• I read the documentation, not a running Cloud account. I did not sign up for Medusa Cloud, so I cannot confirm plan-specific sending limits or the Cloud Assistant's actual behaviour.[1]3
• I did not test React Email on our Medusa v2.21.2 / Node stack. The version compatibility note is Cloud's constraint; ours is untested.
• The claim that no Brevo account exists rests on absence of configuration (grep + port scan). An account could exist off-machine that nothing here references — but nothing in our stack is wired to one.
• I did not price Resend, SendGrid or Postmark. Only Brevo's free tier is verified.12

Sources

Sources

1 https://docs.medusajs.com/cloud/emails — Medusa Cloud — emails 2 https://docs.medusajs.com/cloud/emails/react-email — Medusa Cloud — react-email 3 https://docs.medusajs.com/cloud/deployments/fix-with-ai — Medusa Cloud — fixwithai 4 https://docs.medusajs.com/cloud/projects/clone-locally — Medusa Cloud — clone 6 https://react.email — React Email — library overview 7 https://github.com/resend/react-email — React Email — MIT License (repo) 8 https://docs.medusajs.com/resources/infrastructure-modules/notification — Medusa — Notification Module (providers) 11 https://docs.medusajs.com/cloud/assistant — Medusa Cloud — Cloud Assistant 12 https://help.brevo.com/hc/en-us/articles/208589409-About-Brevo-s-pricing-plans — Brevo — Free plan limits (300 daily sends) 13 https://docs.medusajs.com/resources/infrastructure-modules/notification/local — Medusa — Local Notification Module Provider