Get started

Procedure

1. Verify that the mount is ready

   Run the following commands to check the mount status:

   mountpoint /workspace
   findmnt -T /workspace

   You can proceed once both commands recognize the mount point. No database login or connection configuration is required.

2. Create your first persistent file

   Run the following commands to create a workspace directory and write a test file:

   mkdir -p /workspace/my-agent
   printf 'PXFS workspace is ready.\n' > /workspace/my-agent/hello.txt
   cat /workspace/my-agent/hello.txt

   my-agent/hello.txt now belongs to your persistent workspace. Any agent, script, or container that mounts the same identity-bound PXFS can continue to read this file.

3. Create a version boundary for important content

   Regular file writes work as expected. When you want the current content to appear clearly in the history, explicitly call fsync:

   python3 - <<'PY'
   import os
   
   path = "/workspace/my-agent/hello.txt"
   with open(path, "a", encoding="utf-8") as f:
       f.write("The next run can continue from here.\n")
       f.flush()
       os.fsync(f.fileno())
   PY

4. View file version history

   Run the following commands to view the version history of a file:

   ls -la /workspace/my-agent/.versions/hello.txt
   cat /workspace/my-agent/.versions/hello.txt/v1

   .versions is a per-file read-only history entry point. Version numbers are based on the actual listing output and are sorted numerically rather than lexicographically.

5. Read the official Skill

   Run the following command to view the official PXFS Skill file:

   sed -n '1,220p' /workspace/.agents/skills/polardbx-filesystem/SKILL.md

   You can also instruct your agent directly:

   Note

   Your working directory is on PXFS. Before you begin, read .agents/skills/polardbx-filesystem/SKILL.md. Create a persistent version after completing important writes, and always ask for confirmation before performing any restore or delete operation.

What to do next

After completing the preceding steps, you have obtained the following:

• A working directory that persists beyond a single agent run.

• A set of standard file interfaces that require no changes to existing scripts.

• A history entry point indexed by version number and microsecond-level timestamps.

• An agent operation guide provided with the workspace.

Next, switch the output directory of your existing programs to PXFS. For more information, see Working with files.