Logo

Quickstart

Install ZeroFS, configure a storage backend, start the server, and mount the filesystem.

To try ZeroFS without object storage, use url = "memory:///" and omit the [aws] table. The filesystem is then empty after every server restart.

Install ZeroFS

curl -fsSL https://pkgs.zerofs.net/zerofs.gpg | sudo gpg --dearmor -o /usr/share/keyrings/zerofs.gpg
echo "deb [signed-by=/usr/share/keyrings/zerofs.gpg] https://pkgs.zerofs.net/deb stable main" | sudo tee /etc/apt/sources.list.d/zerofs.list
sudo apt update
sudo apt install zerofs

The package-manager installations also provide a disabled systemd unit and a configuration skeleton under /etc/zerofs. This quickstart runs the server directly. For containers, systemd, alternate installation directories, or a build that includes the Web UI, see System integration and Docker.

Configure Storage

Generate a configuration file:

zerofs init

This writes zerofs.toml in the current directory, overwriting a file with that name if one already exists. Open it in your preferred editor and set the storage URL, encryption password, and credentials for that backend. You can put values directly in the file or keep its environment-variable placeholders. See the configuration reference for S3-compatible, Azure, and GCS settings.

Start the Server

zerofs run --config zerofs.toml

Keep that process running. The first start creates the filesystem metadata at the configured storage path.

Mount the Filesystem

Open another terminal. On Linux, use the native kernel client when DKMS can build it for your kernel. Install zerofs-kernel-client before using the first command below. The bundled FUSE client works without the ZeroFS kernel module. macOS and Linux can also use NFS.

sudo mkdir -p /mnt/zerofs
sudo mount -t zerofs \
  -o consistency=relaxed,msize=10485760 \
  127.0.0.1:5564 /mnt/zerofs

The native client is an out-of-tree module built locally by DKMS for compatible kernels; see Native kernel client for compatibility and installation. The FUSE command stays in the foreground; press Ctrl+C to unmount. For stock v9fs, Unix sockets, or FUSE client controls, see 9P file access. For NFS mount behavior and limitations, see NFS file access.

Verify the Mount

Change to the mount point you chose, then write and read a file:

cd /path/to/mount
echo "Hello from ZeroFS" > hello.txt
cat hello.txt

Monitor the Server

The generated configuration enables the RPC listener used by the terminal dashboard:

zerofs monitor --config zerofs.toml

See Monitoring and tracing for per-operation and object-store request traces.

Was this page helpful?