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

# TiDB Cloud Filesystem

> Mount a TiDB Cloud Filesystem, or a self-hosted drive9 server, as a MIRAGE VFS from Node.

`TiDBFilesystemVFS` mounts a [TiDB Cloud Filesystem](https://www.pingcap.com/tidb/tidb-cloud-filesystem/)
through its REST API. Agents list, read, write, move and remove files under
the mount with ordinary shell commands, and no FUSE mount is needed.

MIRAGE ships it in `@struktoai/mirage-node`.

For tokens and regions, see [TiDB Cloud Filesystem Setup](https://docs.mirage.strukto.ai/home/setup/tidb.md).

## Node

```bash theme={null}
pnpm add @struktoai/mirage-node
```

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

const vfs = await TiDBFilesystemVFS.create(
  normalizeTiDBFilesystemConfig({
    host: process.env.TIDB_FILESYSTEM_HOST,
    token: process.env.TIDB_FILESYSTEM_TOKEN,
    root_path: '/workspace',
  }),
)
const ws = new Workspace({ '/fs': vfs }, { mode: MountMode.WRITE })
const res = await ws.shell('mkdir -p /fs/notes && echo hello > /fs/notes/a.txt && ls /fs/notes')
console.log(res.stdoutText)
```

| Field | Description |
| - | - |
| `host` required | The file system's endpoint, such as `https://aws-us-east-1.drive9.ai` for its region, or the origin of a self-hosted drive9 server. |
| `token` required, secret | The file system token, sent as a bearer token. |
| `rootPath` default `'/'` | Directory inside the file system that becomes the mount root, such as `/projects/a` for a token scoped to it; `..` segments are refused. |
| `timeout` default `30` | Seconds one request may take before it fails. |
| `walkLimit` default `1000` | Most files one command walks under a folder: `grep -r`, `find` and other walks stop there, and a larger glob, `tar -c`, `cp -r` or `rm -r` is refused. `-1` lifts the limit. |

Fields marked secret are redacted in snapshots.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with TiDB Cloud Filesystem mounted at `/<path>`.

**Rendered**

### Virtual Filesystem

| Path | Description |
| - | - |
| `/<path>` | `tidb_filesystem`, write |

#### Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

| Path | Supported |
| - | - |
| `/<path>` | Almost all Unix commands. |

#### Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| - | - |
| `/<path>` | `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |

Run `man` to list every command, and `man <cmd>` or `<cmd> --help` for one command's usage.

**Raw**

```markdown theme={null}
---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `tidb_filesystem`, write |

## Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

| Path | Supported |
| --- | --- |
| `/<path>` | Almost all Unix commands. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |

Run `man` to list every command, and `man <cmd>` or `<cmd> --help` for one command's usage.
```

## Behavior

* A file under 50,000 bytes is written with one request; a larger one goes up
  in parts, a few at a time, and reads of it stream from object storage,
  ranged when a command reads only part of it.
* `>>` onto a file of 50,000 bytes or more sends only the new bytes and the
  file's last part; a smaller file is read and written back.
* `mv` is one server-side rename, for a file or a whole directory. `rm -r`
  is one recursive delete.
* `cp` reads the file and writes the copy, so the two never share content.
* Before a write, `mkdir` or `mv`, Mirage asks the file system what the
  destination and its parents are, so a missing parent, a file in the way or a
  directory target fails as it does on a local disk.
* A file in the extent layout, which only the file system's FUSE client
  writes and reads, reads as `Operation not supported`.

See `examples/typescript/vfs/tidb_filesystem/tidb_filesystem.ts`.


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