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/pgyarn add @ezghcloud/mastra-integration @mastra/observability @mastra/pgpnpm add @ezghcloud/mastra-integration @mastra/observability @mastra/pgbun add @ezghcloud/mastra-integration @mastra/observability @mastra/pgIn 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-slimIts 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 initDetection 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 productionThe 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>/webhookfor 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
scaleatmin: 1, max: 1. - A reference to a sandbox image needs
sandboxes: trueon the service; the file is refused without it. - A Mastra image built by detection holds only Mastra’s build output,
.mastra/output, with its ownnode_modules. Areleasecommand on the service, or a service builtfromit with its owncommand, finds no app source in it. To keep the whole app in the image, setbuild.startCommandto a command other thannode .mastra/output/index.mjs. agentsis private unless it haspublic. To reach it from the internet, give it its CDN hostname (see Connect chat platforms) orpublic.domains(see Public services).- Node services trust the EZGH database certificate authority with no change to the app: Deploy
sets
NODE_EXTRA_CA_CERTSon 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: truefails until the environment’s services boundary is updated. After that failure, the stack’s Settings offers Update services boundary for the environment (it needspolicies.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.passon its bot, which a service’s bot doesn’t have. SandboxesEzghSandboxcreates 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: truetakes the service’s sandbox access away. Sandboxes the app created stay as they are; Deploy never stops or deletes them.