VelociFS

VelociFS is a practical Linux CLI that optimizes an existing Steam library (Steam + Proton) by applying safe, reversible filesystem and OS tuning. It targets real pain points like metadata storms, shadercache churn, compatdata writes, and btrfs CoW overhead.

Safety first: VelociFS never deletes data, supports --dry-run, produces rollback steps, and logs every operation.

Features

• Scan your Steam library and detect filesystem/mount options, disk type, and Steam subdirectories.
• Plan optimizations with safety profiles (safe, balanced, aggressive) and get an undo plan.
• Apply / Rollback actions with explicit confirmation.
• Doctor common problems (NTFS/exFAT issues, CoW on btrfs, ownership mismatches, HDD warnings).

Supported distros

• Debian 12/13
• Ubuntu (current releases)

Installation

cargo build --release
./target/release/velocifs --help

Quick start

# 1) Scan your Steam library
velocifs scan --path ~/.local/share/Steam

# 2) Create a safe plan
velocifs plan --path ~/.local/share/Steam --profile safe --out plan.json

# 3) Dry-run the plan to see commands
velocifs apply --plan plan.json --dry-run --yes

# 4) Apply for real (requires root for some actions)
sudo velocifs apply --plan plan.json --yes

# 5) Rollback if needed
sudo velocifs rollback --plan plan.json --yes

CLI commands

velocifs scan --path <steamlib> [--json] [--verbose]

• Detects filesystem type and mount options.
• Detects the block device, scheduler, and SSD/HDD.
• Reports btrfs subvol/compression/autodefrag if applicable.
• Discovers Steam library subdirectories:
  • steamapps/common
  • steamapps/compatdata
  • steamapps/shadercache
  • steamapps/downloading
  • steamapps/temp

velocifs plan --path <steamlib> [--profile safe|balanced|aggressive] [--dry-run] [--out plan.json]

Creates a plan describing actions and rollback steps. Profiles:

• Safe: no remounts or sysctl changes; only safe directory-level changes and recommendations.
• Balanced: includes sysctl drop-in and optional remount suggestions.
• Aggressive: more recommendations, still no unsafe journaling and no data=writeback.

velocifs apply --plan plan.json [--dry-run] [--yes]

Executes the plan in order. If an action needs root, the tool will ask you to re-run with sudo.

velocifs rollback --plan plan.json [--dry-run] [--yes]

Reverts changes where possible. For sysctl drop-ins, VelociFS restores the latest backup if it exists.

velocifs doctor --path <steamlib>

Outputs a prioritized checklist of issues:

• NTFS/exFAT warnings
• ownership/permissions mismatches
• btrfs CoW on heavy-write directories
• HDD performance warnings
• Flatpak Steam path mismatch

What changes can VelociFS make?

btrfs (primary wins)

• chattr +C on heavy-write directories:
  • steamapps/compatdata
  • steamapps/shadercache
  • steamapps/downloading
  • steamapps/temp

Important: +C only affects new files. Existing files keep their CoW extents until rewritten.

ext4 (conservative)

• Recommends noatime or relatime if not present.
• Suggests commit= with clear warnings about a larger crash window.

Generic

• Recommends a suitable I/O scheduler for SSD/NVMe or HDD.
• Optional sysctl drop-in:
  • vm.swappiness
  • vm.dirty_background_ratio
  • vm.dirty_ratio
  • vm.vfs_cache_pressure

Logs

All operations are logged to:

~/.cache/velocifs/logs/<timestamp>.log

Safety model

• No deletions.
• Dry-run prints exact commands without executing.
• Undo plan is included in every plan.
• Backups created for /etc/sysctl.d/velocifs.conf before overwriting.

FAQ

Will this break my games?

The safe profile only makes reversible changes like chattr +C on new files and recommendations. Balanced/aggressive profiles add sysctl and remount suggestions that are still conservative.

Do I need root?

Some actions (sysctl, remounts) require root. VelociFS tells you when sudo is required.

What about Flatpak Steam?

VelociFS detects the Flatpak library path (~/.var/app/com.valvesoftware.Steam/data/Steam) and warns if your target path doesn’t match.

Can I undo everything?

Yes, most changes are reversible. For chattr +C, disabling CoW on existing files isn’t fully reversible unless files are rewritten; VelociFS documents this limitation.

Development

cargo test

License

MIT