Documentation / Agents / Deploy

Deploy a Mastra project

Package, build, publish, and verify an unchanged Mastra project with the Constal CLI.

Before you begin

Use a Mastra project with a committed lockfile and a conventional exported application entry such as src/mastra/index.ts. Constal currently qualifies Mastra versions >=0.10.0 <1.0.0 and >=1.63.0 <2.0.0. The CLI accepts a local directory, ZIP or TAR.GZ archive, or public Git URL ending in a full 40-character commit SHA.

Create a deployment API key with deployment and Resource-read authority, then save it without placing the key in shell history:

sh
printf '%s' "$CONSTAL_API_KEY" | constal auth login --token-stdin
constal context use --namespace production

Constal excludes .env, node_modules, generated .constal output, and common build directories from a local project archive. Keep secrets in Constal Credentials rather than the repository.

Steps

  1. Run the project locally with its normal Mastra command and commit its lockfile.
  2. From the Mastra package root, run constal deploy .. In a monorepo, use the workspace member containing the exported Mastra instance; Constal retains that member as the deployment root while installing from the enclosing workspace lockfile.
  3. Keep the default --mastra-storage constal to substitute the owner-scoped durable storage adapter. Use --mastra-storage project only when the application already configures an external Worker-compatible Mastra store and you intend to preserve it.
  4. Bind any project-specific service or peer Channel by logical name. The binding is resolved and pinned during deployment; application input cannot replace it later.
  5. Wait for the build, or use --no-wait in automation and read the returned deployment revision with constal deployments get.
sh
constal deploy . \
  --mastra-storage constal \
  --bind orders=crn:constal:production:acme:production:service/orders \
  --bind constal-peer-data-processor=crn:constal:production:acme:production:channel/data-processor \
  --wait \
  --output json

A peer URL such as http://data-processor:4111 maps only when constal-peer-data-processor is bound to an exact Channel. It then enters the ordinary Channel and target-Agent code-Policy path; Constal does not create a private peer network.

Storage and Credentials

With Constal storage, Mastra threads, messages, working memory, workflow snapshots, scores, and observability records use owner-scoped framework domains. Semantic embedding and similarity operations use the bound Constal Memory Resource; Session storage does not implement vector search.

Provider environment variables receive non-secret import-time sentinels. The Model or Service Resource resolves the actual customer Credential only after code Policy accepts the exact operation. Configure provider authority through Gateways and Models, Credentials, and scoped bindings—not by uploading .env.

Verify

The completed deployment should report detection.surfaces: ["mastra"], an unchanged source digest, the installed Mastra/client versions, one shared artifact digest, and raw plus gzip Worker sizes below the platform limits. Its outputs contain an Agent for each registered entry. An external Node server additionally produces a server Agent and a Channel with the same immutable artifact.

sh
constal deployments get DEPLOYMENT_REVISION --output json
constal agents list --output json
constal channels list --output json

Invoke a small generation or workflow through the existing Mastra client and confirm that the resulting Constal Run records the expected Model and Tool settlements once.

Next steps

Read How Mastra maps to Constal for the ownership model and Mastra compatibility and operations for supported surfaces and troubleshooting. Use Operate Runs to inspect waits, cost, journal entries, and terminal state.