# Mastra

> Give a Mastra agent a Nevia computer as its workspace, so its file tools and commands run on the computer

> Nevia is in early access for selected teams. The CLI installs with `curl -fsSL https://get.nevia.cloud | sh`, and the MCP server is at https://api.nevia.cloud/mcp. A person signs in once in the browser.
> Setup, sign-in and requesting access: [SKILL.md](https://nevia.cloud/SKILL.md). When Nevia fits and when it doesn't: [why.md](https://nevia.cloud/why.md).

> For the complete documentation index, see [llms.txt](https://nevia.cloud/llms.txt). This page's HTML version: https://nevia.cloud/docs/agent-frameworks/mastra

The Mastra adapter gives a [Mastra](https://mastra.ai) agent a workspace on a
Nevia computer. The agent's file tools and its `execute_command` tool run on
the computer, not on your machine. The adapter is built on the
[TypeScript SDK](https://nevia.cloud/docs/reference/sdk/typescript.md) and is in early access, so
names and behaviour can change.

The quick start gives an agent a computer, asks it to write and run a program
and deletes the computer. The adapter follows Mastra's workspace contract, so
[Mastra's workspace docs](https://mastra.ai/docs/sandbox/overview) cover the
tools and options. This page covers only what is particular to Nevia.

## Prerequisites

You need:

* Node.js 22.23.4 or later on 22, or 24.22.1 or later.
* `@mastra/core` 1.68 or later.
* An API key for the model provider. The quick start uses Anthropic, so it
  needs `ANTHROPIC_API_KEY`.
* The `nevia` CLI, signed in with `nevia login`, to download the SDK bundle.
  The [Quickstart](https://nevia.cloud/docs/get-started/quickstart.md) shows how to install it.
* A Nevia key file for a service account with the **editor** role.
  [Use an automation key file](https://nevia.cloud/docs/guides/automation-key-file.md) shows how a
  workspace admin issues one.

## 1. Install the adapter

> **Invited testers only**
>
> The SDKs are in early access for invited testers. To ask for access, see
> [Request access to Nevia](https://nevia.cloud/docs/get-started/request-access.md).

From your project's root, download the SDK bundle. It unpacks to
`vendor/nevia-sdk-0.1.0/`:

```bash
curl -fsSL --oauth2-bearer "$(nevia auth access-token)" https://sdk.nevia.cloud/0.1.0.tar.gz | tar -xz
```

Then install the adapter, with the SDK beside it, from the bundle:

**npm**

```bash
npm init -y
npm pkg set type=module
npm install ./vendor/nevia-sdk-0.1.0/typescript/nevia-sdk-0.1.0.tgz \
  ./vendor/nevia-sdk-0.1.0/typescript/nevia-mastra-0.1.0.tgz \
  @mastra/core
npm install --save-dev tsx
```

Name the SDK's file next to the adapter's, so both come from the bundle and
nothing is looked up on a public registry.

The quick start runs with [tsx](https://tsx.is).

## 2. Authenticate

Point the adapter at the key file and set the model provider's key:

```bash
export NEVIA_KEY_FILE="$HOME/path/to/key.json"
export ANTHROPIC_API_KEY="sk-ant-..."
```

Without `NEVIA_KEY_FILE`, the adapter falls back to your `nevia login`
session. It finds credentials in the same order as the
[TypeScript SDK](https://nevia.cloud/docs/reference/sdk/typescript.md#client).

## 3. Give an agent a computer

Save this as `agent.ts`:

```ts
import { Agent } from '@mastra/core/agent'
import { neviaWorkspace } from '@nevia/mastra'

const workspace = neviaWorkspace({ id: 'quickstart', image: 'docker.io/library/node:24-slim' })

const agent = new Agent({
  id: 'coder',
  name: 'Coder',
  instructions: 'You write and run code in your workspace.',
  model: 'anthropic/claude-sonnet-5-5',
  workspace,
})

try {
  const result = await agent.generate(
    'Write hello.js that prints the Node.js version, then run it. Answer with its output only.',
    { maxSteps: 5 },
  )
  console.log(result.text)
} finally {
  await workspace.destroy()
}
```

Run it:

```bash
npx tsx agent.ts
```

The agent writes `/workspace/hello.js` with its write file tool, runs
`node hello.js` with `execute_command` and answers with the output. The
Node.js version varies:

```text
v24.22.2
```

The first tool call starts the workspace, creating the computer and waiting
until it is ready.

## 4. Clean up

The `finally` block deletes the computer when the agent is done, even when the
call throws. `nevia ls` confirms the computer is gone.

To keep the computer between runs, skip `destroy()`. The workspace `id` names
the computer, so a later program that calls `neviaWorkspace()` with the same
`id` finds the same computer, files included. Call `workspace.destroy()` from
that program when you are done.

## How the workspace maps to a computer

`neviaWorkspace()` returns a Mastra `Workspace`, so the agent uses Mastra's
own file tools and `execute_command`. It takes Mastra's sandbox options plus
`image`, `computerEnv` for environment variables stored on the computer, and
`nevia` for a client or its options.

Two workspaces with the same `id` share one computer. `image` and
`computerEnv` apply only when the adapter creates the computer. Commands run in
`/workspace` and file tool paths can't leave it.

`workspace.stop()` sleeps the computer and the next start wakes it with its
files intact. A sleeping computer's disk still counts toward storage until
`workspace.destroy()` deletes it.

Commands run in the foreground with direct exec and keep the last 64 KiB of
each output stream. Pass `maxRetainedBytes` to `executeCommand()` for another
cap. Truncated output ends `stderr` with a note.

## Limitations

These add to the SDK's [Limits and workarounds](https://nevia.cloud/docs/reference/sdk/limits.md).

* **No background commands.** A command must end before the tool answers, so
  Mastra leaves out the `background` argument and the process tools. The
  adapter tells the agent to redirect long output to a file instead.
* **Output arrives at the end.** `onStdout` and `onStderr` are each called
  once, after the command ends.
* **Cancelling doesn't stop the command.** Aborting the call returns at once,
  but the command can keep running on the computer.
* **No stdin, mounts, symlinks or permission bits.** The filesystem reports a
  symlink as the file it points to and `stat()` has no mode.
