Agent frameworks

Mastra

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

The Mastra adapter gives a Mastra 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 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 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 shows how to install it.
  • A Nevia key file for a service account with the editor role. Use an automation key file shows how a workspace admin issues one.

Install the adapter

Invited testers only

The SDKs are in early access for invited testers. To ask for access, see Request access to Nevia.

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

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 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.

Authenticate

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

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.

Give an agent a computer

Save this as agent.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:

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:

v24.22.2

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

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.

  • 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.

On this page