git:20260818.75b906f to git:20260818.ad6ce7a

63 added, 8 removed. Audit A to A.

---

name: mount-tidb-cloud-fs

description: Mount an existing TiDB Cloud Filesystem to a local directory with the ti CLI in a clean or ephemeral environment, using TI_FS_TOKEN and TI_REGION_CODE without ti configure, TiDB Cloud API keys, a profile, or TI_FS_FILE_SYSTEM_ID. Use when an agent needs to mount, access, or persist a Drive9-backed workspace in a sandbox, CI job, container, or local machine.

---

# Mount a TiDB Cloud Filesystem

Mount an existing TiDB Cloud Filesystem without configuring a `ti` profile. Do not

use this skill to create or delete a file system or to manage its tokens.

This token-only workflow requires `ti` v0.2.1 or later. The CLI is currently in

preview; if installed behavior differs, run `ti fs mount-file-system --help` and

check the official repository: <https://github.com/tidbcloud/ti-cli>.

## Required inputs

| Input | Required | Purpose |

| --- | --- | --- |

| `TI_FS_TOKEN` | yes | Owner or scoped Filesystem token. It authenticates the request and identifies the file system. |

| `TI_REGION_CODE` | yes | Routing region, for example `aws-us-east-1`. Use `--region` only as an explicit alternative. |

| `MOUNT_PATH` | yes | Local directory where the file system will be mounted. |

| `TI_FS_FILE_SYSTEM_ID` | no | Optional consistency assertion. `ti` normally derives the ID from the token. |

The token does not remove the need for an explicit region in a clean environment.

Do not run `ti configure` or supply TiDB Cloud API keys for this workflow.

## Workflow

### 1. Validate the inputs

```bash

: "${TI_FS_TOKEN:?Set TI_FS_TOKEN to an existing Filesystem token}"

: "${TI_REGION_CODE:?Set TI_REGION_CODE to the Filesystem region}"

: "${MOUNT_PATH:?Set MOUNT_PATH to the local mount directory}"

```

Never print or log `TI_FS_TOKEN`. Let `ti` validate the token format and its remote

permissions.

### 2. Install or verify `ti`

```bash

if ! command -v ti >/dev/null 2>&1; then

curl -fsSL https://github.com/tidbcloud/ti-cli/releases/latest/download/install.sh \

| sh -s -- --yes

export PATH="$HOME/.ti/bin:$PATH"

ti --version

```

Require v0.2.1 or later. If an older version is installed, upgrade it before

mounting with `ti update`.

### 3. Prepare the mount path and driver

```bash

mkdir -p -- "$MOUNT_PATH"

```

Prefer a new or empty directory. Do not hide existing local files by mounting over

a non-empty directory unless the user explicitly intends that behavior.

- Keep the default `--driver auto` unless a specific driver is required:

+ Choose the driver by platform:

- - Linux requires `/dev/fuse` plus `fusermount3` or `fusermount`. Installing `fuse3`

- is not enough in a container unless the container can access `/dev/fuse` and has

- the permissions needed to mount it. WebDAV is not a Linux fallback in v0.2.3.

+ - On Linux, use FUSE only. Never pass `--driver webdav`; the current `ti`

+ implementation rejects WebDAV mounts on Linux.

- macOS automatically uses macFUSE when available and otherwise uses the system

WebDAV mount helper. Install macFUSE only when FUSE behavior is required.

- Windows local mounting is not supported by the v0.2.3 implementation. Use

Filesystem data-plane commands or mount from a supported Linux/macOS host.

+ On Linux, do not stop after discovering that `fusermount3` or `fusermount` is

+ missing. Attempt to install the FUSE userspace package first. Do not infer that

+ installation is impossible from a read-only workspace; run the package manager and

+ report its actual error if it fails.

+ ```bash

+ if [ "$(uname -s)" = "Linux" ] &&

+ ! command -v fusermount3 >/dev/null 2>&1 &&

+ ! command -v fusermount >/dev/null 2>&1; then

+ if [ "$(id -u)" -eq 0 ]; then

+ fuse_privilege=()

+ elif command -v sudo >/dev/null 2>&1; then

+ fuse_privilege=(sudo)

+ else

+ echo "FUSE tools are missing and root or sudo is required to install them" >&2

+ exit 1

+ fi

+ if command -v apt-get >/dev/null 2>&1; then

+ "${fuse_privilege[@]}" apt-get update

+ "${fuse_privilege[@]}" apt-get install -y fuse3

+ elif command -v dnf >/dev/null 2>&1; then

+ "${fuse_privilege[@]}" dnf install -y fuse3

+ elif command -v yum >/dev/null 2>&1; then

+ "${fuse_privilege[@]}" yum install -y fuse3 ||

+ "${fuse_privilege[@]}" yum install -y fuse

+ elif command -v apk >/dev/null 2>&1; then

+ "${fuse_privilege[@]}" apk add --no-cache fuse3

+ else

+ echo "Unsupported package manager; install fuse3 manually" >&2

+ exit 1

+ fi

+ hash -r

+ fi

+ if [ "$(uname -s)" = "Linux" ]; then

+ command -v fusermount3 >/dev/null 2>&1 ||

+ command -v fusermount >/dev/null 2>&1 ||

+ { echo "FUSE userspace tools are still unavailable" >&2; exit 1; }

+ if [ ! -c /dev/fuse ]; then

+ echo "FUSE tools are installed, but /dev/fuse is not exposed" >&2

+ echo "Expose /dev/fuse and grant mount permissions in the host or container runtime" >&2

+ exit 1

+ fi

+ ```

### 4. Mount the file system

```bash

+ mount_driver=auto

+ if [ "$(uname -s)" = "Linux" ]; then

+ mount_driver=fuse

+ fi

ti fs mount-file-system \

--mount-path "$MOUNT_PATH" \

+ --driver "$mount_driver" \

--ready-timeout 60s

```

Rely on the environment variables instead of passing `--fs-token`; command-line

arguments can be exposed through shell history or process inspection.

The mount runs in the background and returns after it is ready. Useful options:

- Add `--read-only` for inspection or when the token has no write permission.

- Add `--foreground` when debugging the mount process.

- - Add `--driver fuse` or `--driver webdav` only after checking platform support.

+ - On macOS, override `auto` with `--driver fuse` or `--driver webdav` only when

+ required. Never use `--driver webdav` on Linux.

- Use `--query` and `--output` when an agent needs a specific machine-readable

result.

### 5. Verify access

```bash

ls -la -- "$MOUNT_PATH"

```

If write access is expected, create a unique probe rather than overwriting a fixed

path. Skip this check for a read-only mount or a token without `write` permission.

```bash

probe_path="$(mktemp "$MOUNT_PATH/.ti-mount-probe.XXXXXX")"

printf 'mount probe\n' > "$probe_path"

cat -- "$probe_path"

rm -f -- "$probe_path"

```

### 6. Unmount when finished

```bash

ti fs unmount-file-system --mount-path "$MOUNT_PATH"

```

## Troubleshooting

- A missing region fails even when the token is valid. Set `TI_REGION_CODE` or pass

`--region <code>`.

- A supplied `TI_FS_FILE_SYSTEM_ID` must match the ID derived from the token.

- A scoped token can access only its allowed paths and operations. Do not assume it

permits writes.

- - On Linux, confirm both `/dev/fuse` and `fusermount3` or `fusermount` are available.

- If FUSE cannot be exposed, a local mount is not available; use `ti fs` data-plane

- commands instead.

+ - On Linux, do not treat missing FUSE userspace tools as a final blocker. Run the

+ installation workflow, then report the actual failing command or missing

+ `/dev/fuse` device or permissions. Never switch to WebDAV.

- If a background mount times out, inspect the log path reported by `ti` and retry

with `--foreground`.