RemotePFS

Expose read-only NAS game files to PS5 as virtual exFAT USB storage.

Architecture · Configuration · SBC install · Troubleshooting

Why

RemotePFS presents files from one or more protocol-backed sources through a virtual, read-only exFAT filesystem. V1 supports NFS and SMB 3.1.1 through Linux's CIFS client. Future providers can reuse the same source contract. An SBC serves that filesystem through a local nbdkit Python plugin, a Linux NBD block device, and a USB mass-storage gadget. No .exfat image, loop device, or game copy is required.

Features

• Generic source contract with NFS and SMB 3.1.1/CIFS support.
• Virtual exFAT metadata generated in memory.
• nbdkit Python API v2 over a Unix socket.
• Read-only enforcement at source, NBD, and USB gadget layers.
• FastAPI localhost control plane with compile/activate generations.
• Metadata preload support through nbdsh.
• macOS-compatible unit-test and software-development path; SBC hardware is required for USB/NBD integration.

Install

RemotePFS targets a Linux SBC. macOS can run unit tests and software-only API checks, but cannot provide ConfigFS, /dev/nbd0, nbdkit, or a USB Device Controller.

uv sync
uv run --frozen pytest
uv run --frozen ruff format .
uv run --frozen ruff check .

See SBC installation for Debian/Ubuntu/Armbian deployment.

Commands

cp config/remotepfs.yaml.example /tmp/remotepfs.yaml
# Edit /tmp/remotepfs.yaml with source endpoints and SBC credential paths, then:
remotepfs compile /tmp/remotepfs.yaml
remotepfs serve --config /etc/remotepfs/remotepfs.yaml
curl http://127.0.0.1:8080/api/health

API endpoints:

• GET /api/health, /api/status, /api/config, /api/games
• POST /api/config/compile, /api/config/activate, /api/config/reload, /api/eject
• PUT /api/config

Documentation

• Configuration reference
• SBC installation and hardware checklist
• Troubleshooting and verification
• Canonical specifications
• Design decisions

Sponsor

RemotePFS is a community project for reproducible, read-only PS5 storage workflows.

Contributors

Contributions must preserve read-only behavior, update tests for observable contracts, and follow Ruff and Google-style docstrings.

Related projects

• MkPFS — project conventions reference.
• nbdkit — NBD server and filter framework.

Contributing

Use Conventional Commits. Run uv run --frozen pytest and uv run --frozen ruff check . before opening a change. Hardware-dependent validation must include SBC command output and PS5 observations; never claim those checks from macOS.