> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mastra

> Wire mirage tools into a Mastra Agent via the @struktoai/mirage-agents/mastra adapter.

[Mastra](https://mastra.ai) is an opinionated TypeScript framework for AI agents and workflows. Mirage ships a tool factory that exposes a `Workspace` as five `createTool()` instances (`execute`, `readFile`, `writeFile`, `editFile`, `ls`) ready to plug into `new Agent({ tools })`.

<Note>
  Node only. The Mirage adapter is runtime-agnostic, but most Mastra setups (memory, evals, workflows) depend on Node APIs.
</Note>

## Install

```bash theme={null}
pnpm add @struktoai/mirage-agents @struktoai/mirage-node @mastra/core
```

## Usage

```ts theme={null}
import { MountMode, OpsRegistry, RAMResource, Workspace } from '@struktoai/mirage-node'
import { Agent } from '@mastra/core/agent'
import { mirageTools } from '@struktoai/mirage-agents/mastra'
import { buildSystemPrompt } from '@struktoai/mirage-agents/openai'

const ram = new RAMResource()
const ops = new OpsRegistry()
for (const op of ram.ops()) ops.register(op)
const ws = new Workspace({ '/': ram }, { mode: MountMode.WRITE, ops })

const agent = new Agent({
  id: 'mirage-ram-agent',
  name: 'Mirage RAM Agent',
  instructions: buildSystemPrompt({
    mountInfo: { '/': 'In-memory filesystem (read/write)' },
  }),
  model: 'openai/gpt-5.4-mini',
  tools: mirageTools(ws),
})

const result = await agent.generate(
  "Create /hello.txt with 'hi from mirage' and list every file under /.",
  { maxSteps: 20 },
)
console.log(result.text)
```

## Exports

| Symbol            | Purpose                                                                                                                                                                |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mirageTools(ws)` | Returns `{ execute, readFile, writeFile, editFile, ls }`, each a `createTool()` from `@mastra/core/tools` with stable `id`s (`mirage-execute`, `mirage-read-file`, …). |

### Tool reference

| Tool id             | Input                                         | Output                                   |
| ------------------- | --------------------------------------------- | ---------------------------------------- |
| `mirage-execute`    | `{ command: string }`                         | `{ stdout, stderr, exitCode }`           |
| `mirage-read-file`  | `{ path: string }`                            | `{ content? , error? }`                  |
| `mirage-write-file` | `{ path, content }`                           | `{ path }` (auto-mkdirs parent)          |
| `mirage-edit-file`  | `{ path, oldString, newString, replaceAll? }` | `{ path?, occurrences?, error? }`        |
| `mirage-ls`         | `{ path: string }`                            | `{ files?: { path, is_dir }[], error? }` |

The execute signature follows Mastra v1: `execute(inputData, context)`. You don't need to call it directly, the agent runtime invokes it on tool calls.

## Examples

* [`examples/typescript/agents/mastra/ram_mastra.ts`](https://github.com/strukto-ai/mirage/blob/main/examples/typescript/agents/mastra/ram_mastra.ts), RAM-only sandbox driven by `gpt-5.4-mini`.