---
name: polardbx-zero-pxfs
description: Mount a PolarDB-X PXFS workspace (Agent file service) as a local directory. Files are stored in a database with version history and time travel and used through ordinary file operations. Use when the user asks for a persistent agent workspace, a file system with history, or asks to mount PXFS.
compatibility: macOS only, for now — one command, native mount, needs an administrator password prompt. Prefer macOS. The Linux path is an unverified preview (needs Docker) and is still being worked on; do not present it as supported. Requires outbound access to zero.polardbx.com and to the PXFS endpoint on TCP 12049.
metadata:
  version: 0.4.1
  homepage: https://zero.polardbx.com/
---

# PolarDB-X Zero — PXFS

PXFS is a **file system backed by PolarDB-X**. Mount it once, then read and write ordinary files. History is exposed
as virtual entries at the mount root: `.snapshot` holds dated point-in-time views, and `.versions` is also present.

One claim gives you a **dedicated instance** (an exclusive PolarDB-X Enterprise base + PXFS). On that instance you can
create as many MEMBER users as you want (each with its own private home directory) and mount each of them on its own
directory.

**The instance lives for 24 hours.** When it expires — or when you release it — the instance and **everything stored
on it are destroyed**, with no warning and no recovery; the mount token expires with it. Tell the user this before
they start putting work in, and treat PXFS as scratch space: anything that must survive belongs in git or another
durable store.

## Mount it (macOS)

Two commands. The second one does everything: claims the instance if needed, signs a **MEMBER** user token whose POSIX
uid/gid matches your current macOS user, downloads and verifies the client, and mounts it. **Reads and writes work as
you: no sudo.**

```sh
curl -fsSL 'https://zero.polardbx.com/pxfs/macos-mount' -o /tmp/pxfs-mount.sh
bash /tmp/pxfs-mount.sh
```

Four things you must handle correctly:

1. **macOS shows an administrator password dialog.** The first mount attempt sometimes fails; when it does the
   script retries once and macOS asks again, so approve however many dialogs appear (usually one, sometimes two).
   Tell the user to type the password into the system dialog. Never ask for the password yourself; no TTY is
   needed. Cancelling aborts the mount.
2. **The command does not return while PXFS is mounted.** It is a foreground supervisor. Run it in a persistent
   session and keep that session open. Do not add `&`, do not close the terminal, and do not treat the
   still-running command as a hang.
3. **Success is the line `PXFS mounted successfully`.** A finished download or the password dialog alone is not
   success. The script also prints the mountpoint (default `$HOME/pxfs-<yourname>`), the endpoint, the identity, and
   the assignment id.
4. **Ctrl-C unmounts** and stops the local tunnel. The instance stays assigned to you, so you can mount again.

## Use it

Just use ordinary file operations, as your own user:

```sh
echo 'hello' > "$HOME/pxfs-$(id -un)/notes.txt"
cat "$HOME/pxfs-$(id -un)/notes.txt"
```

**If `.agents/skills/polardbx-filesystem/SKILL.md` exists in the mount root, read it before using history.** That
read-only official skill covers POSIX semantics, `.versions` and `.snapshot` time travel, checkpoints, recovery, and
quota, and is authoritative for how the file system behaves. Do not fail the task if it is absent — browse
`.snapshot` at the mount root for point-in-time views, and discover the exact layout by listing it rather than
assuming a per-file path.

Two things to know up front:

- A successful `write` is not yet a durable version. Flush, `fsync`, and close (or a publishing rename) decide what
  becomes a version.
- Hard links, symlinks, and ACLs are **not** supported.

To confirm the mount actually works — POSIX operations, durable commits, and `.versions`/`.snapshot` time travel —
read `https://zero.polardbx.com/pxfs/HEALTHCHECK.md` and run the one-command health check it describes. To measure
throughput and latency on the current network path, read `https://zero.polardbx.com/pxfs/PERFCHECK.md`.

## Speed: slow is not broken

PXFS is a **remote** NFS mount over a single TCP connection (macOS has no `nconnect`). Every operation costs one
network round trip, so anything single-threaded is latency-bound, not bandwidth-bound. Upstream measured ten 1 MiB
files over a ~42 ms path at about **28 seconds** with a serial `cp -X`, and ~20 s with four parallel workers.

- A `cp` or `cat` that takes tens of seconds is **expected**. Do not report it as a hang, a stall, or an I/O error.
- To go faster, write **several independent files concurrently**. Never have two writers share one file.
- Do not run benchmarks unless the user explicitly asks. Do not change mount options to improve a number.
- Do not move, delete, or copy the cached tunnel binary (the `tunnel` path printed at startup) while PXFS is mounted.

If I/O really is stuck (no progress at all, minutes on a small file), do **not** probe the mount with recursive
`find`, `du`, or `ls -R` — that queues more blocked round trips. Unmount that mountpoint and report:

```sh
bash /tmp/pxfs-mount.sh --release --mountpoint "$HOME/pxfs-$(id -un)"
```

## Multiple identities and mountpoints (advanced)

You can layer more users onto the same instance and mount each on its own directory. `--identity` picks the user
name; a fresh `--mountpoint` avoids collision with your first mount.

```sh
# a second MEMBER for a colleague's uid/gid — run as that user, or override
bash /tmp/pxfs-mount.sh --identity alice --mountpoint "$HOME/pxfs-alice"

# a tenant ADMIN view (sees /home, /shared and every user directory)
bash /tmp/pxfs-mount.sh --admin --mountpoint "$HOME/pxfs-admin"
```

The instance is a single billed resource. Multiple mounts share it. Treat an `--admin` mount as **read-only**: the
tenant root is not writable by your local uid, and the failure is silent — creating the file succeeds, so a shell
redirect looks like it worked, but the data write is refused and you are left with a **0-byte file** (plus an
AppleDouble `._` sibling). Always do real work inside a MEMBER mount.

## Release

Unmount the specific mountpoint (leaves the instance so other mounts keep working):

```sh
bash /tmp/pxfs-mount.sh --release --mountpoint "$HOME/pxfs-<name>"
```

Hand the whole instance back (**everything on it is destroyed**; the script refuses if any mountpoint is still up):

```sh
bash /tmp/pxfs-mount.sh --release
```

Doing nothing has the same effect once the assignment expires.

## Mount it (Linux) — unverified preview

Only the macOS path above has been verified end to end. The steps below have never been run through completely and are
still being improved. If the user has a Mac, use that instead. If Linux is the only option, tell the user up front that
this is a preview that may not work, and report exactly where it fails rather than improvising a workaround.

Requires `docker`, `mount.nfs`, and root or `sudo`. Claim first, provision a user, then mount:

```sh
CLAIM=$(curl -fsSL -X POST 'https://zero.polardbx.com/api/v1/pxfs/instances' -H 'Content-Type: application/json' -d '{}')
ASSIGN=$(echo "$CLAIM" | python3 -c 'import json,sys;print(json.load(sys.stdin)["instance"]["assignmentId"])')
SESSION=$(echo "$CLAIM" | python3 -c 'import json,sys;print(json.load(sys.stdin).get("token",""))')

USER=$(curl -fsSL -X POST "https://zero.polardbx.com/api/v1/pxfs/instances/$ASSIGN/users" \
  -H "x-pxz-token: $SESSION" -H 'Content-Type: application/json' \
  -d "{\"identityName\":\"$(id -un)\",\"role\":\"MEMBER\",\"posixUid\":$(id -u),\"posixGid\":$(id -g)}")
TOKEN=$(echo "$USER" | python3 -c 'import json,sys;print(json.load(sys.stdin)["user"]["token"])')
ENDPOINT=$(echo "$USER" | python3 -c 'import json,sys;print(json.load(sys.stdin)["user"]["endpoint"])')

curl -fsSL 'https://zero.polardbx.com/pxfs/mount' | \
  PXFS_TOKEN="$TOKEN" bash -s -- --endpoint "$ENDPOINT" --mountpoint /mnt/pxfs
```

Treat the token like a password: keep it in a `0600` file, never on a command line in shared shells, never in logs.

## Errors

| Message or symptom | What to do |
|---|---|
| `you already hold the maximum number of PXFS instances` | release the old one first: `bash /tmp/pxfs-mount.sh --release` |
| `your network has reached its PXFS instance quota` | different cause: others behind the same egress IP count too, so releasing yours may not help. Wait for one to expire, or use another network |
| `PXFS is unavailable or the warm pool is empty` | retry in a few minutes |
| `instance still provisioning` | retry in a few seconds |
| `checksum mismatch` | do not use the artifact; retry the download |
| `Permission denied` writing under `--admin` mount | expected: admin views the tenant root; do your work under a MEMBER mount |
| mount hangs, then NFS timeouts | the script auto-detects a wrong whitelisted IP, fixes it and retries — let it run. If it still fails, outbound TCP 12049 is blocked on your network |
| `mount did not come up ... Re-run the same command` | just re-run it; it is safe and force-cleans that stale mountpoint first |
| `mount attempt failed; retrying once in 5s` | intermittent; the retry normally succeeds. Approve the second password dialog |
| `401` during tunnel auth | the token was revoked or expired; re-run the mount to sign a new one |
| administrator dialog cancelled | expected abort; re-run and approve |
| mount-point I/O stalls | do not probe with `find`/`du`; run `--release --mountpoint <path>` and report |
| `... mountpoint(s) still active; unmount them first` | release each mount individually, then run `--release` again |