Docs

Torch Object Storage

FSX

POSIX-compatible mode

FSX offers a POSIX-compatible mode. This topic explains how to use the mode, its compatibility limits, and the support levels for various tools and workloads.

Background and objectives

FSX operates in performance mode by default. This mode prioritizes efficient object storage and high data read/write speeds, including sequential reads/writes of large files and cache optimization. However, the performance mode may behave differently than a standard local file system with regard to certain POSIX semantics. To address this issue, FSX provides a compatible mode (compatible_mode).

The primary objective of the compatible mode is to maximize the alignment with POSIX-compliant access behaviors of common ecosystem tools. This minimizes execution failures or exceptions caused by differences in the low-level API. It also ensures the seamless migration of existing workloads from traditional file system clients to FSX. This preserves the original behavior and logic.

Core features

When the compatible mode is enabled, FSX provides the following enhancements:

Object operations: Random writes and truncation (enlargement and shrinkage) are supported.

Attribute emulation: FSX emulates file system attributes, such as file permissions (Permission), owner/group (UID/GID), and timestamps (Timestamp).

More interfaces: FSX adds support for symlinks (Symlink), device nodes (Mknod), and other system-level interfaces.

Directory handling and error codes: FSX offers enhanced directory detection capabilities and directory renaming logic. For interfaces supported by FSX, it aligns the error codes with those of a standard POSIX system.

Configuration method

We recommend enabling this mode if your workload relies heavily on POSIX semantics. To do so, specify compatible_mode=true when mounting via FSX.

Mount command example

Key parameters

compatible_mode: Used to enable the compatible mode. To enable the mode, set the parameter value to true.

no_writeback_cache: Used to disable cache writeback. We recommend using this parameter for tool invocations, code compilation, and scenarios involving small files. However, if your workload relies heavily on caching for write performance, consider not using this parameter.

tos_allow_delete: Used to grant file deletion permissions. While this option is not strictly necessary for the compatible mode to function, it does impact the behavior of many tools.

Support matrix for common tools and workloads

The following table shows the support levels and configuration recommendations for the most common tools and workloads in the compatible mode.

✅: Supported. ❇️: Partially supported. ❌: Not supported.

Tools/Workloads	Supported or not	Description
cat/echo	✅	I/O redirection and append-only writes are supported.
vim	❇️	File editing is supported. However, temporary .swp files relating to the deletion and overwriting policy may remain due to the Vim mechanism. We recommend using a parameter policy that allows for deletion and overwriting or adjusting the editor's temporary file policy.
cp/mv	❇️	Basic copy and move operations are supported. warning Creating hard links with the cp -l command is not supported.
rsync	❇️	Data synchronization is supported, and the mode, uid, and gid attributes are preserved.
git	❇️	Core commands, including clone, init, pull, push, and checkout, are supported. Executing stash/stash pop commands may generate warning messages. This does not affect the main process. tip Frequent branch switching and writing a large number of small files in this mode are not recommended, as they may cause performance bottlenecks.
scp/sftp	✅	Basic file transfer is supported.
tar/zip/gzip	✅	Standard compression and extraction operations are supported. We recommend validating the operations in a production environment if you need to preserve timestamps and permission information.
tosutil	❇️	File uploads are supported. However, due to differences in the underlying implementation, downloading large files may be slow. Therefore, regular use for downloading large files is not recommended.
Compiling C++/Go/Java/Python/Node.js	❇️	Although compilation is supported, it takes longer overall. We recommend that you only store the source code or compilation outputs on the FSX mount point, and then compile on the local disk.
openclaw/sqlite	❇️	Basic operations are supported, but the read/write performance is moderate.
Compiling Rust	❌	Hard link issues are known to cause failures during compilation in the compatible mode. Therefore, compiling Rust in this mode is not recommended.

Last updated: 2026.05.15 10:54:37