AWS Lambda

AWS Lambda runs your app's server on demand, so there is no server to set up or keep running. A Lambda function does not serve the app's static files, though, so this guide uses three AWS services together:

• AWS Lambda runs the app's server, which handles its pages and API.
• Amazon S3 stores the app's static files, such as JavaScript, CSS, and images.
• Amazon CloudFront gives the app one public address with HTTPS and sends each request to the right place.

This guide walks through deploying one standalone app from scratch. You will create the app, give it a production database and an auth secret, prepare the database, build it for Lambda, create the function, upload the static files, and then put CloudFront in front of both.

You also need an AWS account and the AWS CLI installed and signed in on your computer, with a default region set. Run the commands in this guide on your own computer. Steps 5 and 6 use the AWS CLI, and Step 7 uses the CloudFront console.

Step 1: Create the app

Create your new standalone app. The example below creates an app from the Chat template, but you can start from any template. Move into the app's folder and install its dependencies. corepack enable turns on the pnpm version the app expects, so you do not need to install pnpm yourself.

npx --yes @agent-native/core@latest create my-app --standalone --template chat

cd my-app

corepack enable

pnpm install

Replace my-app with your own app name if you like. The rest of this guide assumes you are inside the app's folder.

Step 2: Configure environment secrets

The app reads its production settings from environment variables:

The exports below make the following commands work in this shell. Before deploying, save these same variables in your host's project or service environment settings. Step 5 saves the first two on the Lambda function, and Step 8 adds BETTER_AUTH_URL.

Database URL

During local development the app stores data in a local database when DATABASE_URL is unset. A deployed app needs a real PostgreSQL database that keeps its data between deploys. Lambda does not keep files between requests, so the database must live outside the function. Copy the connection string from your provider and export it:

export DATABASE_URL='your-postgres-url-string'

The database provider guides show where to find the connection string for each provider, including Amazon RDS for PostgreSQL.

Auth secret

Generate this once and keep it stable across deploys.

The app uses BETTER_AUTH_SECRET to sign user sessions. If it changes, every signed-in user is signed out. The command below generates a random value:

export BETTER_AUTH_SECRET="$(openssl rand -hex 32)"

Save the generated value somewhere safe, such as a password manager. Use the same value every time you deploy.

Public URL

BETTER_AUTH_URL is the public address people use to reach your app. On most hosts it is optional, because the app works out its address from each incoming request. Behind CloudFront, the function receives requests addressed to its own Lambda URL instead of your public address, so the app needs this variable to build correct sign-in links and OAuth redirects.

You get the address when you create the CloudFront distribution in Step 7, and you set this variable in Step 8.

Step 3: Migrate

Migrations create and update the tables the app needs in your database. Run this before the first deploy:

pnpm migrate:production

The command runs on your computer and connects to the production database with the DATABASE_URL you exported in Step 2. Run it again after you upgrade the app, before you deploy the new version.

Step 4: Build

Build the app for Lambda:

env -u DATABASE_URL -u BETTER_AUTH_SECRET -u BETTER_AUTH_URL NITRO_PRESET=aws-lambda pnpm build

NITRO_PRESET=aws-lambda builds the app as a Lambda function. The build splits the output into two folders:

The .output/server folder becomes the Lambda function, and the .output/public folder goes to S3.

Step 5: Create the function

Create the function's role

The function needs an IAM role that lets it run and write logs. Create one once for the app:

aws iam create-role --role-name my-app-lambda --assume-role-policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"lambda.amazonaws.com"},"Action":"sts:AssumeRole"}]}'

aws iam attach-role-policy --role-name my-app-lambda --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

export ROLE_ARN="$(aws iam get-role --role-name my-app-lambda --query Role.Arn --output text)"

Package and create the function

Zip the server folder, then create the function from the zip file:

(cd .output/server && zip -qr ../../function.zip .)

aws lambda create-function \
  --function-name my-app \
  --runtime nodejs24.x \
  --handler server.handler \
  --role "$ROLE_ARN" \
  --zip-file fileb://function.zip \
  --memory-size 1024 \
  --timeout 60 \
  --environment "$(node -e 'console.log(JSON.stringify({ Variables: { DATABASE_URL: process.env.DATABASE_URL, BETTER_AUTH_SECRET: process.env.BETTER_AUTH_SECRET } }))')"

--handler server.handler points Lambda at the entry file from Step 4. The node -e command turns the two secrets you exported in Step 2 into the format the AWS CLI expects, so you do not have to paste them by hand. --timeout 60 gives each request up to 60 seconds, which matches the CloudFront limit in Step 7.

A new role can take a few seconds to become usable. If create-function reports that the role cannot be assumed, wait a moment and run it again.

Add a function URL

A function URL gives the function its own HTTPS address, which CloudFront uses in Step 7:

aws lambda create-function-url-config --function-name my-app --auth-type NONE

aws lambda add-permission --function-name my-app --statement-id FunctionUrlPublic --action lambda:InvokeFunctionUrl --principal "*" --function-url-auth-type NONE

aws lambda add-permission --function-name my-app --statement-id FunctionUrlInvoke --action lambda:InvokeFunction --principal "*" --invoked-via-function-url

The first command prints the FunctionUrl, which looks like https://abc123.lambda-url.us-east-1.on.aws/. Copy it for Step 7. The two add-permission commands allow requests to reach the function through that address.

Step 6: Upload the static files

Create an S3 bucket for the app's static files and copy them in. Bucket names are shared across all of AWS, so add something unique to the name:

aws s3 mb s3://my-app-assets-123456

aws s3 sync .output/public s3://my-app-assets-123456

The bucket stays private. CloudFront reads from it in Step 7.

Step 7: Put CloudFront in front

Create the CloudFront distribution in the CloudFront console:

AllViewerExceptHostHeader forwards the browser's cookies, headers, and query strings to the function, but not its Host header. The function URL only accepts requests addressed to its own host name, which is why the app needs BETTER_AUTH_URL in the next step.

Step 8: Set the public address and deploy

Export the CloudFront address and save all three variables on the function:

export BETTER_AUTH_URL='https://d111111abcdef8.cloudfront.net'

aws lambda update-function-configuration \
  --function-name my-app \
  --environment "$(node -e 'console.log(JSON.stringify({ Variables: { DATABASE_URL: process.env.DATABASE_URL, BETTER_AUTH_SECRET: process.env.BETTER_AUTH_SECRET, BETTER_AUTH_URL: process.env.BETTER_AUTH_URL } }))')"

This command replaces all of the function's variables at once, so it includes the two from Step 5 as well. Use the same full list whenever you change a variable.

Open the CloudFront address and create the first account.

Deploy updates

To ship a new version, run the migrations, build again, upload the new function code and static files, and clear CloudFront's cache:

pnpm migrate:production

env -u DATABASE_URL -u BETTER_AUTH_SECRET -u BETTER_AUTH_URL NITRO_PRESET=aws-lambda pnpm build

rm -f function.zip && (cd .output/server && zip -qr ../../function.zip .)

aws lambda update-function-code --function-name my-app --zip-file fileb://function.zip

aws s3 sync .output/public s3://my-app-assets-123456

aws cloudfront create-invalidation --distribution-id your-distribution-id --paths "/*"

aws s3 sync keeps the previous version's files in the bucket, so pages that are already open in a browser can still load them. Find the distribution ID on the distribution's page in the CloudFront console. The function's variables stay in place, so you do not need to repeat Step 8.

Limits

What's next

• Node.js - run the app on a machine you manage
• Deployment Environment Variables - the full list of production settings
• Deployment - compare hosting targets and prerequisites