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

# TypeScript Quickstart

> Create a Mirage TypeScript workspace, mount RAM as a virtual filesystem, and run shell commands with @struktoai/mirage-node.

## Installation

Install the Node runtime:

```bash theme={null}
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 VFS so you can try Mirage without credentials.

```ts theme={null}
import { MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'

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

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

  await ws.close()
}

main()
```

Run it:

```bash theme={null}
pnpm tsx quickstart.ts
```

## Run Commands

Once a VFS is mounted, you can use Mirage like a shell over your virtual filesystem:

```ts theme={null}
import { MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'

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

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

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

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

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

  await ws.close()
}

main()
```

## Output Limits

To keep huge reads from flooding an agent, `cat`, `grep`, `rg`, `head`, and
`tail` cap their output at 2000 lines, and every command stops after 600
seconds. When a cap fires, the agent sees the truncated output plus a stderr
notice (`cat: output truncated at limit (2000 lines); ...`).

Set your own limits in three places. A mount's third tuple element covers
commands that run on it, `commandLimits` is the default for every session,
and a profile's `commandLimits` applies to sessions created with it:

```ts theme={null}
import { Limit, MountMode, OnExceed, RAMVFS, Workspace } from '@struktoai/mirage-node'

const ws = new Workspace(
  {
    '/data': [
      new RAMVFS(),
      MountMode.WRITE,
      { grep: new Limit({ maxLines: 50, onExceed: OnExceed.ERROR }) },
    ],
  },
  {
    mode: MountMode.WRITE,
    commandLimits: { head: new Limit({ maxLines: 500, timeoutSeconds: 30 }) },
    profiles: { researcher: { commandLimits: { head: new Limit({ maxLines: 5000 }) } } },
  },
)
ws.createSession('research', { profile: 'researcher' })
```

A command's limit comes from the first place that names it: the session's
profile, the mount the command runs on, the workspace, then the built-in
default. An entry replaces that command's whole limit, so restate
`timeoutSeconds` if you still want a deadline; commands it does not name keep
their defaults.

* `maxLines` / `maxBytes` cap the output; `null` means no cap.
* `timeoutSeconds` is a deadline; a command that runs past it exits 124.
* `onExceed: OnExceed.TRUNCATE` (default) keeps the capped output, adds a stderr
  notice, and leaves the exit code alone. `ERROR` drops the output and exits
  1, so `&&` and `||` see the failure.

Caps apply to what each command prints, one command at a time:
`cat big.txt; echo end` still prints `end`. Data going into a pipe, a
redirect, or `$(...)` is never cut, so `cat big.txt | wc -l` counts every
line. The workspace YAML takes the same fields, in snake\_case, under
`command_limits`; see
[Command limits](/home/yaml#command-limits).

## Workspace documents and sessions

See [Workspace](/home/workspace) to expose optional, profile-aware `/VFS.md` and `/SKILL.md` files and change a session's profile through the application API, CLI or HTTP.

## Next Steps

* See [TypeScript Installation](/typescript/install) for optional native peers (FUSE, Redis, Postgres, MongoDB, SSH, Email).
* Browse [TypeScript Agents](/typescript/agents/index) to wire Mirage into OpenAI Agents SDK, Vercel AI SDK, LangChain, Mastra, and more.
* Pick a real backend from the VFS section, such as [S3](/typescript/setup/s3), [Slack](/typescript/slack), or [Discord](/typescript/discord).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.