# Mastra compatibility and operations

> Check qualified versions and features, interpret deployment output, and diagnose unsupported dependencies or bindings.

Constal qualifies behavior by exact project revision, installed framework/client versions, immutable artifact, fault schedules, and two-customer isolation evidence. A build preview is not a compatibility pass. Public receipts identify which source and feature cases actually ran.

## Qualified surface {#qualified-surface}

| Surface | Mapping |
| --- | --- |
| Mastra `>=0.10.0 <1.0.0`, `>=1.63.0 <2.0.0` | Controlled Worker or SandboxPool build according to resolved dependencies |
| Agents and streaming | Agent Runs and durable protocol events |
| Workflows and suspend/resume | Runs, framework snapshots, and durable waits |
| Legacy and vNext networks | Registry-specific Agent entries |
| Memory storage | Owner-scoped framework domains |
| Vector operations | Constal Memory Resource |
| Tools, scorers, MCP, and voice routes | Qualified public Mastra handler modules |
| Registered Hono middleware and `apiRoutes` | Unchanged code inside a customer-scoped Run |
| External Express or Node server | Channel plus server Agent |
| OpenAI, Anthropic, Bedrock, Tavily, and Exa | Governed Model, Search, or Service Resources |
| Daytona, E2B, and Stagehand Tools | SandboxPool or Browser Resources |

The production Worker is minified and must remain below 64 MiB raw and 10 MiB with deterministic level-9 gzip. Deployment independently recompresses the exact upload before publishing it.

## Serving URLs {#serving-urls}

Use the Mastra compatibility base for `@mastra/client-js`:

```text
https://platform.constal.ai/v1/namespaces/{namespace}/agents/{agent}/mastra
```

An external server is reached through its emitted Channel:

```text
https://platform.constal.ai/v1/channels/{tenant}/{namespace}/{channel}/{route...}
```

Do not bypass the Channel with a private Worker hostname. The Channel is the authentication, code-Policy, target-selection, and customer-authority boundary.

## Deployment diagnostics {#diagnostics}

The build result records the detected entry, exact package manager, registry entries, storage disposition, provider bindings, compatibility requirements, raw/gzip artifact sizes, and any generated host overlay. A requirement marked `compatibility-work` names the unresolved package, source location, missing binding, or replacement instead of allowing an ungoverned fallback.

Common fixes are:

- Bind `constal-peer-HOST` when unchanged application code calls `http://HOST:PORT` for another Agent.
- Choose `--mastra-storage constal` when the project uses a local or ephemeral default store.
- Choose `--mastra-storage project` only with an explicitly configured external Worker-compatible store.
- Replace raw TCP, local filesystem, subprocess, or stdio-MCP assumptions with an existing Service, Memory, SandboxPool, or HTTP MCP Resource.
- Configure Credentials and scoped bindings rather than expecting `.env` secret values inside application code.
- Use the exact project root in a monorepo so detection finds the exported `Mastra` instance without publishing siblings.

## Release verification {#release-verification}

Before promotion, verify the deployment reached `deployed`, every emitted Resource shares the expected artifact digest, gzip size is below the limit, and a real Mastra client can list and invoke the expected entry. Exercise at least one model or external Tool call, one stream, and every workflow wait used by the application. Inspect the Run journal to confirm each paid or externally visible effect dispatched once.

The public A2A gateway qualification demonstrates an unchanged Express server, Bedrock, streaming, durable application Maps, detached background work, three peer Channels, crash recovery, and two isolated customers. Continue with [Operate Agents](/docs/agents/operate.md), [Operate Runs](/docs/runs/operate.md), and [Analytics](/docs/analytics.md) for production operations.