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/core1.68 or later.- An API key for the model provider. The quick start uses Anthropic, so it
needs
ANTHROPIC_API_KEY. - The
neviaCLI, signed in withnevia 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 -xzThen 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 tsxName 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.tsThe 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.2The 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
backgroundargument and the process tools. The adapter tells the agent to redirect long output to a file instead. - Output arrives at the end.
onStdoutandonStderrare 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.