---
title: "Deploy a Mastra app"
description: "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."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy a Mastra app

A [Mastra](https://mastra.ai) 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](/sandboxes) started from images built from your repository, and its traces go to
[Observability](/observability) next to the service's logs.

## 1. Create the app

Start from an existing Mastra app, or create one:

```sh
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

```sh
npm i @ezghcloud/mastra-integration @mastra/observability @mastra/pg
yarn add @ezghcloud/mastra-integration @mastra/observability @mastra/pg
pnpm add @ezghcloud/mastra-integration @mastra/observability @mastra/pg
bun add @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:

```ts
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](/deploy/file#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`:

```dockerfile
FROM python:3.13-slim
```

Its `FROM` pulls through the project's registry, like any [image build](/build/image-builds#base-images).
`<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) (`<registry>/<scope>/<name>:<tag>`), and set `SANDBOX_IMAGE` to it.
The service's bot may pull only from that scope; other images are
[refused](/sandboxes/images#permission-to-pull).

## 4. Write the file

From the root of the checkout:

```sh
ezgh deploy init
```

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

```yaml
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`:

```yaml
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](/secrets) as secret `llm`, field `OPENAI_API_KEY`.

Check the file with `ezgh deploy validate`.

## 5. Push

[Register the environment](/deploy/environments) 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](/deploy/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:

```sh
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](/observability/traces).

## 7. Connect chat platforms

Mastra's [channels](https://mastra.ai/docs/agents/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:

```yaml
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:

```text
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](/deploy/file#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](https://mastra.ai/docs/server/auth); 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](/deploy/file#resources), 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](#7-connect-chat-platforms)) or `public.domains` (see
  [Public services](/deploy/file#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`](/sandboxes/bots) 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](/sandboxes/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.

Source: https://docs.ezghcloud.com/deploy/mastra/index.mdx
