Skip to main content

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 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 }).
Node only. The Mirage adapter is runtime-agnostic, but most Mastra setups (memory, evals, workflows) depend on Node APIs.

​
Install

pnpm add @struktoai/mirage-agents @struktoai/mirage-node @mastra/core

​
Usage

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

SymbolPurpose
mirageTools(ws)Returns { execute, readFile, writeFile, editFile, ls }, each a createTool() from @mastra/core/tools with stable ids (mirage-execute, mirage-read-file, …).

​
Tool reference

Tool idInputOutput
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