ArgosFS

Get started

Meet your first
ArgosFS volume.

Build from source, create a disposable host-backed volume, and mount it with FUSE. No dedicated disks are needed for this walkthrough.

Linux with /dev/fuseRust ≥ 1.87FUSE 3Two terminals
01

Install prerequisites

On Debian or Ubuntu, install FUSE 3 headers and build tools. Install Rust 1.87 or newer using your normal Rust toolchain setup.

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

Clone and build

Run these commands in a shell. Keep the repository as your working directory for the following steps.

Terminal 1 
git clone https://github.com/fwerkor/ArgosFS.git
cd ArgosFS
cargo build --release
cargo test
03

Create a test volume

Use a fresh temporary directory for a six-member, 4+2 host volume. These members share your host storage; they do not provide six independent physical failure domains.

Terminal 1 
ARGOSFS_LAB=$(mktemp -d /tmp/argosfs-lab.XXXXXX)
printf '%s\n' "$ARGOSFS_LAB"
mkdir -p "$ARGOSFS_LAB/mnt"
./target/release/argosfs mkfs "$ARGOSFS_LAB/volume" \
  --disks 6 --k 4 --m 2 --compression zstd
04

Inspect, then mount

Check health and the dry-run plan before mounting. The final command stays in the foreground; leave this terminal open.

Terminal 1 
./target/release/argosfs health "$ARGOSFS_LAB/volume" --json
./target/release/argosfs autopilot "$ARGOSFS_LAB/volume" \
  --dry-run --explain --json
./target/release/argosfs mount "$ARGOSFS_LAB/volume" \
  "$ARGOSFS_LAB/mnt" --foreground
05

Read, write, and unmount

In a second terminal, set ARGOSFS_LAB to the exact path printed in step 3 (replace the example below). Unmounting ends the foreground mount process. The test data remains in the temporary directory.

Terminal 2 
ARGOSFS_LAB=/tmp/argosfs-lab.REPLACE_ME
printf 'Hello, ArgosFS!\n' > "$ARGOSFS_LAB/mnt/hello.txt"
cat "$ARGOSFS_LAB/mnt/hello.txt"
sync
fusermount3 -u "$ARGOSFS_LAB/mnt"

Where to go next

Explore one layer
at a time.

CLI and volume selectors Loop images and raw pools Root filesystem integration Testing and FUSE setup

Containers must expose /dev/fuse and allow FUSE mounts. For the first run, use a Linux host or a VM with FUSE enabled.