ContextQMD
Back to Mastra

Deploy Mastra to AWS Lambda | Deployment

docs/src/content/en/guides/deployment/aws-lambda.mdx

2025-12-187.2 KB
Original Source

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

Deploy Mastra to AWS Lambda

Deploy your Mastra application to AWS Lambda using Docker containers and the AWS Lambda Web Adapter. This approach runs your Mastra server as a containerized Lambda function with automatic scaling.

:::info This guide covers deploying the Mastra server. 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:

:::warning On AWS Lambda, the filesystem is ephemeral, so any local database file will be lost between invocations. If you're using LibSQLStore with a local file, configure it to use a remote LibSQL-compatible database (for example, Turso) instead. :::

Create a Dockerfile

Create a Dockerfile in your project root:

dockerfile
FROM node:22-alpine

WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci

# Copy source and build Mastra
COPY src ./src
RUN npx mastra build

# Alpine compatibility for some native deps
RUN apk add --no-cache gcompat

# Add the Lambda Web Adapter
COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.9.1 /lambda-adapter /opt/extensions/lambda-adapter

# Run as non-root
RUN addgroup -g 1001 -S nodejs && \
  adduser -S mastra -u 1001 && \
  chown -R mastra:nodejs /app

USER mastra

# Adapter / app configuration
ENV PORT=8080
ENV NODE_ENV=production
ENV AWS_LWA_READINESS_CHECK_PATH="/api"

# Start the Mastra server
CMD ["node", ".mastra/output/index.mjs"]

:::note This Dockerfile uses npm. If you're using pnpm, yarn, or another package manager, adjust the commands accordingly (e.g. npm ci won't work with pnpm lockfiles). :::

Build and push the Docker image

<Steps> <StepItem> Set up environment variables for the deployment. Use the same region for all AWS services (ECR, Lambda) to avoid issues with resources not appearing across regions: 
```bash
export PROJECT_NAME="your-mastra-app"
export AWS_REGION="us-east-1"
export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
```
</StepItem> <StepItem> Build your Docker image. Disable BuildKit to ensure the image is compatible with Lambda's container runtime: 
```bash
export DOCKER_BUILDKIT=0
docker build --platform linux/arm64 -t "$PROJECT_NAME" .
```

:::note
BuildKit's default image format can cause compatibility issues with Lambda. Setting `DOCKER_BUILDKIT=0` uses the classic builder, which produces images in a format Lambda reliably accepts.
:::
</StepItem> <StepItem> Create an Amazon ECR repository to store your Docker image: 
```bash
aws ecr create-repository --repository-name "$PROJECT_NAME" --region "$AWS_REGION"
```
</StepItem> <StepItem> Log in to Amazon ECR: 
```bash
aws ecr get-login-password --region "$AWS_REGION" | \
  docker login --username AWS --password-stdin \
  "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com"
```
</StepItem> <StepItem> Tag your image and push it to ECR: 
```bash
docker tag "$PROJECT_NAME":latest \
  "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$PROJECT_NAME":latest

docker push \
  "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$PROJECT_NAME":latest
```
</StepItem> </Steps>

Create the Lambda function

<Steps> <StepItem> Navigate to the [AWS Lambda Console](https://console.aws.amazon.com/lambda/) and click **Create function**. Make sure you have the same region selected as where you created your ECR repository. </StepItem> <StepItem> Select **Container image** and configure the function: 
- **Function name**: Enter a name (e.g. `mastra-app`)
- **Container image URI**: Click **Browse images**, select your ECR repository, and choose the `latest` tag
- **Architecture**: Select **arm64**

Click **Create function** to create the Lambda function.
</StepItem> <StepItem> Configure memory and timeout. Go to **Configuration** > **General configuration** and click **Edit**: 
- **Memory**: 512 MB (adjust based on your application needs)
- **Timeout**: 1 minute or higher (the default 3 seconds is too low for most Mastra applications)

Click **Save**.
</StepItem> <StepItem> Add environment variables. Go to **Configuration** > **Environment variables** and click **Edit**. Add the variables your Mastra application needs: 
- `OPENAI_API_KEY`: Your OpenAI API key (if using OpenAI)
- `ANTHROPIC_API_KEY`: Your Anthropic API key (if using Anthropic)
- Other provider-specific API keys as needed (e.g. `TURSO_DATABASE_URL` and `TURSO_AUTH_TOKEN` if using LibSQL with Turso)

Click **Save**.
</StepItem> <StepItem> Enable a Function URL for external access. Go to **Configuration** > **Function URL** and click **Create function URL**: 
- **Auth type**: Select **NONE** for public access
- Under **Additional settings**, check **Configure cross-origin resource sharing (CORS)**, then configure:
  - **Allow origin**: `*`
  - **Allow headers**: `content-type` (`x-amzn-request-context` is also required when used with services like CloudFront/API Gateway)
  - **Allow methods**: `*`

Click **Save**.
</StepItem> </Steps>

Verify your deployment

<Steps> <StepItem> Copy the **Function URL** from the Lambda console and visit `<your-function-url>/api/agents` in your browser. You should see a JSON list of your agents. </StepItem> <StepItem> You can now call your Mastra endpoints over HTTP. 
:::warning
For production deployments, set up [authentication](/docs/server/auth) before exposing your endpoints publicly, restrict CORS origins to your trusted domains, use AWS IAM roles for secure access to other AWS services, and store sensitive environment variables in AWS Secrets Manager or Parameter Store.
:::
</StepItem> </Steps>

Next steps

This guide provides a quickstart for deploying Mastra to AWS Lambda. For production workloads, consider enabling CloudWatch monitoring for your Lambda function, setting up AWS X-Ray for distributed tracing, and configuring provisioned concurrency for consistent performance.