Medusa Cloud — Fix with AI, emails, React Email, project creation, clone locally

Young, 2026-10-18: study the four Medusa Cloud pages (Fix with AI, Emails, React Email, Clone Locally) and register them as a research doc. This doc sits beside medusa-templates-pos-payments-features.md and medusa-product-research.md in Docs/Projects/vhost/research/.

Scope note: we run Medusa self-hosted in Docker on our Oracle ARM node (per docker-systems-design.md). Medusa Cloud is the managed offering. The value here is what we can borrow (agent debugging, email patterns, React Email templates, project scaffolding) without taking on Cloud lock-in.

1. "Fix with AI" — agent debugging for builds and deployments

When a build or deployment fails on Medusa Cloud, the "Fix with AI" button appears on the deployment details page. The Cloud Assistant:

• Retrieves the relevant project data directly from Medusa Cloud and the connected GitHub repo
• Analyses build logs + runtime logs
• Identifies the root cause
• Provides actionable steps to resolve the issue
• Guides the developer through the fix

Availability: all plans, always-on for failed deployments.

Future roadmap: coding capabilities — build features using natural language directly from the Cloud dashboard.

What we can borrow:

• The pattern (log analysis → root cause → actionable steps) is exactly what our Heart agents (Ace/Alpha/Atlas) should do when a tenant deployment fails
• We can replicate this as a SolOS ops agent (Atlas lane) that tails docker compose logs and proposes fixes
• The Cloud CLI (mcloud logs) pattern of streaming logs to AI agents is reusable with our own CLI (docker compose logs -f)

What we must NOT use: Medusa Cloud's agent is Cloud-only. We run self-hosted.

2. Medusa Emails — built-in transactional email

Medusa Emails is a built-in email sending service for Cloud organizations and projects.

How it works

• Enabled by default for all Cloud projects with zero configuration
• Send transactional + marketing emails directly from the Medusa application
• No manual email infrastructure setup required
• Available for all Cloud plans (different sending limits per plan)
• Email activity tracking on the dashboard (delivery status, opens, etc.)

Requirements

• No other Notification Module Provider configured for the email channel (remove SendGrid, etc. to use Medusa Emails)
• Sender domain verification required for sending to users outside your organization (Launch/Scale/Enterprise plans only)

Sending emails

import { Modules } from "@medusajs/framework/utils"
const notificationModuleService = container.resolve(Modules.NOTIFICATION)
await notificationModuleService.createNotifications({
  to: "user@example.com",
  channel: "email",
  content: {
    html: "<h1>Welcome</h1><p>...</p>",
    subject: "Welcome to Medusa Emails",
  },
})

Local development

Medusa Emails is not available locally. Use the Local Notification Module Provider to log email details to the console:

{
  resolve: "@medusajs/medusa/notification-local",
  id: "local",
  options: {
    channels: [process.env.NODE_ENV === "development" ? "email" : "feed"],
  },
}

What we can borrow

• The notification module pattern (sendNotificationsStep, createNotifications) works the same in self-hosted Medusa — we just need our own SMTP provider
• The local notification module provider pattern is useful for our dev/test environments
• Email activity tracking concept → feeds our dashboard (Nova's lane)

What we must NOT use

• Medusa Emails is Cloud-only. We self-host SMTP (Postfix, SendGrid, or Amazon SES) per tenant.

3. React Email templates

React Email lets you create email templates using React components with preview and testing capabilities.

Setup (Cloud projects)

1. Install React Email dependencies
2. Create email templates as React components
3. Preview templates during development
4. Send emails using the template with Medusa Emails

Common templates

• Order confirmation
• Password reset
• Welcome email
• Shipping notification
• Refund confirmation

What we can borrow

• React Email is an open-source library (MIT) — we can use it in our self-hosted Medusa projects too
• The component-based email template pattern (React → HTML string) is framework-agnostic and works with any SMTP provider
• Preview during dev is valuable for our tenant onboarding (show clients their email templates before go-live)

4. Cloud project creation

From starters

Medusa provides starter templates for quick setup:

Each starter includes: backend, admin dashboard, storefront.

From GitHub

Import your own repository — Medusa sets up Postgres, Redis, S3 automatically.

Environments

• Multiple long-lived environments (production, staging)
• Instant preview environments on every PR
• Zero-downtime deployments
• Autoscaling to meet traffic demands

Managed resources

• PostgreSQL database
• Redis server
• S3 bucket (file storage)
• Medusa Cache (API performance)
• Medusa Search (full-text + vector, Scale/Enterprise)

What we can borrow

• The starter template concept (we already have our own: Next.js Storefront + Agilo POS + Medusa backend per tenant)
• Preview environments per PR — we can replicate with Docker Compose + nginx vhost per PR (Sol's lane)
• Zero-downtime deploy pattern — blue/green or rolling update in Docker

What we must NOT use

• Medusa Cloud managed resources (Postgres, Redis, S3) — we self-host these per tenant in Docker Compose
• Cloud environments — we manage our own staging/prod per tenant

5. Clone locally

Prerequisites

• Node.js v20.19.0+ or v22.12.0+
• Git
• PostgreSQL running locally

Who is this for

Created your project from a starter and don't have the code locally yet. Cloud clones the starter code into a GitHub repo in your account/org.

Steps

1. Clone the repository locally
2. Install dependencies (npm install)
3. Set up local PostgreSQL
4. Configure environment variables (.env)
5. Run the application (npm run dev)

Local email testing

Since Medusa Emails isn't available locally, use the Local Notification Module Provider to log email details to the console during development.

What we can borrow

• The clone-locally workflow is exactly how our tenant onboarding should work:
  1. Sol scaffolds the tenant repo from our template
  2. Client clones it locally
  3. Client runs npm run dev against local resources
  4. Client pushes changes → triggers deploy
• The local notification module provider pattern for email testing

6. Medusa Cloud vs self-hosted — comparison

What we borrow

1. Fix with AI pattern — agent analyzes logs, proposes fixes → our Atlas agent
2. Preview environments per PR — Docker Compose + nginx vhost per PR
3. Zero-downtime deploy — blue/green in Docker
4. React Email templates — MIT library, works with any SMTP
5. Local notification module provider — for dev/test email
6. Project scaffolding — clone from starter → our tenant onboarding flow
7. Email activity tracking → dashboard panel (Nova's lane)

What we must NOT use

1. Medusa Cloud managed resources — lock-in, per-plan pricing
2. Medusa Emails — Cloud-only, we self-host SMTP
3. Medusa Search — Cloud-only, we self-host Meilisearch
4. Medusa Cache — Cloud-only, we use Redis
5. Cloud environments — we manage our own
6. Cloud Assistant — we have our own Heart agents

7. Open items

1. Atlas agent spec — design an Atlas sub-agent that tails Docker logs and proposes fixes (Fix with AI pattern for self-hosted)
2. Email provider selection — SendGrid vs Amazon SES vs Postfix per tenant (Mira's cost lane)
3. React Email adoption — evaluate for tenant email templates (Nova's UX lane)
4. Preview environment automation — Docker Compose + nginx vhost per PR (Sol's engineering lane)
5. Search provider — evaluate Meilisearch vs Medusa Search vs Elasticsearch for tenant storefronts
6. Clone-locally onboarding — write a tenant onboarding script that scaffolds from our template (Sol's lane)
7. Email activity dashboard — add email delivery metrics to the fleet dashboard (Nova's lane)
8. Sender domain verification — per-tenant domain setup for email (Sol's ops lane)