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

# VFS.md

> The Markdown file that tells an agent what is mounted and which commands work on each path.

VFS.md lists every mounted path, its layout and which Unix commands work
there, in the [VFS.md](https://agentvfs.org/vfs) format. It is built from the
live workspace and follows the session's [profile](https://docs.mirage.strukto.ai/home/policy/overview.md): a
command the profile denies, or a path it hides, is never mentioned. Each VFS
page shows its VFS.md, such as [Gmail](https://docs.mirage.strukto.ai/python/vfs/gmail.md). The CLIs are in
[SKILL.md](https://docs.mirage.strukto.ai/home/setup/cli/skill-md.md).

## Get it

> [tab] Python
>
> ```python theme={null}
> vfs_md = await ws.vfs_md()
> agent = await ws.vfs_md(session_id="agent")
> preview = await ws.vfs_md(profile="reader")
> await ws.vfs_md("/VFS.md")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> const vfsMd = await ws.vfsMd()
> const agent = await ws.vfsMd(undefined, { sessionId: 'agent' })
> const preview = await ws.vfsMd(undefined, { profile: 'reader' })
> await ws.vfsMd('/VFS.md')
> ```

> [tab] HTTP
>
> ```bash theme={null}
> curl http://127.0.0.1:8765/v1/workspaces/demo/vfs-md \
>   -H "Authorization: Bearer $MIRAGE_AUTH_TOKEN"
>
> curl -X PUT http://127.0.0.1:8765/v1/workspaces/demo/vfs-md \
>   -H "Authorization: Bearer $MIRAGE_AUTH_TOKEN" \
>   -H 'Content-Type: application/json' \
>   -d '{"path":"/VFS.md"}'
> ```

> [tab] CLI
>
> ```bash theme={null}
> mirage workspace vfs-md demo
> mirage workspace vfs-md demo --path /VFS.md
> ```

* **No session or profile**: what the workspace's default profile allows.
* **A session**: what that session's agent sees.
* **A profile**: a preview of what a session with that profile would see.
* **A path**: the file appears in the workspace, read-only and always
  current, so the agent runs `cat /VFS.md`. Each session reads its own
  version.

## What VFS.md says about each path

* **VFS**: its name, for a VFS with its own layout or its own search, such
  as Google Drive. Plain files, on `s3` or `ram` for example, show only the
  mode: which VFS holds them changes nothing an agent does.
* **Mode**: `read`, `write` or `exec`. A path whose VFS cannot change files
  shows `read`, whatever mode it is mounted with.
* **Layout**: how its files are organized and what they hold, for a VFS that
  has one. A VFS sets it with [`vfs_md`](https://docs.mirage.strukto.ai/home/setup/vfs/new#write-one).
* **Supported commands**: the Unix commands that work there, and which of them
  ask the service which files may match. CLIs such as
  [`gh`](https://docs.mirage.strukto.ai/home/setup/cli/gh) are in SKILL.md, not here.
* **Limitations**: where it differs from a local filesystem, such as being
  read only, or the [`walk_limit`](https://docs.mirage.strukto.ai/home/integration/search#walk_limit) on
  large folders.

Which commands can change files depends on the methods the VFS implements;
[Adding a New VFS](https://docs.mirage.strukto.ai/home/setup/vfs/new.md) lists them.


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