# Mastra projects

> Deploy an existing Mastra application on Constal without changing its framework imports or orchestration code.

Constal hosts an existing Mastra project as an immutable, governed deployment. Your application continues to import `@mastra/core`, provider packages, Tools, workflows, networks, storage types, middleware, and clients normally. You do not replace those imports with `@constal/sdk`, add a Constal manifest, or translate the application into another graph format.

```sh
npm install -g @constal/cli
printf '%s' "$CONSTAL_API_KEY" | constal auth login --token-stdin
constal deploy .
```

## What gets deployed {#outputs}

Constal detects the exported `Mastra` instance, runs the installed Mastra build through the Constal deployer, and publishes one immutable Worker artifact. Each registered Agent, workflow, legacy network, and vNext network becomes an addressable Constal Agent entry. If the project starts an Express or Node HTTP server, the same deployment also publishes a server Agent and a Channel that targets it.

The deployment does not add another scheduler or storage service. Mastra behavior executes inside ordinary customer-scoped Sessions and Runs. Model calls, external Tools, Credentials, cost, and approvals use the existing Constal Resource and code-Policy boundaries.

## Choose a guide {#guides}

| Goal | Guide |
| --- | --- |
| Deploy a repository or local project | [Deploy a Mastra project](/docs/agents/mastra/deploy.md) |
| Understand the runtime mapping | [How Mastra maps to Constal](/docs/agents/mastra/runtime.md) |
| Check versions, features, limits, and failures | [Mastra compatibility and operations](/docs/agents/mastra/compatibility.md) |
| Configure model or service authority | [Gateways and Models](/docs/resources/gateways-and-models.md) |
| Give each customer different Resources | [Scoped bindings](/docs/credentials/scoped-bindings) |

## Existing clients remain valid {#clients}

Point `@mastra/client-js` at the deployed Agent compatibility URL and keep its Agent, workflow, memory, Tool, vector, scorer, MCP, voice, and streaming calls:

```ts
import { MastraClient } from "@mastra/client-js";

const client = new MastraClient({
  baseUrl: "https://platform.constal.ai/v1/namespaces/production/agents/support/mastra",
  headers: { authorization: `Bearer ${process.env.CONSTAL_API_KEY}` },
  retries: 0,
});

const result = await client.getAgent("support").generate("Resolve ticket 42");
```

Provider retries remain disabled at this boundary because Constal recovers the settled operation from the Run journal instead of asking the provider to repeat a paid or externally visible effect.

## Next steps {#next-steps}

Start with the [deployment tutorial](/docs/agents/mastra/deploy.md), then review [runtime mapping](/docs/agents/mastra/runtime.md) before attaching customer Credentials or external services.