### Install Mirage from Source

Source: https://docs.mirage.strukto.ai/typescript/install

Clone the Mirage repository and install dependencies from source. This is useful for contributing to Mirage or exploring examples directly.

```bash
git clone https://github.com/strukto-ai/mirage.git
cd mirage/typescript
pnpm install
pnpm -r build

```

--------------------------------

### Install Mirage Node Package

Source: https://docs.mirage.strukto.ai/typescript/install

Install the base Mirage Node package using pnpm. This includes the core runtime and is sufficient for the TypeScript Quickstart.

```bash
pnpm add @struktoai/mirage-node

```

--------------------------------

### Run TypeScript Quickstart

Source: https://docs.mirage.strukto.ai/typescript/quickstart

Execute the TypeScript quickstart file using pnpm and tsx.

```bash
pnpm tsx quickstart.ts

```

--------------------------------

### CLI execute() Examples

Source: https://docs.mirage.strukto.ai/home/shell

Command-line interface examples for executing commands with specified workspaces and sessions.

```bash
mirage execute --workspace demo --command "ls /data"
mirage execute --workspace demo --session agent-1 --command "pwd"
```

--------------------------------

### Install Paperclip CLI

Source: https://docs.mirage.strukto.ai/home/setup/paperclip

Use this command to install the Paperclip CLI. It fetches and executes an installation script.

```bash
curl -fsSL https://paperclip.gxl.ai/install.sh | bash

```

--------------------------------

### Install Mirage Browser

Source: https://docs.mirage.strukto.ai/typescript/setup/gdocs

Install the Mirage Browser package using pnpm.

```bash
pnpm add @struktoai/mirage-browser
```

--------------------------------

### Install Mirage AI CLI via Script

Source: https://docs.mirage.strukto.ai/home/install

Install the Mirage AI CLI by piping the installation script to `sh`. Ensure your system supports FUSE for mounts.

```bash
curl -fsSL https://strukto.ai/mirage/install.sh | sh

```

--------------------------------

### Install Mirage Node and PG

Source: https://docs.mirage.strukto.ai/typescript/setup/postgres

Install the necessary packages for Node.js integration with Postgres.

```bash
pnpm add @struktoai/mirage-node pg

```

--------------------------------

### Install Mirage CLI Persistently with uv tool install

Source: https://docs.mirage.strukto.ai/python/install

Installs the `mirage` CLI globally, making it available on your PATH. Use this for regular CLI usage.

```bash
uv tool install mirage-ai
```

```bash
mirage --help
```

--------------------------------

### Install Mirage AI CLI via npm

Source: https://docs.mirage.strukto.ai/home/install

Install the Mirage AI CLI globally using npm. This is an alternative to the script-based installation.

```bash
npm install -g @struktoai/mirage-cli

```

--------------------------------

### Install Dependencies

Source: https://docs.mirage.strukto.ai/python/setup/oci

Installs the necessary dependencies for OCI Object Storage integration. Ensure you have uv installed.

```bash
uv sync --extra s3
```

--------------------------------

### Setup TrelloResource in Node.js

Source: https://docs.mirage.strukto.ai/typescript/setup/trello

Initialize TrelloResource with your API key and token, then mount it into a Workspace. This example demonstrates reading Trello data.

```typescript
import { MountMode, TrelloResource, Workspace } from '@struktoai/mirage-node'

const trello = new TrelloResource({
  apiKey: process.env.TRELLO_API_KEY!,
  apiToken: process.env.TRELLO_API_TOKEN!,
})

const ws = new Workspace({ '/trello': trello }, { mode: MountMode.READ })
await ws.execute('ls /trello/')

```

--------------------------------

### Install Mirage AI from Source

Source: https://docs.mirage.strukto.ai/python/install

Clone the Mirage repository and install dependencies from source for development or contribution. Excludes the 'camel' extra to avoid conflicts.

```bash
git clone https://github.com/strukto-ai/mirage.git
cd mirage/python
uv sync --all-extras --no-extra camel
```

--------------------------------

### Install Mirage Node

Source: https://docs.mirage.strukto.ai/typescript/setup/gdocs

Install the Mirage Node package using pnpm.

```bash
pnpm add @struktoai/mirage-node
```

--------------------------------

### Install Mirage Browser and SDK

Source: https://docs.mirage.strukto.ai/typescript/setup/notion

Install the necessary packages for Mirage browser functionality and the Model Context Protocol SDK using pnpm.

```bash
pnpm add @struktoai/mirage-browser @modelcontextprotocol/sdk

```

--------------------------------

### Running Python VFS Examples with Node.js

Source: https://docs.mirage.strukto.ai/typescript/python-fs

To run the virtual file system examples, use Node.js with the experimental WASM JSPI flag enabled. Ensure you are using a compatible Node.js version.

```bash
node --experimental-wasm-jspi --import tsx/esm examples/typescript/python/vfs.ts
```

--------------------------------

### SSH Resource Example Usage

Source: https://docs.mirage.strukto.ai/python/resource/ssh

Demonstrates various file operations on a remote server via SSH, including listing directories, reading logs, searching files, and getting file metadata. Requires an asyncio event loop.

```python
import asyncio

from mirage import MountMode, Workspace
from mirage.resource.ssh import SSHConfig, SSHResource

config = SSHConfig(
    host="myserver",
    username="deploy",
    identity_file="~/.ssh/id_ed25519",
    root="/var/log",
)
resource = SSHResource(config=config)


async def main():
    ws = Workspace({"/logs": resource}, mode=MountMode.READ)

    # List remote directory
    r = await ws.execute("ls /logs/")
    print(await r.stdout_str())

    # Read last 20 lines of a log
    r = await ws.execute("tail -n 20 /logs/nginx/access.log")
    print(await r.stdout_str())

    # Search across log files
    r = await ws.execute('grep "ERROR" /logs/app.log')
    print(await r.stdout_str())

    # Find large files
    r = await ws.execute("find /logs/ -name '*.log'")
    print(await r.stdout_str())

    # File metadata
    r = await ws.execute("stat /logs/app.log")
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Example GitHub CI Filesystem Structure

Source: https://docs.mirage.strukto.ai/python/resource/github_ci

A concrete example of the filesystem layout for the GitHub CI resource, showing sample workflow and run IDs.

```plaintext
/ci/
  workflows/
    CI_12345678.json
    Deploy_87654321.json
  runs/
    CI_9876543210/
      run.json
      jobs/
        build_11111111.json
        build_11111111.log
        test_22222222.json
        test_22222222.log
      annotations.jsonl
      artifacts/
        coverage-report_55555.zip

```

--------------------------------

### Install Mirage Node and Pyodide

Source: https://docs.mirage.strukto.ai/typescript/python

Install the necessary packages for using Python execution in a Node.js environment with Mirage.

```bash
pnpm add @struktoai/mirage-node pyodide

`npm install` and `yarn add` work too. If `pyodide` isn’t installed, `python3` returns `exit=127` with a helpful stderr message, and the workspace keeps running.
```

--------------------------------

### Verify Mirage CLI Installation

Source: https://docs.mirage.strukto.ai/home/cli

Verifies the Mirage CLI installation by displaying the help message.

```bash
mirage --help
```

--------------------------------

### Install Mirage AI Python Package

Source: https://docs.mirage.strukto.ai/home/install

Use this command to install the `mirage-ai` Python library and the `mirage` CLI binary.

```bash
uv add mirage-ai

```

--------------------------------

### Install Mirage CLI

Source: https://docs.mirage.strukto.ai/home/cli

Installs the Mirage CLI using curl or package managers.

```bash
curl -fsSL https://strukto.ai/mirage/install.sh | sh
```

```bash
npm install -g @struktoai/mirage-cli
```

```bash
uv add mirage-ai
```

```bash
pip install mirage-ai
```

```bash
uvx mirage-ai
```

```bash
npx mirage
```

--------------------------------

### Install OpenHands SDK

Source: https://docs.mirage.strukto.ai/python/agents/openhands

Install the OpenHands SDK and tools using pip. This command ensures you have the necessary versions for integration with Mirage.

```bash
uv add 'mirage-ai[openhands]'
```

--------------------------------

### Install Mirage Node and Fuse Native

Source: https://docs.mirage.strukto.ai/typescript/agents/codex

Install the necessary packages for Mirage Node and FUSE integration using pnpm.

```bash
pnpm add @struktoai/mirage-node @zkochan/fuse-native

```

--------------------------------

### Install Mirage AI with extra dependencies

Source: https://docs.mirage.strukto.ai/python/quickstart

Install Mirage AI with specific extra dependencies, such as S3 support, using uv.

```bash
uv add "mirage-ai[s3]"
```

--------------------------------

### Install Mirage AI Base Package with pip

Source: https://docs.mirage.strukto.ai/python/install

Alternative command to install the base Mirage AI package if not using `uv`.

```bash
pip install mirage-ai
```

--------------------------------

### Install Mirage AI Base Package with uv

Source: https://docs.mirage.strukto.ai/python/install

Use this command to install the base Mirage AI package for local workflows.

```bash
uv add mirage-ai
```

--------------------------------

### Install Mirage Browser

Source: https://docs.mirage.strukto.ai/typescript/setup/github_ci

Install the Mirage Browser package using pnpm. This is required for using Mirage functionalities in a browser environment.

```bash
pnpm add @struktoai/mirage-browser

```

--------------------------------

### Install R2 Dependencies

Source: https://docs.mirage.strukto.ai/python/setup/r2

Install the necessary dependencies for R2 using the uv sync command. This ensures compatibility with S3.

```bash
uv sync --extra s3

```

--------------------------------

### Install Mirage with FUSE Extra

Source: https://docs.mirage.strukto.ai/python/setup/fuse

Use this command to install Mirage with FUSE support. This includes the necessary dependencies for FUSE functionality.

```bash
pip install "mirage-ai[fuse]"
```

--------------------------------

### Install Mirage AI Resource Extras

Source: https://docs.mirage.strukto.ai/python/install

Install optional dependencies for specific Mirage AI resources like S3, R2, Redis, or FUSE.

```bash
uv add "mirage-ai[s3]"
```

```bash
uv add "mirage-ai[r2]"
```

```bash
uv add "mirage-ai[redis]"
```

```bash
uv add "mirage-ai[fuse]"
```

--------------------------------

### Usage Example: Mirage Agents with Vercel AI SDK

Source: https://docs.mirage.strukto.ai/typescript/agents/vercel

Demonstrates how to set up and use Mirage agents with the Vercel AI SDK. This example creates an in-memory workspace, defines system prompts, and uses `generateText` to interact with the workspace by creating and reading files.

```typescript
import { MountMode, OpsRegistry, RAMResource, Workspace } from '@struktoai/mirage-node'
import { generateText, stepCountIs } from 'ai'
import { openai } from '@ai-sdk/openai'
import { mirageTools } from '@struktoai/mirage-agents/vercel'
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 { text } = await generateText({
  model: openai('gpt-5.4-mini'),
  system: buildSystemPrompt({
    mountInfo: { '/': 'In-memory filesystem (read/write)' },
  }),
  prompt:
    "Create /hello.txt with 'hi from mirage' and /data/numbers.csv with 3 sample rows. " +
    'Then list and read every file back.',
  tools: mirageTools(ws),
  stopWhen: stepCountIs(20),
})

console.log(text)

```

--------------------------------

### Install Mirage Node.js Runtime

Source: https://docs.mirage.strukto.ai/typescript/quickstart

Install the Mirage Node.js runtime and tsx for running TypeScript files. npm and yarn alternatives are also supported.

```bash
pnpm add @struktoai/mirage-node
pnpm add -D tsx typescript

```

--------------------------------

### Redis Filesystem Example

Source: https://docs.mirage.strukto.ai/python/resource/redis

Demonstrates creating directories and files, reading content, listing files, copying, moving, searching, and cleaning up within the Redis filesystem.

```python
import asyncio

from mirage import MountMode, Workspace
from mirage.resource.redis import RedisResource

resource = RedisResource(url="redis://localhost:6379/0")


async def main():
    ws = Workspace({"/redis": resource}, mode=MountMode.WRITE)

    # Create directories and files
    await ws.execute("mkdir -p /redis/data/")
    await ws.execute('echo "hello world" | tee /redis/data/hello.txt')

    # Read back
    r = await ws.execute("cat /redis/data/hello.txt")
    print(await r.stdout_str())

    # List files
    r = await ws.execute("ls /redis/data/")
    print(await r.stdout_str())

    # Copy and move
    await ws.execute("cp /redis/data/hello.txt /redis/data/copy.txt")
    await ws.execute("mv /redis/data/copy.txt /redis/data/renamed.txt")

    # Search
    r = await ws.execute('grep "hello" /redis/data/')
    print(await r.stdout_str())

    # Clean up
    await ws.execute("rm -r /redis/data/")


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Install Mirage Node with Redis

Source: https://docs.mirage.strukto.ai/typescript/setup/redis

Install the necessary packages for using Redis with Mirage Node. Requires the redis@^5 peer dependency.

```bash
pnpm add @struktoai/mirage-node redis
```

--------------------------------

### Use stat for Structured Metadata

Source: https://docs.mirage.strukto.ai/python/resource/linear

Example showing how to use the `stat` command to get structured metadata about a file, which can be useful for debugging or inspection.

```bash
# Use stat for structured metadata
stat /linear/teams/ENG__Engineering__abc123/issues/ENG-123__iss_001/issue.json

```

--------------------------------

### Install Mirage Agents and Node Adapter

Source: https://docs.mirage.strukto.ai/typescript/agents/index

Install the core Mirage Agents package along with the Node.js adapter for server-side applications. For browser applications, swap `@struktoai/mirage-node` for `@struktoai/mirage-browser`.

```bash
pnpm add @struktoai/mirage-agents @struktoai/mirage-node

```

--------------------------------

### GCS Resource Example with Async Operations

Source: https://docs.mirage.strukto.ai/python/resource/gcs

Demonstrates asynchronous execution of shell commands on a mounted GCS resource, including listing directories, viewing file content, and getting file statistics. Requires '.env.development' for environment variables.

```python
import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.gcs import GCSConfig, GCSResource

load_dotenv(".env.development")

config = GCSConfig(
    bucket=os.environ["GCS_BUCKET"],
    access_key_id=os.environ["GCS_ACCESS_KEY_ID"],
    secret_access_key=os.environ["GCS_SECRET_ACCESS_KEY"],
)
resource = GCSResource(config)


async def main():
    ws = Workspace({"/gcs/": resource}, mode=MountMode.READ)

    r = await ws.execute("ls /gcs/")
    print(await r.stdout_str())

    r = await ws.execute("ls /gcs/data/")
    print(await r.stdout_str())

    r = await ws.execute("cat /gcs/data/example.json | head -n 10")
    print(await r.stdout_str())

    r = await ws.execute("tree /gcs/")
    print(await r.stdout_str())

    r = await ws.execute("stat /gcs/data/example.json")
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Using Mirage with Remote Data (Example)

Source: https://docs.mirage.strukto.ai/home/introduction

Illustrates how Mirage can be used with common Unix-like commands to interact with remote data sources, such as logs or metrics, without needing per-source plugins.

```bash
<code>tail</code>, <code>grep</code>, <code>jq</code> over remote logs, metrics, and config without per-source plugins.
```

--------------------------------

### Full Google Drive Resource Example with Async Operations

Source: https://docs.mirage.strukto.ai/python/resource/gdrive

Demonstrates various operations on a mounted Google Drive resource using an asynchronous workspace. Includes listing directories, reading files, accessing Google Workspace file metadata with `jq`, searching with `rg`, and creating a new Google Doc.

```python
import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.gdrive import GoogleDriveConfig, GoogleDriveResource

load_dotenv(".env.development")

config = GoogleDriveConfig(
    client_id=os.environ["GOOGLE_CLIENT_ID"],
    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
)
resource = GoogleDriveResource(config=config)


async def main():
    ws = Workspace({"/gdrive": resource}, mode=MountMode.READ)

    # List root
    r = await ws.execute("ls /gdrive/ | head -n 10")
    print(await r.stdout_str())

    # Browse a subfolder
    r = await ws.execute("ls /gdrive/Projects/")
    print(await r.stdout_str())

    # Read a regular file
    r = await ws.execute("cat /gdrive/Projects/spec.pdf | head -c 200")
    print(await r.stdout_str())

    # Read a Google Doc title
    r = await ws.execute('jq ".title" /gdrive/Notes/meeting.gdoc.json')
    print(await r.stdout_str())

    # Read a Google Sheet title
    r = await ws.execute(
        'jq ".properties.title" /gdrive/Projects/roadmap.gsheet.json')
    print(await r.stdout_str())

    # Read a Google Slides deck length
    r = await ws.execute(
        'jq ".slides | length"'
        " /gdrive/Presentations/quarterly_review.gslide.json")
    print(await r.stdout_str())

    # Search across all files
    r = await ws.execute('rg "quarterly" /gdrive/Projects/')
    print(await r.stdout_str())

    # Tree view
    r = await ws.execute("tree -L 2 /gdrive/")
    print(await r.stdout_str())

    # Create a new Google Doc
    r = await ws.execute(
        "gws-docs-documents-create"
        ' --json '{"title": "New Doc from MIRAGE"}\'')
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Install Mirage AI with Pydantic-AI

Source: https://docs.mirage.strukto.ai/python/agents/pydantic-ai

Install the necessary packages for Mirage AI with pydantic-ai support. This command installs `pydantic-ai>=1.35` and `pydantic-ai-backend>=0.1.0`.

```bash
uv add 'mirage-ai[pydantic-ai]'
```

--------------------------------

### Initialize Mirage Workspace and Execute Command

Source: https://docs.mirage.strukto.ai/typescript/agents/claude-code

Set up a Mirage workspace with RAM and S3 resources, mount it as a FUSE filesystem, execute a command, and then close the workspace.

```typescript
import { MountMode, RAMResource, S3Resource, Workspace } from '@struktoai/mirage-node'

const ws = new Workspace(
  {
    '/': new RAMResource(),
    '/s3/': new S3Resource({ bucket: 'my-bucket', /* ... */ }),
  },
  { mode: MountMode.WRITE, fuse: true },
)
await ws.execute('true') // wait for mount

console.log(`cd ${ws.fuseMountpoint} && claude`)
// ... run claude in another terminal, then:
await ws.close() // auto-unmounts

```

--------------------------------

### Create Workspace and Get Auth Token (Local Mode)

Source: https://docs.mirage.strukto.ai/home/auth

Demonstrates creating a workspace and retrieving the local authentication token used by the daemon. This token is typically stored in `~/.mirage/auth_token`.

```bash
mirage workspace create workspace.yaml --id demo
cat ~/.mirage/auth_token   # the token the daemon expects
```

--------------------------------

### Install Mirage AI for OpenAI Agents

Source: https://docs.mirage.strukto.ai/python/agents/openai-agents

Install the Mirage AI package with OpenAI support. This command also installs required versions of `openai` and `openai-agents`.

```bash
uv add 'mirage-ai[openai]'
```

--------------------------------

### Initialize Workspace with Multiple Resources (Python)

Source: https://docs.mirage.strukto.ai/

Mount different resource types (RAM, S3, Slack) into a workspace and execute shell commands across them. Ensure necessary resources are configured before execution.

```python
from mirage import Workspace
from mirage.resource.ram import RAMResource
from mirage.resource.s3 import S3Resource
from mirage.resource.slack import SlackResource

ws = Workspace({
    "/data": RAMResource(),
    "/s3": S3Resource(bucket="my-bucket"),
    "/slack": SlackResource(),
})

# Same shell vocabulary, three different backends.
await ws.execute('echo "hello mirage" > /data/hello.txt')
await ws.execute("ls /s3/reports/")
result = await ws.execute('grep -r "release" /slack/eng')
print(await result.stdout_str())
```

--------------------------------

### Create and use a RAM workspace

Source: https://docs.mirage.strukto.ai/python/quickstart

Demonstrates creating a Mirage workspace with RAM as a virtual filesystem, executing commands to write and read files, and closing the workspace.

```python
import asyncio

from mirage import MountMode, Workspace
from mirage.resource.ram import RAMResource


async def main() -> None:
    ws = Workspace({"/data": RAMResource()}, mode=MountMode.WRITE)

    await ws.execute('echo "hello mirage" | tee /data/hello.txt')
    result = await ws.execute("cat /data/hello.txt")
    print(await result.stdout_str())

    await ws.close()


asyncio.run(main())
```

--------------------------------

### Install Mastra Dependencies

Source: https://docs.mirage.strukto.ai/typescript/agents/mastra

Install the necessary Mastra packages using pnpm.

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

```

--------------------------------

### Configure and Use RedisResource

Source: https://docs.mirage.strukto.ai/typescript/setup/redis

Configure a RedisResource instance with a Redis URL and key prefix, then mount it into a Workspace. This example demonstrates writing to and reading from Redis keys as if they were files.

```typescript
import { MountMode, RedisResource, Workspace } from '@struktoai/mirage-node'

const redis = new RedisResource({
  url: process.env.REDIS_URL ?? 'redis://localhost:6379',
  keyPrefix: 'mirage/',
})

const ws = new Workspace({ '/r': redis }, { mode: MountMode.WRITE })
await ws.execute('echo "hello" | tee /r/greet')
await ws.execute('cat /r/greet')
```

--------------------------------

### Install MongoDB Dependency

Source: https://docs.mirage.strukto.ai/typescript/install

Install the MongoDB driver if you plan to use the MongoDBResource.

```bash
pnpm add mongodb

```

--------------------------------

### Install Pydantic Deep Agents

Source: https://docs.mirage.strukto.ai/python/agents/pydantic-ai

Install the pydantic-deep package to integrate with pydantic-deepagents.

```bash
uv add pydantic-deep
```

--------------------------------

### Example: Interact with Notion Workspace using Mirage

Source: https://docs.mirage.strukto.ai/python/resource/notion

Demonstrates various operations on a Notion workspace using the Mirage Workspace object, including listing pages, reading page content, searching, creating pages, and appending content. Requires .env.development file with NOTION_API_KEY.

```python
import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.notion import NotionConfig, NotionResource

load_dotenv(".env.development")

config = NotionConfig(api_key=os.environ["NOTION_API_KEY"])
resource = NotionResource(config=config)


async def main():
    ws = Workspace({"/notion": resource}, mode=MountMode.WRITE)

    # List top-level pages
    r = await ws.execute("ls /notion/pages/")
    print(await r.stdout_str())

    # Read a page
    r = await ws.execute(
        'cat "/notion/pages/Project-Roadmap__a1b2c3d4/page.json"'
    )
    print(await r.stdout_str())

    # Search across all pages
    r = await ws.execute('grep "deadline" /notion/pages/')
    print(await r.stdout_str())

    # Tree view
    r = await ws.execute("tree -L 2 /notion/")
    print(await r.stdout_str())

    # Create a new page
    r = await ws.execute(
        'notion-page-create --parent_id a1b2c3d4'
        ' --title "New Page" --content "Hello from Mirage"'
    )
    print(await r.stdout_str())

    # Append content to an existing page
    r = await ws.execute(
        'notion-block-append --page_id a1b2c3d4'
        ' --content "Appended paragraph"'
    )
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Install SSHResource and ssh2

Source: https://docs.mirage.strukto.ai/typescript/setup/ssh

Install the necessary packages for SSHResource functionality using pnpm.

```bash
pnpm add @struktoai/mirage-node ssh2
```

--------------------------------

### Full Google Docs Resource Example

Source: https://docs.mirage.strukto.ai/python/resource/gdocs

Demonstrates various operations including listing files, reading documents, searching, creating, and writing to Google Docs using the Workspace API.

```python
import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.gdocs import GDocsConfig, GDocsResource

load_dotenv(".env.development")

config = GDocsConfig(
    client_id=os.environ["GOOGLE_CLIENT_ID"],
    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
)
resource = GDocsResource(config=config)


async def main():
    ws = Workspace({"/gdocs": resource}, mode=MountMode.READ)

    # List structure
    r = await ws.execute("ls /gdocs/")
    print(await r.stdout_str())

    # List owned documents
    r = await ws.execute("ls /gdocs/owned/")
    print(await r.stdout_str())

    # Read a document
    r = await ws.execute(
        "cat /gdocs/owned/2026-04-04_Project_Plan__1AbCdEf.gdoc.json")
    print(await r.stdout_str())

    # Extract title with jq
    r = await ws.execute(
        'jq ".title"'
        " /gdocs/owned/2026-04-04_Project_Plan__1AbCdEf.gdoc.json")
    print(await r.stdout_str())

    # Search across all documents
    r = await ws.execute('rg "quarterly" /gdocs/owned/')
    print(await r.stdout_str())

    # Tree view
    r = await ws.execute("tree -L 1 /gdocs/")
    print(await r.stdout_str())

    # Create a new document
    r = await ws.execute(
        'gws-docs-documents-create --json '{"title":"MIRAGE Example Doc"}\'')
    print(await r.stdout_str())

    # Append text to a document
    r = await ws.execute(
        'gws-docs-write --document 1AbCdEf --text "Appended via MIRAGE."'')
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())


```

--------------------------------

### Full Example: Interacting with Google Slides Resource

Source: https://docs.mirage.strukto.ai/python/resource/gslides

Demonstrates various operations using the Google Slides resource within a Mirage Workspace, including listing files, reading presentations, searching content, and creating/updating presentations. Requires a .env.development file for credentials.

```python
import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.gslides import GSlidesConfig, GSlidesResource

load_dotenv(".env.development")

config = GSlidesConfig(
    client_id=os.environ["GOOGLE_CLIENT_ID"],
    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
)
resource = GSlidesResource(config=config)


async def main():
    ws = Workspace({"/gslides": resource}, mode=MountMode.READ)

    # List structure
    r = await ws.execute("ls /gslides/")
    print(await r.stdout_str())

    # List owned presentations
    r = await ws.execute("ls /gslides/owned/")
    print(await r.stdout_str())

    # Read a presentation
    r = await ws.execute(
        "cat /gslides/owned/2026-04-04_QBR_Deck__1AbCdEf.gslide.json")
    print(await r.stdout_str())

    # Extract title with jq
    r = await ws.execute(
        'jq ".title"'
        " /gslides/owned/2026-04-04_QBR_Deck__1AbCdEf.gslide.json")
    print(await r.stdout_str())

    # Search across all presentations
    r = await ws.execute('rg "quarterly" /gslides/owned/')
    print(await r.stdout_str())

    # Tree view
    r = await ws.execute("tree -L 1 /gslides/")
    print(await r.stdout_str())

    # Create a new presentation
    r = await ws.execute(
        'gws-slides-presentations-create --json '{"title":"MIRAGE Deck"}'")
    print(await r.stdout_str())

    # Batch update a presentation
    r = await ws.execute(
        'gws-slides-presentations-batchUpdate'
        ' --params '{"presentationId":"1AbCdEf"}'
        ' --json '{"requests":[]}'")
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Install FUSE on Arch Linux

Source: https://docs.mirage.strukto.ai/home/setup/linux

Installs the FUSE 3 package on Arch Linux.

```bash
sudo pacman -S fuse3

```

--------------------------------

### Install Mirage Node with MongoDB

Source: https://docs.mirage.strukto.ai/typescript/setup/mongodb

Install the necessary packages for using MongoDBResource in a Node.js environment.

```bash
pnpm add @struktoai/mirage-node mongodb
```

--------------------------------

### Full Gmail Resource Example with Async Operations

Source: https://docs.mirage.strukto.ai/python/resource/gmail

Demonstrates various operations on the Gmail resource using asynchronous execution within a Mirage Workspace. Includes listing labels, messages, reading emails, searching, and sending.

```python
import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.gmail import GmailConfig, GmailResource

load_dotenv(".env.development")

config = GmailConfig(
    client_id=os.environ["GOOGLE_CLIENT_ID"],
    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
)
resource = GmailResource(config=config)


async def main():
    ws = Workspace({"/gmail": resource}, mode=MountMode.READ)

    # List labels
    r = await ws.execute("ls /gmail/")
    print(await r.stdout_str())

    # List date directories in INBOX
    r = await ws.execute("ls /gmail/INBOX/")
    print(await r.stdout_str())

    # List messages for a specific date
    r = await ws.execute("ls /gmail/INBOX/2026-04-12/")
    print(await r.stdout_str())

    # Read a message
    r = await ws.execute(
        "cat /gmail/INBOX/2026-04-12/Meeting_Notes__msg123.gmail.json")
    print(await r.stdout_str())

    # Extract subject with jq
    r = await ws.execute(
        'jq ".subject"'
        " /gmail/INBOX/2026-04-12/Meeting_Notes__msg123.gmail.json")
    print(await r.stdout_str())

    # List attachments
    r = await ws.execute("ls /gmail/INBOX/2026-04-12/Meeting_Notes__msg123/")
    print(await r.stdout_str())

    # Search across all messages
    r = await ws.execute('rg "quarterly" /gmail/INBOX/')
    print(await r.stdout_str())

    # Tree view
    r = await ws.execute("tree -L 2 /gmail/INBOX/")
    print(await r.stdout_str())

    # Triage unread messages
    r = await ws.execute('--query "is:unread" --max 5')
    print(await r.stdout_str())

    # Send an email
    r = await ws.execute(
        'gws-gmail-send --to "user@example.com"'
        ' --subject "Hello from MIRAGE"'
        ' --body "This email was sent via the MIRAGE Gmail resource."')
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Verify macFUSE Installation

Source: https://docs.mirage.strukto.ai/home/setup/macos

Check if the macFUSE filesystem directory exists to confirm a successful installation.

```bash
ls /Library/Filesystems/macfuse.fs

```

--------------------------------

### Initialize and Use Email Resource

Source: https://docs.mirage.strukto.ai/python/resource/email

Demonstrates initializing the EmailResource with configuration and performing various operations like listing folders, reading messages, and sending emails using the Workspace.

```python
import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.email import EmailConfig, EmailResource

load_dotenv(".env.development")

config = EmailConfig(
    imap_host=os.environ["IMAP_HOST"],
    smtp_host=os.environ["SMTP_HOST"],
    username=os.environ["EMAIL_USERNAME"],
    password=os.environ["EMAIL_PASSWORD"],
)
resource = EmailResource(config=config)


async def main():
    ws = Workspace({"/email": resource}, mode=MountMode.READ)

    # List folders
    r = await ws.execute("ls /email/")
    print(await r.stdout_str())

    # List date directories in INBOX
    r = await ws.execute("ls /email/INBOX/")
    print(await r.stdout_str())

    # List messages for a specific date
    r = await ws.execute("ls /email/INBOX/2026-04-14/")
    print(await r.stdout_str())

    # Read a message
    r = await ws.execute(
        "cat /email/INBOX/2026-04-14/Meeting_Notes__12345.email.json")
    print(await r.stdout_str())

    # Extract subject with jq
    r = await ws.execute(
        'jq ".subject"'
        " /email/INBOX/2026-04-14/Meeting_Notes__12345.email.json")
    print(await r.stdout_str())

    # List attachments
    r = await ws.execute("ls /email/INBOX/2026-04-14/Meeting_Notes__12345/")
    print(await r.stdout_str())

    # Search across all messages
    r = await ws.execute('rg "quarterly" /email/INBOX/')
    print(await r.stdout_str())

    # Tree view
    r = await ws.execute("tree -L 2 /email/INBOX/")
    print(await r.stdout_str())

    # Triage unread messages
    r = await ws.execute("email-triage --folder INBOX --unseen --max 5")
    print(await r.stdout_str())

    # Send an email
    r = await ws.execute(
        'email-send --to "user@example.com"'
        ' --subject "Hello from MIRAGE"'
        ' --body "This email was sent via the MIRAGE email resource."')
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Install Pi Coding Agent

Source: https://docs.mirage.strukto.ai/typescript/agents/pi

Install the necessary packages for the Pi Coding Agent using pnpm.

```bash
pnpm add @struktoai/mirage-agents @struktoai/mirage-node @mariozechner/pi-coding-agent @mariozechner/pi-ai
```

--------------------------------

### Verify FUSE Installation

Source: https://docs.mirage.strukto.ai/home/setup/linux

Checks the installed version of the `fusermount3` utility to confirm FUSE is correctly set up.

```bash
fusermount3 --version

```

--------------------------------

### Create and Execute Commands with Session Mounts (Python)

Source: https://docs.mirage.strukto.ai/home/shell

Demonstrates creating sessions with restricted mount access and executing commands within those sessions. Commands accessing disallowed mounts will result in an error.

```python
ws = Workspace({
    "/s3": s3,
    "/slack": slack,
    "/linear": linear,
})

ws.create_session("slack-agent", allowed_mounts={"/slack"})
ws.create_session("data-agent", allowed_mounts={"/s3"})

await ws.execute("ls /slack", session_id="slack-agent")  # ok
await ws.execute("cat /linear/issues/SEC-42",
                 session_id="slack-agent")
# exit_code=1, stderr=b"session 'slack-agent' not allowed to "
#                     b"access mount '/linear'\n"

```

--------------------------------

### Install FUSE on Fedora/RHEL

Source: https://docs.mirage.strukto.ai/home/setup/linux

Installs the FUSE 3 package and development headers on Fedora or RHEL-based systems.

```bash
sudo dnf install fuse3 fuse3-devel

```

--------------------------------

### Node.js PostgresResource Setup

Source: https://docs.mirage.strukto.ai/typescript/setup/postgres

Connect to Postgres using a DSN and mount schemas/tables in a workspace. Execute commands against the mounted resource.

```typescript
import { MountMode, PostgresResource, Workspace } from '@struktoai/mirage-node'

const pg = new PostgresResource({
  dsn: process.env.PG_DSN!,
  schemas: ['public', 'analytics'],
})

const ws = new Workspace({ '/pg': pg }, { mode: MountMode.READ })
await ws.execute('ls /pg/public/')

```

--------------------------------

### Install macFUSE using Homebrew

Source: https://docs.mirage.strukto.ai/home/setup/macos

Use this command to install macFUSE via the Homebrew package manager.

```bash
brew install --cask macfuse

```

--------------------------------

### Install FUSE on Ubuntu/Debian

Source: https://docs.mirage.strukto.ai/home/setup/linux

Installs the FUSE 3 package and development headers on Ubuntu or Debian-based systems.

```bash
sudo apt-get install fuse3 libfuse3-dev

```

--------------------------------

### Example Usage of Supabase Resource

Source: https://docs.mirage.strukto.ai/python/resource/supabase

Demonstrates how to use the Supabase resource within a Mirage Workspace to perform common filesystem operations like listing files, reading content, and finding files. Ensure your .env.development file is loaded with necessary Supabase credentials.

```python
import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.supabase import SupabaseConfig, SupabaseResource

load_dotenv(".env.development")

config = SupabaseConfig(
    bucket=os.environ["SUPABASE_BUCKET"],
    region=os.environ["SUPABASE_REGION"],
    project_ref="oawrffhlppbtbpnehiif",
    access_key_id=os.environ["SUPABASE_ACCESS_KEY_ID"],
    secret_access_key=os.environ["SUPABASE_SECRET_ACCESS_KEY"],
)
resource = SupabaseResource(config=config)


async def main():
    ws = Workspace({"/supabase": resource}, mode=MountMode.READ)

    r = await ws.execute("ls /supabase/")
    print(await r.stdout_str())

    r = await ws.execute("cat /supabase/documents/data.csv | head -n 10")
    print(await r.stdout_str())

    r = await ws.execute("find /supabase/ -name '*.pdf'")
    print(await r.stdout_str())

    r = await ws.execute("tree -L 2 /supabase/")
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Install Mirage Agents and Langchain Dependencies

Source: https://docs.mirage.strukto.ai/typescript/agents/langchain

Install the necessary packages for deepagents, Mirage Node, and Langchain Anthropic.

```bash
pnpm add @struktoai/mirage-agents @struktoai/mirage-node deepagents @langchain/anthropic
```

--------------------------------

### R2 Example Usage

Source: https://docs.mirage.strukto.ai/python/resource/r2

Demonstrates mounting an R2 resource and executing various shell commands like 'ls', 'cat', and 'find' to interact with files in the bucket. Supports reading columnar files as formatted tables.

```python
import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.r2 import R2Config, R2Resource

load_dotenv(".env.development")

config = R2Config(
    bucket=os.environ["R2_BUCKET"],
    account_id=os.environ["R2_ACCOUNT_ID"],
    access_key_id=os.environ["R2_ACCESS_KEY_ID"],
    secret_access_key=os.environ["R2_SECRET_ACCESS_KEY"],
)
resource = R2Resource(config=config)


async def main():
    ws = Workspace({"/r2": resource}, mode=MountMode.READ)

    r = await ws.execute("ls /r2/")
    print(await r.stdout_str())

    r = await ws.execute("cat /r2/data/metrics.csv | head -n 10")
    print(await r.stdout_str())

    # Parquet files render as formatted tables
    r = await ws.execute("cat /r2/data/export.parquet")
    print(await r.stdout_str())

    r = await ws.execute("find /r2/ -name '*.csv'")
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Full Example: Interacting with GitHub CI Resource

Source: https://docs.mirage.strukto.ai/python/resource/github_ci

Demonstrates how to use the Workspace to execute shell commands against the mounted GitHub CI filesystem, including listing files, reading metadata, and viewing logs.

```python
import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.github_ci import GitHubCIConfig, GitHubCIResource

load_dotenv(".env.development")


async def main():
    config = GitHubCIConfig(
        token=os.environ["GITHUB_TOKEN"],
        owner="my-org",
        repo="my-repo",
    )
    resource = GitHubCIResource(config=config)
    ws = Workspace({"/ci": resource}, mode=MountMode.READ)

    # List top-level
    r = await ws.execute("ls /ci/")
    print(await r.stdout_str())

    # List workflows
    r = await ws.execute("ls /ci/workflows/")
    print(await r.stdout_str())

    # List recent runs
    r = await ws.execute("ls /ci/runs/")
    print(await r.stdout_str())

    # Read run metadata
    r = await ws.execute("cat /ci/runs/CI_9876543210/run.json")
    print(await r.stdout_str())

    # List jobs for a run
    r = await ws.execute("ls /ci/runs/CI_9876543210/jobs/")
    print(await r.stdout_str())

    # Read job log
    r = await ws.execute("cat /ci/runs/CI_9876543210/jobs/build_11111111.log")
    print(await r.stdout_str())

    # Read annotations
    r = await ws.execute("cat /ci/runs/CI_9876543210/annotations.jsonl")
    print(await r.stdout_str())

    # Tree view
    r = await ws.execute("tree -L 2 /ci/")
    print(await r.stdout_str())

    # Find all failed job logs
    r = await ws.execute("find /ci/runs/ -name '*.log'")
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Upgrade Mirage CLI with uv tool install

Source: https://docs.mirage.strukto.ai/python/install

Command to upgrade an existing persistent installation of the Mirage CLI.

```bash
uv tool install --upgrade mirage-ai
```

--------------------------------

### Configure and Initialize Slack Resource

Source: https://docs.mirage.strukto.ai/python/resource/slack

Set up the Slack resource by providing a bot token and initializing the Workspace. This configures the resource to be mounted at a specific path.

```python
import os

from mirage import MountMode, Workspace
from mirage.resource.slack import SlackConfig, SlackResource

config = SlackConfig(token=os.environ["SLACK_BOT_TOKEN"])
resource = SlackResource(config=config)
ws = Workspace({"/slack": resource}, mode=MountMode.READ)

```

--------------------------------

### Install DeepAgents and LangChain

Source: https://docs.mirage.strukto.ai/python/agents/langchain

Install the necessary packages for DeepAgents and LangChain, including a specific LangChain model provider.

```bash
uv add 'mirage-ai[deepagents]' langchain-anthropic

```

--------------------------------

### Allow pnpm Install Script in package.json

Source: https://docs.mirage.strukto.ai/typescript/setup/fuse

Configure pnpm to allow the install script for `@zkochan/fuse-native` when not using a pnpm workspace.

```json
{
  "pnpm": {
    "onlyBuiltDependencies": ["@zkochan/fuse-native"]
  }
}
```

--------------------------------

### Allow pnpm Install Script in Workspace

Source: https://docs.mirage.strukto.ai/typescript/setup/fuse

Configure pnpm to allow the install script for `@zkochan/fuse-native` within a pnpm workspace.

```yaml
onlyBuiltDependencies:
  - '@zkochan/fuse-native'
```

--------------------------------

### Install Email Dependencies

Source: https://docs.mirage.strukto.ai/typescript/install

Install the necessary packages for the EmailResource, which handles IMAP read, SMTP send, and MIME parsing.

```bash
pnpm add imapflow mailparser nodemailer

```

--------------------------------

### Full Slack Resource Example with Workspace Operations

Source: https://docs.mirage.strukto.ai/python/resource/slack

Demonstrates various operations on the Slack resource using the Workspace interface, including listing directories, reading messages, and searching content.

```python
import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.slack import SlackConfig, SlackResource

load_dotenv(".env.development")

config = SlackConfig(token=os.environ["SLACK_BOT_TOKEN"])
resource = SlackResource(config=config)


async def main():
    ws = Workspace({"/slack": resource}, mode=MountMode.READ)

    # List structure
    r = await ws.execute("ls /slack/")
    print(await r.stdout_str())

    # List channels
    r = await ws.execute("ls /slack/channels/")
    print(await r.stdout_str())

    ch = r.stdout_str().strip().splitlines()[0].strip()
    base = f"/slack/channels/{ch}"

    # Read messages from a specific date
    r = await ws.execute(f'cat "{base}/2026-04-04/chat.jsonl" | head -n 3')
    print(await r.stdout_str())

    # Read user profile
    r = await ws.execute("cat /slack/users/alice__U12345678.json")
    print(await r.stdout_str())

    # Extract message text with jq
    r = await ws.execute(
        f'cat "{base}/2026-04-04/chat.jsonl"'
        ' | jq -r ".[] | .text" | head -n 5')
    print(await r.stdout_str())

    # Search across channel (scans all date files)
    r = await ws.execute(f'rg message "{base}/"')
    print(await r.stdout_str())

    # Tree view
    r = await ws.execute("tree -L 1 /slack/")
    print(await r.stdout_str())

    # Navigate with cd/pwd
    await ws.execute(f'cd "{base}"')
    r = await ws.execute("pwd")
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

```