ContextQMD
Back to Mastra

Deploy Mastra to Cloudflare | Deployment

docs/src/content/en/guides/deployment/cloudflare.mdx

2025-12-183.2 KB
Original Source

import Steps from "@site/src/components/Steps"; import StepItem from "@site/src/components/StepItem";

Deploy Mastra to Cloudflare

Use @mastra/deployer-cloudflare to deploy your Mastra server to Cloudflare Workers. The deployer bundles your code and generates a wrangler.jsonc file conforming to Cloudflare's wrangler configuration, ready to deploy with no additional configuration.

:::info

If you're using a server adapter or web framework, deploy the way you normally would for that framework.

:::

Before you begin

You'll need a Mastra application and a Cloudflare account.

:::warning Cloudflare Workers use an ephemeral filesystem, so any storage you configure (including observability storage) must be hosted externally. If you're using LibSQLStore with a file URL, switch to a remotely hosted database. :::

Installation

Add the @mastra/deployer-cloudflare package to your project:

bash
npm install @mastra/deployer-cloudflare@latest

Import CloudflareDeployer and set it as the deployer in your Mastra configuration:

typescript
import { Mastra } from '@mastra/core'
// highlight-next-line
import { CloudflareDeployer } from '@mastra/deployer-cloudflare'

export const mastra = new Mastra({
  // highlight-start
  deployer: new CloudflareDeployer({
    name: 'your-project-name',
    vars: {
      NODE_ENV: 'production',
    },
  }),
  // highlight-end
})

In order to test your Cloudflare Worker locally, also install the wrangler CLI:

bash
npm install -D wrangler

Usage

After setting up your project, push it to your remote Git provider of choice (e.g. GitHub).

<Steps> <StepItem> Connect your repository to Cloudflare. On the "Workers & Pages" dashboard, select **Create application** and choose your Git provider in the next step. Continue with the setup process and select the repository you want to deploy. 
:::note

Remember to set your environment variables needed to run your application (e.g. your [model provider](/models/providers) API key). You can upload secrets from your `.env` file using `npx wrangler secret bulk .env`. See [Secrets](/reference/deployer/cloudflare#secrets) for details.

:::
</StepItem> <StepItem> Once you're ready, click the **Deploy** button and wait for the first deployment to complete. </StepItem> <StepItem> Try out your newly deployed function by going to `https://<your-project-name>.<slug>.workers.dev/api/agents`. You should get a JSON response listing all available agents. 
Since the [Mastra server](/docs/server/mastra-server) prefixes every API endpoint with `/api`, you have to add it to your URLs when making requests.
</StepItem> <StepItem> You can now call your Mastra endpoints over HTTP. 
:::note

Set up [authentication](/docs/server/auth) before exposing your endpoints publicly.

:::
</StepItem> </Steps>