Logo

Quickstart

This guide will get you up and running with ZeroFS in minutes. We'll cover installation, basic configuration, and mounting your first S3-backed filesystem. By the end, you'll have a fully functional filesystem that stores data in S3 while feeling like local storage.

Before you begin, ensure you have access to an S3-compatible storage service and the necessary credentials (access key ID and secret access key). For quick testing without external storage, you can use file:/// URLs to store data locally.

Installation

ZeroFS is distributed as a single static binary. Choose your installation method:

curl -sSfL https://sh.zerofs.net | sh

Configuration

Create a configuration file for ZeroFS:

# Initialize a config file
zerofs init

# This creates a template you can customize

Edit the configuration file with your settings:

[cache]
dir = "/var/cache/zerofs"
disk_size_gb = 10.0
memory_size_gb = 2.0    # Optional memory cache

[storage]
url = "s3://my-bucket/zerofs-data"
encryption_password = "your-secure-password"

[aws]
access_key_id = "your-access-key"
secret_access_key = "your-secret-key"
region = "us-east-1"

[servers.ninep]
addresses = ["127.0.0.1:5564"]

[servers.nfs]
addresses = ["127.0.0.1:2049"]

See all configuration options

Start ZeroFS

Now start ZeroFS with your configuration:

# Start ZeroFS with configuration file
zerofs run --config zerofs.toml

# Or use the shorthand
zerofs run -c zerofs.toml

Mount the Filesystem

With ZeroFS running, the recommended way to mount it (on Linux) is with ZeroFS's own client, zerofs mount. It connects to the 9P server, mounting as a regular user with no root or kernel module, and reconnecting on its own if the server restarts or is temporarily unavailable. You can also mount with NFS or the Linux kernel 9P client on Linux:

# Linux: ZeroFS's own client. Requires [servers.ninep] in your config.

# Create mount point
sudo mkdir -p /mnt/zerofs

# Connect to the 9P server and mount via FUSE (runs as a regular user)
zerofs mount 127.0.0.1:5564 /mnt/zerofs

# Or over a Unix socket for lower-latency local mounts:
# zerofs mount /tmp/zerofs.9p.sock /mnt/zerofs

Using NBD Block Devices

If you enabled NBD support, you can create and access block devices dynamically:

# First, ensure NBD is configured in your TOML:
# [servers.nbd]
# addresses = ["127.0.0.1:10809"]

# Mount the filesystem (if not already mounted)
sudo mount -t nfs -o vers=3,async,nolock 127.0.0.1:/ /mnt/zerofs

# Create a block device file
sudo mkdir -p /mnt/zerofs/.nbd
sudo truncate -s 10G /mnt/zerofs/.nbd/my-device

# Install nbd-client if needed
sudo apt-get install nbd-client  # Debian/Ubuntu
sudo yum install nbd              # RHEL/CentOS

# Connect to the NBD device
sudo nbd-client 127.0.0.1 10809 /dev/nbd0 -N my-device

# Create filesystem
sudo mkfs.ext4 /dev/nbd0

# Mount the block device
sudo mkdir -p /mnt/nbd0
sudo mount /dev/nbd0 /mnt/nbd0

Learn more about NBD devices

Verify It's Working

Test your new filesystem:

# Check mount
df -h /mnt/zerofs

# Create a test file
echo "Hello from ZeroFS!" > /mnt/zerofs/test.txt

# Read it back
cat /mnt/zerofs/test.txt

# Check file metadata
ls -la /mnt/zerofs/

Learn about NFS operations

What's Next?

Congratulations! You now have a fully functional filesystem backed by S3. Here are some next steps:

Was this page helpful?