Skip to main content

​
Installation

Install the Node runtime: 
pnpm add @struktoai/mirage-node
pnpm add -D tsx typescript
npm install @struktoai/mirage-node and yarn add @struktoai/mirage-node work too.

​
Create a Workspace

Start with the RAM resource so you can try Mirage without credentials. 
import { MountMode, RAMResource, Workspace } from '@struktoai/mirage-node'

async function main(): Promise<void> {
  const ws = new Workspace({ '/data': new RAMResource() }, { mode: MountMode.WRITE })

  await ws.execute('echo "hello mirage" | tee /data/hello.txt')
  const result = await ws.execute('cat /data/hello.txt')
  process.stdout.write(result.stdoutText)

  await ws.close()
}

main()
Run it: 
pnpm tsx quickstart.ts

​
Run Commands

Once a resource is mounted, you can use Mirage like a shell over your virtual filesystem: 
import { MountMode, RAMResource, Workspace } from '@struktoai/mirage-node'

async function main(): Promise<void> {
  const ws = new Workspace({ '/data': new RAMResource() }, { mode: MountMode.WRITE })

  await ws.execute(`echo '{"name": "alice"}' | tee /data/user.json`)

  const files = await ws.execute('ls /data/')
  process.stdout.write(files.stdoutText)

  const name = await ws.execute('jq ".name" /data/user.json')
  process.stdout.write(name.stdoutText)

  const match = await ws.execute('grep alice /data/user.json')
  process.stdout.write(match.stdoutText)

  await ws.close()
}

main()

​
Output Safeguards

To keep huge reads from flooding an agent, cat, grep, rg, head, and tail cap their final output at 2000 lines by default. When a cap fires, the agent sees the truncated bytes plus a stderr notice (output truncated at safeguard limit (2000 lines); ...); the exit code stays 0. Caps fire only on the terminal command of a pipeline, so cat big.txt | head -n 30 still shows 30 lines.

​
Configure per mount

Pass a commandSafeguards option keyed by mount prefix, then command. Each CommandSafeguard sets maxLines / maxBytes (output cap) and/or timeoutSeconds (deadline); onExceed is TRUNCATE (default, exit 0 plus notice) or ERROR (exit 1 plus notice): 
import {
  CommandSafeguard,
  MountMode,
  OnExceed,
  RAMResource,
  Workspace,
} from '@struktoai/mirage-node'

const ws = new Workspace(
  { '/data': new RAMResource() },
  {
    mode: MountMode.WRITE,
    commandSafeguards: {
      '/data': {
        head: new CommandSafeguard({ maxLines: 100 }), // cap, keep going
        grep: new CommandSafeguard({ maxLines: 50, onExceed: OnExceed.ERROR }),
        rg: new CommandSafeguard({ timeoutSeconds: 30 }), // deadline
      },
    },
  },
)
The same limits are available to the CLI as a command_safeguards block in the workspace YAML.

​
Next Steps

  • See TypeScript Installation for optional native peers (FUSE, Redis, Postgres, MongoDB, SSH, Email).
  • Browse TypeScript Agents to wire Mirage into OpenAI Agents SDK, Vercel AI SDK, LangChain, Mastra, and more.
  • Pick a real backend from the Resources section, such as S3, Slack, or Discord.