Deploy Mastra

Deploy and Host Mastra on Railway

Mastra is a TypeScript framework for building AI agents, workflows, tools, and production-ready AI applications.

This Railway template deploys Mastra with PostgreSQL, providing a production Mastra server with Studio, persistent storage, agent memory, workflows, health monitoring, and multi-provider AI model support.

About Hosting Mastra

Mastra provides a complete TypeScript-native framework for building and operating AI-powered applications.

This template runs Mastra as a standalone production server and includes Mastra Studio in the production build, allowing you to inspect and interact with registered agents, workflows, and tools directly from your browser.

PostgreSQL is used as the persistent storage backend through Mastra's official PostgreSQL integration, allowing application state to survive container restarts and Railway redeployments.

The Mastra application is publicly accessible, while PostgreSQL remains available only through Railway private networking.

Common Use Cases

• Build AI agents with TypeScript
• Create multi-step AI workflows
• Develop AI assistants
• Build agent-powered APIs
• Persist agent memory and conversation state
• Create human-in-the-loop workflows
• Develop AI automation pipelines
• Experiment with multiple LLM providers
• Build internal AI tools
• Develop MCP-compatible AI applications
• Inspect agents and workflows using Mastra Studio
• Build production AI backends

Dependencies for Mastra Hosting

This template includes:

• Mastra — AI agent and workflow runtime
• Mastra Studio — Browser-based development and inspection interface
• PostgreSQL — Persistent application storage
• Railway Private Networking — Internal database communication

Mastra Studio

This template builds Mastra using:

mastra build --studio

Mastra's production build can include the Studio interface inside the generated .mastra/output deployment artifact.

After deployment:

1. Generate a Railway public domain for the Mastra service.
2. Open the assigned Mastra public URL.
3. Use Mastra Studio to inspect and interact with the registered application components.

The included starter application registers:

• Assistant agent
• Example workflow
• PostgreSQL storage

No separate frontend service is required.

Persistent PostgreSQL Storage

This template uses Mastra's official PostgreSQL storage package:

@mastra/pg

The application connects to PostgreSQL using:

DATABASE_URL

On Railway, the Mastra service references the PostgreSQL service through:

${{Postgres.DATABASE_URL}}

The template uses PostgreSQL for persistent Mastra state, allowing application data to survive:

• Mastra restarts
• Container replacements
• Railway redeployments
• Application upgrades

The Mastra application itself does not require a Railway Volume.

Supported AI Providers

The starter agent supports:

Select the provider using:

MODEL_PROVIDER

Supported values:

openai
anthropic
google

Configure the model using:

MODEL_NAME

The repository generates the model identifier from the selected provider and model configuration.

Important Environment Variables

DATABASE_URL

Required PostgreSQL connection URL used by Mastra for persistent storage.

Railway automatically references the included PostgreSQL service.

MODEL_PROVIDER

Defines the active model provider.

Supported values:

• openai
• anthropic
• google

Default:

openai

MODEL_NAME

Defines the provider-specific model name.

Default:

gpt-4o-mini

Provider API Keys

Configure only the credential required by the selected provider:

• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• GOOGLE_GENERATIVE_AI_API_KEY

An AI provider API key is required when invoking the corresponding agent, but the Mastra service itself can be configured independently of unrelated provider credentials.

SYSTEM_PROMPT

Optional default instructions used by the starter assistant agent.

PORT

HTTP port used by the Mastra production server.

Default:

4111

NODE_ENV

Set to:

production

for Railway deployment.

Starter Agent

The template includes a starter agent named:

assistant

The agent uses:

• Configurable AI provider
• Configurable model
• Configurable system prompt
• PostgreSQL-backed Mastra storage

It provides a starting point for creating custom AI assistants and agent-powered applications.

Starter Workflow

An example workflow is included so the deployment immediately contains a functional Mastra workflow.

The workflow can be inspected and executed through Mastra Studio and serves as a reference for building:

• Sequential AI processes
• Multi-step transformations
• Agent-driven workflows
• Human-in-the-loop processes
• Automated AI pipelines

Health Endpoint

The template exposes:

GET /health

The health route verifies both:

• Mastra application availability
• PostgreSQL connectivity

Healthy response:

{
  "status": "ok",
  "database": "ok"
}

If PostgreSQL is unavailable, the endpoint returns HTTP 503.

The health check does not invoke an AI provider.

Railway Deployment

The template deploys two services:

Internet
   │
   ▼
Railway HTTPS
   │
   ▼
Mastra
:4111
   │
   │ Railway Private Network
   ▼
PostgreSQL
:5432

Mastra Service

Recommended configuration:

• Source: GitHub repository
• Public Domain: enabled
• Port: 4111
• Health Check: /health
• Volume: not required
• Custom Start Command: not required
• RAILWAY_RUN_UID: not required

The production image starts the generated Mastra server directly from:

.mastra/output/index.mjs

The Dockerfile runs the application as a non-root Node.js user.

PostgreSQL Service

Recommended configuration:

• Public Domain: disabled
• Private Networking: enabled
• Port: 5432
• Persistent Volume: enabled

PostgreSQL should remain private and should not be exposed directly to the internet.

After Deployment

1. Wait for PostgreSQL to become available.
2. Wait for the Mastra service to become healthy.
3. Generate a public domain for Mastra on port 4111.
4. Set MODEL_PROVIDER.
5. Set MODEL_NAME.
6. Add the API key for the selected AI provider.
7. Open the Mastra public URL.
8. Access Mastra Studio.
9. Inspect the included assistant agent.
10. Run the included example workflow.
11. Verify /health returns a successful database status.

Persistent Storage Model

The deployment uses:

Mastra
   │
   ▼
PostgreSQL
   │
   ▼
Railway Volume

Mastra itself remains stateless from the container filesystem perspective.

This means:

• No Mastra application volume is required
• Redeployments do not remove PostgreSQL-backed state
• Application containers can be replaced safely
• PostgreSQL remains the persistent data layer

Security Notes

For production deployments:

• Keep PostgreSQL private
• Never expose DATABASE_URL
• Never commit AI provider API keys
• Use scoped provider credentials where possible
• Rotate exposed credentials immediately
• Review Studio exposure before using the template for sensitive workloads
• Avoid exposing administrative development interfaces unnecessarily
• Review authentication requirements before deploying sensitive or multi-user applications

This starter focuses on simple self-hosted deployment and does not add custom authentication that is not part of the configured Mastra application.

Mastra vs Alternatives

Mastra is particularly well suited for developers who want an AI agent and workflow platform built around the TypeScript ecosystem.

Why Deploy Mastra on Railway?

Railway provides a simple environment for running Mastra together with its persistent PostgreSQL backend.

Deploying Mastra on Railway provides:

• Automatic HTTPS domains
• Railway private networking
• Persistent PostgreSQL storage
• Built-in environment variable management
• Simple secret configuration
• Integrated deployment logs
• Easy application redeployments
• Mastra Studio in the production build
• No application volume requirement
• No Redis dependency for the standard deployment
• A clean two-service architecture

This template provides a practical starting point for building and operating TypeScript-based AI agents, workflows, and AI applications with Mastra and PostgreSQL.