ArgosFS

Get started

Build a local autonomous storage lab.

ArgosFS is a Rust project with a management CLI, FUSE mount frontend, validation scripts, retained artifact data, and experiments for recovery, placement, compatibility, and rootfs behavior.

01

Install dependencies

Use a Linux host or VM with FUSE 3 and SMART tooling. Some compatibility tests need elevated privileges.

sudo apt-get update
sudo apt-get install -y build-essential pkg-config libfuse3-dev fuse3 smartmontools
02

Build and test

Start with normal Rust checks before mounting a volume.

cargo build --release
cargo test
cargo clippy --all-targets --all-features -- -D warnings
03

Create a volume

Create a small local test volume with multiple logical disks and an erasure-coded layout.

target/release/argosfs mkfs /var/lib/argosfs/root \
  --disks 6 --k 4 --m 2 --compression zstd
04

Mount and inspect

Mount in foreground while testing, then inspect health and planner output before enabling mutation.

target/release/argosfs mount /var/lib/argosfs/root /mnt/argos-root --foreground
target/release/argosfs health /var/lib/argosfs/root --json
target/release/argosfs autopilot /var/lib/argosfs/root --dry-run --explain --json

Suggested workflow

Do not start by trusting automation.

The safest path is to build confidence in layers: compile, run unit/integration tests, create a throwaway volume, mount it, run smoke tests, inspect health output, then run autopilot in dry-run mode before any maintenance action.

Smoke

Basic mounted behavior

Create files, rename paths, test xattrs, sync writes, and unmount cleanly before running deeper experiments.

Health

Inspect disk state

Use JSON health output to confirm device discovery, capacity accounting, SMART refresh state, and stale telemetry markers.

Plan

Dry-run first

Planner explanations show selected actions and rejected alternatives without mutating the volume.

Repair

Validate after faults

After simulated failures, run fsck, journal verification, and shard recovery before trusting the mount again.

Common commands

Useful CLI surfaces.

The CLI is meant for both operation and research. Most commands can be used manually, scripted in experiments, or captured as artifacts.

Command map

What to inspect

  • health --json: disk health, capacity, parser status, and risk signals.
  • autopilot --dry-run --explain --json: planned maintenance without mutation.
  • fsck --repair: metadata, orphan, and consistency repair checks.
  • verify-journal: journal snapshot and hash-chain validation.
  • export / import: rootfs and metadata roundtrip testing.
  • metrics: Prometheus-oriented observability output for experiments.

Experiment mode

Generate artifacts instead of screenshots.

For paper-style evaluation, use the experiment scripts so results include raw records, summaries, and manifests.

scripts/compat/run_fuse_smoke.sh
scripts/compat/run_deep_roundtrip.sh /mnt/argos-root
scripts/experiments/run_all.sh --quick --output paper-data/runs/ae-quick
python3 scripts/experiments/summarize_results.py \
  paper-data/runs/ae-quick/raw \
  paper-data/runs/ae-quick

Repository

Everything starts from the GitHub repo.

Clone ArgosFS