DocsICP FilingConsole
Documentation
Home Page PolarDB PolarDB for Xscale AI and Agents Agent File Service (PXFS) Limits and FAQ

Limits and FAQ

Updated at:
Copy as MD
Product
My Favorites

This topic describes the supported scope, frequently asked questions, and currently unsupported advanced semantics of Agent File Service (PXFS).

Supported scope

The default PXFS path provides a standard file interface. Most applications only need to mount the workspace, read and write files, and continue working. You only need to review the boundaries on this page if your use case involves cross-host database concurrency, historical directory tree browsing, or rarely used advanced POSIX semantics.

Use case

Status

Recommended approach

Standard file and directory read/write

Supported

Use standard POSIX file interfaces.

append, truncate, and sparse writes

Supported

Call fsync after critical results are written.

Atomic result publishing

Supported

Write to a temporary file in the same directory, then use rename.

File-level history

Supported

<dir>/.versions/<file>/vN

Microsecond-granularity workspace snapshot reads

Supported

<dir>/.snapshot/<UTC time>/<file>

Personal and team workspaces

Supported

Personal root directory and authorized /.shared

Automatic agent reading of PXFS rules

Supported

Official polardbx-filesystem Skill

SQLite memory

Supported with specified configurations

Single host, DELETE/FULL/NORMAL

Sharing a single mutable SQLite database across hosts

Not currently supported

Pin each mutable database file to a single NFS client host.

Browsing history of deleted paths and old directory trees

Not currently supported

Keep stable paths for important files.

FAQ

Why does ls -a not show .versions or .snapshot?

.versions and .snapshot are lookup-only virtual entries. They are not guaranteed to appear in standard directory listings. Access them directly by their known paths:

ls -la /workspace/project/.versions/file.txt
cat /workspace/project/.snapshot/2026-08-29T10:30:00.123456Z/file.txt

.snapshot only available at the mount root?

No. .snapshot is a per-directory entry. To query a file in a specific directory, use .snapshot/<time>/<file> under that directory.

Why cannot I access history from the original path of a deleted file?

History queries currently use paths that are still discoverable as entry points. Searching for deleted paths by their former file names or restoring old directory trees is not currently supported. For important files that require long-term traceability, keep stable paths and use version recovery to overwrite content.

Can I modify the official Skill?

The .agents/skills/polardbx-filesystem directory is provided by PXFS and is read-only. You can add other Skills at the same level under .agents/skills without affecting the official Skill.

Can multiple agents share content?

Yes. Each token first enters its own visible root directory. After the platform enables a shared workspace, team content is delivered through the authorized /.shared directory. Do not use tokens as a sharing mechanism.

What happens when the quota is exhausted?

Write operations return a clear error. Your application should stop publishing new content, clean up unnecessary business files, or contact the platform to adjust the quota. Do not retry indefinitely.

What should I do if I receive ESTALE, an I/O error, or a network timeout?

First, stop any automatic retries that have side effects. Verify the sidecar and mount status, then reopen the target path to check the current file size and hash. For business writes that use an idempotency key, query the existing result first. If recovery is still not possible, provide the timestamp, path, operation type, error code, and sidecar logs to the platform for investigation.

Currently unsupported advanced semantics

The following advanced semantics are not currently supported:

  • hard link

  • symlink

  • xattr

  • Custom POSIX/NFSv4 ACL

  • Special inodes such as socket, device, and FIFO

  • reflink and copy_file_range fast-copy semantics

  • File locks used as a global coordination mechanism across NFS client hosts

  • Consistency guarantees specific to mmap writes

  • rename overwriting a non-empty directory

  • Using reserved names such as .versions, .snapshot, or .pxfs for business files or directories

  • A single UTF-8 path component exceeding 255 characters

These boundaries do not affect regular file operations, agent artifacts, or SQLite memory usage under the supported configurations.

Previous：SQLite in-memory modeNext：Getting Started