Mount a TiDB Cloud Filesystem

In TiDB Cloud CLI, you can mount a TiDB Cloud Filesystem when an application needs to access remote data through a local filesystem path.

Prerequisites

• Install and configure TiDB Cloud CLI.
• Select a Filesystem by passing --file-system-id, setting TI_FS_FILE_SYSTEM_ID, or supplying an FS token that identifies the Filesystem.
• Provide an FS token through --fs-token, TI_FS_TOKEN, or the local credential stored for the selected Filesystem.
• On Linux, install FUSE3 and provide access to /dev/fuse.

Choose a mount driver

Mount the Filesystem

On macOS or Linux, create a local path and mount the Filesystem in the background:

mkdir -p /path/to/workspace
ti fs mount-file-system \
  --file-system-id "<file-system-id>" \
  --mount-path /path/to/workspace

The CLI starts a background mount process and writes a local mount locator so that the drain and unmount commands can find the correct process.

Use --remote-path to expose a subtree or --read-only to prevent writes. To mount a layer or checkpoint, select the FUSE driver and pass the appropriate layer options described in the mount-file-system reference.

Mount in a container

Installing FUSE3 in an image is not sufficient. The host must expose /dev/fuse, and the container must be allowed to perform the mount. For Docker, provide settings equivalent to the following:

docker run --rm -it \
  --device /dev/fuse \
  --cap-add SYS_ADMIN \
  --security-opt apparmor=unconfined \
  --env TI_FS_TOKEN \
  --env TI_REGION_CODE \
  --env TI_FS_FILE_SYSTEM_ID \
  <image>

For Docker Compose, pass the same device, capability, security, and environment settings:

services:
  agent:
    image: <image>
    devices:
      - /dev/fuse:/dev/fuse
    cap_add:
      - SYS_ADMIN
    security_opt:
      - apparmor=unconfined
    environment:
      TI_FS_TOKEN: ${TI_FS_TOKEN}
      TI_REGION_CODE: ${TI_REGION_CODE}
      TI_FS_FILE_SYSTEM_ID: ${TI_FS_FILE_SYSTEM_ID}

Ubuntu 26.04 mount paths

Ubuntu 26.04 applies an AppArmor profile to /usr/bin/fusermount3. By default, use a path under the current user's home directory, /mnt, /media, /tmp, or /run/user/<uid> instead of /workspace.

For example:

mkdir -p "$HOME/workspace"
ti fs mount-file-system \
  --file-system-id "<file-system-id>" \
  --mount-path "$HOME/workspace"

If an application requires /workspace, add the following rules to /etc/apparmor.d/local/fusermount3:

mount fstype=@{fuse_types} options=(nosuid,nodev) options in (ro,rw,noatime,dirsync,nodiratime,noexec,sync) -> /workspace/{,**/},
umount /workspace/{,**/},

Then reload the profile:

sudo apparmor_parser -r /etc/apparmor.d/fusermount3

For related errors, see Troubleshoot TiDB Cloud CLI.

Drain or unmount

When you run unmount-file-system, the CLI automatically flushes open file handles and pending FUSE work before stopping the mount:

ti fs unmount-file-system --mount-path /path/to/workspace

If you need a durability barrier while keeping a FUSE mount online (for example, before creating a layer checkpoint), run drain-file-system explicitly. This command flushes pending writes and waits for them to complete without unmounting:

ti fs drain-file-system --mount-path /path/to/workspace --timeout 30s

What's next

• Manage TiDB Cloud Filesystem Layers and Checkpoints
• TiDB Cloud Filesystem CLI Command Reference