Skip to content

Deploy a Mastra app

Run a Mastra app on EZGH Deploy, with its agents' commands in EZGH Sandboxes, its storage in a PostgreSQL database and its traces in Observability.

Updated View as Markdown

A Mastra app runs on Deploy as one service, agents, with a PostgreSQL database for Mastra’s storage. With @ezghcloud/mastra-integration, its agents run commands in EZGH Sandboxes started from images built from your repository, and its traces go to Observability next to the service’s logs.

1. Create the app

Start from an existing Mastra app, or create one:

npm create mastra@latest

@ezghcloud/mastra-integration needs Node.js 22 or later and @mastra/core 1.80 or later. It is ESM only. The current @mastra/pg needs @mastra/core 1.83 or later.

2. Add the integration

npm i @ezghcloud/mastra-integration @mastra/observability @mastra/pg

In src/mastra/index.ts, give the agent’s workspace an EzghSandbox, keep Mastra’s storage in the database, and send its traces to Observability:

import { Agent } from "@mastra/core/agent"
import { Mastra } from "@mastra/core/mastra"
import { Workspace } from "@mastra/core/workspace"
import { Observability } from "@mastra/observability"
import { PostgresStore } from "@mastra/pg"
import { EzghSandbox, ezghObservability } from "@ezghcloud/mastra-integration"

const workspace = new Workspace({
  sandbox: new EzghSandbox({ id: "coder", image: process.env.SANDBOX_IMAGE! }),
})
const coder = new Agent({ id: "coder", name: "Coder", model: "…", instructions: "…", workspace })

export const mastra = new Mastra({
  agents: { coder },
  storage: new PostgresStore({ id: "pg", connectionString: process.env.DATABASE_URL! }),
  observability: new Observability({ configs: { ezgh: ezghObservability() } }),
})

On Deploy, neither needs a key, an organization or a project: they use the service’s bot, and the organization, project and environment Deploy sets on every service (see Environment variables).

Give each EzghSandbox an id. The sandbox is named after it (mastra-<id>), so a restarted or newly rolled-out instance finds and reuses the same sandbox. Without an id, each start of the app creates a new sandbox.

3. Add a sandbox image

A sandbox starts from an image. To build one from your repository, add sandbox/Dockerfile (the image sandbox) or sandbox/<name>.Dockerfile (the image <name>), for example sandbox/python.Dockerfile:

FROM python:3.13-slim

Its FROM pulls through the project’s registry, like any image build. <name> is a lowercase letter, then up to 39 lowercase letters, digits or hyphens, and isn’t agents or db; init adds at most 20.

To skip this step, start sandboxes from an image you pushed to the stack’s ci.registry scope in Container Registry (<registry>/<scope>/<name>:<tag>), and set SANDBOX_IMAGE to it. The service’s bot may pull only from that scope; other images are refused.

4. Write the file

From the root of the checkout:

ezgh deploy init

Detection finds Mastra, and init writes EZGHDeploy, then prints the next steps:

version: 1
name: "coder"
region: us-west-1

services:
  agents:
    type: web
    source: ./           # no Dockerfile: built as `ezgh deploy detect` says
    port: 4111
    sandboxes: true      # its Bot may use EZGH Sandboxes in the project
    scale: { min: 1, max: 1 }   # one instance: Mastra's workers run in-process
    health: { path: /health }   # Mastra's health route
    access: { db: owner }       # Mastra creates its tables
    env:
      DATABASE_URL: ${{ resources.db.uri }}
      OTEL_SERVICE_NAME: agents
      SANDBOX_IMAGE: ${{ sandboxImages.python.image }}

resources:
  db:
    type: postgresql
    engineVersion: "18"
    instanceType: gs-1.large
    storage:
      sizeGiB: 20
    backup:
      retentionDays: 7
    logicalDatabases:
      - mastra

sandboxImages:           # built like services, for the sandboxes agents starts
  python:
    dockerfile: ./sandbox/python.Dockerfile

environments:
  production:
    branch: "main"
    project: "coder-prod"

ci:
  registry: "coder"           # the Container Registry scope images are pushed to
Key What it does
services.agents The Mastra server on port 4111, built from the repository with no Dockerfile
sandboxes: true Lets the service’s bot create and use sandboxes in the environment’s project
scale: { min: 1, max: 1 } One instance: Mastra’s workers, such as scheduled workflows, run in the server’s process
health: { path: /health } The path health checks request: Mastra’s health route
access: { db: owner } The service’s database user owns the database, so Mastra can create its tables at start
DATABASE_URL The database’s connection string, for PostgresStore
OTEL_SERVICE_NAME The service name on the app’s traces
sandboxImages One image for each sandbox/*.Dockerfile, built with the service on every deployment
SANDBOX_IMAGE The first sandbox image, by digest: sandbox, from sandbox/Dockerfile, when there is one, else the first by name

To use your model provider, add its key as a secret. In EZGHDeploy:

secrets:
  llm:
    fields: [OPENAI_API_KEY]

and under services.agents.env, OPENAI_API_KEY: ${{ secrets.llm#OPENAI_API_KEY }}. Then store the key in EZGH Secrets as secret llm, field OPENAI_API_KEY.

Check the file with ezgh deploy validate.

5. Push

Register the environment for the branch and project the file names, then commit EZGHDeploy and push. The deployment builds agents and each sandbox image, creates the database, and rolls the service out. See Deployments.

6. Read the traces

Traces go to the environment’s project in Observability, in the dataset named after the environment (production), with service agents. Each agent run is one trace, with spans for model calls and tool use and Mastra’s GenAI attributes on them. Open Observability, then Traces, or from the CLI:

ezgh obs traces get <trace ID> --project coder-prod --dataset production

The service’s output, its logs, is in the same dataset under the same service. See Traces.

7. Connect chat platforms

Mastra’s channels connect an agent to Slack, Discord, Telegram and other chat platforms through Chat SDK adapters (@chat-adapter/<platform>). The platforms send messages to the agent’s webhook, so agents needs a public address. Without a domain of your own, it can use its CDN hostname:

services:
  agents:
    public: { cdn: { enabled: true } }

After the next deployment, agents is served over HTTPS at a hostname such as d4k2m9x0a7qpe.ezghcdn.com, which ezgh cdn distributions list --project coder-prod shows. Set each platform’s webhook to:

https://<hostname>/api/agents/<agent id>/channels/<platform>/webhook

for example https://d4k2m9x0a7qpe.ezghcdn.com/api/agents/coder/channels/slack/webhook. To use a domain of your own instead, add it under public.domains (see Public services); the webhook path stays the same.

Add each platform’s bot token and signing secret as secret fields, like the model provider’s key, under the names its adapter reads.

With public, all of Mastra’s API (/api) can be reached from the internet. Turn on Mastra’s server authentication; channel webhooks stay reachable without it, and each adapter checks its platform’s signature.

During a deployment, the old and the new instance of agents run together for a short time. Mastra keeps channels’ deduplication and locks in the instance’s memory, so a message that arrives then, or a platform’s retry, can be answered twice. To prevent it, keep that state in a cache: add a valkey resource, set REDIS_URL on agents to its ${{ resources.<name>.uri }}, and give the agent’s channels state: createRedisState() from @chat-adapter/state-redis.

Good to know

  • One instance runs the app, and Mastra’s workers with it. Keep scale at min: 1, max: 1.
  • A reference to a sandbox image needs sandboxes: true on the service; the file is refused without it.
  • A Mastra image built by detection holds only Mastra’s build output, .mastra/output, with its own node_modules. A release command on the service, or a service built from it with its own command, finds no app source in it. To keep the whole app in the image, set build.startCommand to a command other than node .mastra/output/index.mjs.
  • agents is private unless it has public. To reach it from the internet, give it its CDN hostname (see Connect chat platforms) or public.domains (see Public services).
  • Node services trust the EZGH database certificate authority with no change to the app: Deploy sets NODE_EXTRA_CA_CERTS on every service, from its next deployment. A value the file sets wins.
  • In an environment registered before sandbox access existed, a deployment of a file with sandboxes: true fails until the environment’s services boundary is updated. After that failure, the stack’s Settings offers Update services boundary for the environment (it needs policies.update); then push or deploy again.
  • The service’s bot can run commands and write files only in sandboxes that have no bot. In a sandbox that has one, those also need bots.pass on its bot, which a service’s bot doesn’t have. Sandboxes EzghSandbox creates have no bot.
  • A project holds at most 100 sandboxes, suspended and stopped ones included. Delete sandboxes an agent no longer needs. See Sandbox limits.
  • Removing sandboxes: true takes the service’s sandbox access away. Sandboxes the app created stay as they are; Deploy never stops or deletes them.
Navigation

Type to search…

↑↓ navigate↵ selectEsc close