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

> Virtualize a TiDB Cloud Filesystem or a self-hosted drive9 server from Node.

`TiDBFilesystemVFS` mounts a [TiDB Cloud Filesystem](https://www.pingcap.com/tidb/tidb-cloud-filesystem/)
through its REST API: its directories and files appear with their own names
and bytes, with no FUSE mount needed. Set up the tokens and region hosts as in [TiDB setup](https://docs.mirage.strukto.ai/home/setup/tidb.md). It ships in `@struktoai/mirage-node`.

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

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

const tidb = await TiDBFilesystemVFS.create({
  host: process.env.TIDB_FILESYSTEM_HOST!,
  token: process.env.TIDB_FILESYSTEM_TOKEN!,
})
const ws = new Workspace({ '/fs': tidb }, { mode: MountMode.WRITE })

const result = await ws.shell('mkdir -p /fs/notes && echo hello > /fs/notes/a.txt && ls /fs/notes')
console.log(result.stdoutText)
await ws.close()
```

`rootPath`, such as `/workspace`, mounts one directory. Use
`MountMode.EXEC` when `python3` or `js` should run scripts from the mount.

### Fields

**timeout** `number` (default: DEFAULT\_TIMEOUT)

Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.

**host** `string` *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** `string` *required*

The file system token, sent as a bearer token.

**rootPath** `string` (default: '/')

Directory inside the file system that becomes the mount root, such as `/projects/a` for a token scoped to it; `..` segments are refused.

Fields marked secret are redacted in snapshots.

## Authentication

`token` is the file system's owner token or a scoped token, sent as a bearer
token. `host` is the endpoint of the file system's region, such as
`https://aws-us-east-1.drive9.ai`; a token works only against its own region.

A scoped token reaches only the path it was created for, and only with the
operations it allows (`read`, `list`, `search`, `write`, `delete`). Mount it
with `rootPath` set to that path, since it cannot list the file system's
root.

TiDB Cloud Filesystem runs on the open-source
[drive9](https://github.com/mem9-ai/drive9) server, and the same VFS mounts a
self-hosted drive9 server: set `host` to its origin and `token` to an API key
it issued.

## Layout

```text theme={null}
/fs/
  notes/
    a.txt
  workspace/
    data.json
```

`/fs/notes/a.txt` is `/notes/a.txt` in the file system, or
`<rootPath>/notes/a.txt` with `rootPath` set. `..` segments in `rootPath`
are refused.

## Behavior

* **Large files:** 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.
* **Appends:** `>>` 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.
* **Moves and deletes:** `mv` is one server-side rename, for a file or a whole
  directory. `rm -r` is one recursive delete.
* **Copies:** `cp` reads the file and writes the copy, so the two never share
  content.
* **Local errors:** before a write, `mkdir` or `mv`, the mount checks the
  destination and its parents, so a missing parent, a file in the way or a
  directory target fails as it does on a local disk.
* **Extent layout:** a file in the extent layout, which only the file system's
  FUSE client writes and reads, reads as `Operation not supported`.

## 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>`.
`<mode>` is the mount's mode: `read`, `write` or `exec`. The commands shown are
those of a `write` mount.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `<mode>` |
>
> **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 <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ```markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `<mode>` |
>
> ## 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 <cmd>` or `<cmd> --help` for one command's usage.
> ```


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