How to Mount the Swarm Network as a Local Filesystem Using Bee-AFS

Bee-AFS is a FUSE-based filesystem client that mounts any Swarm Bee node as a standard local directory, enabling POSIX file operations via the Bee HTTP API without requiring native Swarm protocol knowledge.

Mounting the Swarm network as a local filesystem using Bee-AFS bridges the gap between decentralized storage and traditional file management. According to the ethersphere/awesome-swarm repository, Bee-AFS appears in the curated tools list at [README.md](https://github.com/ethersphere/awesome-swarm/blob/master/README.md) line 68, serving as the official reference for integrating Swarm with conventional filesystem workflows. This guide explains the architecture and provides runnable commands to turn your Bee node into a mountable volume.

What is Bee-AFS?

Bee-AFS (Bee Filesystem) implements a userspace filesystem driver that connects to a Bee node's HTTP API and exposes Swarm storage through the kernel's Virtual File System (VFS) layer. Unlike native Swarm interactions that require understanding content-addressed hashes and manifest structures, Bee-AFS presents a standard hierarchical directory interface compatible with existing Unix tools like cp, rsync, and text editors.

Architecture and Components

The translation from POSIX calls to Swarm operations relies on three coordinated components:

FUSE Kernel Driver

The FUSE (Filesystem in Userspace) module intercepts standard file-system calls—open, read, write, readdir, unlink—from the operating system kernel. Instead of requiring a kernel-level driver, FUSE forwards these operations to the Bee-AFS daemon running in userspace, allowing rapid development without kernel recompilation.

Bee-AFS Daemon

The daemon implements the core translation logic. It converts filesystem paths into Swarm bzz URLs and maps operations to specific Bee API endpoints:

• Uploads: Uses POST /files to store new data on the network
• Downloads: Uses GET /bytes to retrieve content by address
• Caching: Maintains a local cache of directory manifests to accelerate metadata lookups and reduce API latency

All data persistence occurs through the standard Bee REST interface, meaning the daemon requires only network connectivity to the Bee node, not direct access to the underlying Swarm network.

Bee Node

The Swarm Bee node acts as the backend storage layer. Whether running locally via Docker, on a remote server, or within a testnet cluster, the node handles the actual content-addressed storage, erasure coding, and network propagation. Every write operation through the mount point ultimately commits data to the decentralized Swarm network.

Prerequisites and Installation

Bee-AFS requires Go 1.20 or later to compile from source. Install the binary directly from the official repository:

go install github.com/aloknerurkar/bee-afs/cmd/bee-afs@latest

Verify the installation by checking that the bee-afs binary is available in your $GOPATH/bin or $HOME/go/bin directory.

Mounting Swarm as a Local Filesystem

To create the mount point, first prepare an empty directory and then invoke the daemon with your Bee API endpoint. The following example assumes a local Bee node running on the default port 1633:

# Create the mount point directory

mkdir -p /mnt/swarm

# Mount the Swarm network

bee-afs -api http://localhost:1633 /mnt/swarm

Once executed, the /mnt/swarm directory behaves like any standard local filesystem, backed by Swarm's distributed storage.

Everyday File Operations

With the filesystem mounted, interact with Swarm using familiar command-line tools.

Writing Data to Swarm

Copy entire directory trees into the mount point to persist them on the network:

cp -r ./my-project /mnt/swarm/
ls /mnt/swarm/my-project

The cp command triggers the FUSE write operations, which the Bee-AFS daemon translates into POST /files requests to the Bee node.

Reading Files from Swarm

Access files transparently as if they were local:

cat /mnt/swarm/my-project/readme.md

Read requests resolve through the local cache first; cache misses trigger GET /bytes calls to fetch data from the Swarm network.

Unmounting the Filesystem

To safely disconnect the mount point and flush any pending operations:

# Linux

fusermount -u /mnt/swarm

# macOS

umount /mnt/swarm

Always unmount before stopping the Bee-AFS daemon to prevent stale file handles.

Summary

• Bee-AFS implements a FUSE driver that translates POSIX file operations into Swarm Bee API calls, listed officially in ethersphere/awesome-swarm at line 68 of README.md.
• The architecture separates concerns between the FUSE kernel driver (syscall interception), Bee-AFS daemon (API translation and caching), and Bee node (decentralized storage backend).
• Installation requires Go 1.20+ and the command go install github.com/aloknerurkar/bee-afs/cmd/bee-afs@latest.
• Any Bee node accessible via HTTP—local, remote, or containerized—can serve as the storage backend for the mount point.
• Standard Unix utilities (cp, cat, ls, rsync) operate transparently over the mount without requiring Swarm-specific knowledge.

Frequently Asked Questions

What is Bee-AFS and how does it differ from the native Bee API?

Bee-AFS is a FUSE-based filesystem wrapper around the Bee HTTP API. While the native API requires clients to handle content-addressed hashes, manifest uploads, and chunking logic manually, Bee-AFS abstracts these details behind standard file paths and POSIX operations, allowing existing applications to use Swarm storage without modification.

Can I use Bee-AFS with a remote Bee node?

Yes. Because Bee-AFS communicates over the standard Bee REST API, you can mount a remote node by specifying its URL in the -api flag (e.g., -api http://192.168.1.100:1633). The FUSE driver runs locally, but all storage operations target the remote Bee instance.

Does Bee-AFS cache data locally?

The Bee-AFS daemon maintains a local cache of directory manifests to speed up metadata operations like ls and stat. However, file content is generally streamed on demand; large files do not necessarily persist entirely on the local disk unless the operating system's page cache retains them.

How do I troubleshoot a failed mount?

First, verify that the Bee node is accessible via curl http://localhost:1633/health. Next, ensure the mount point directory exists and is empty. If the bee-afs command fails with permission errors, confirm that your user has permission to use FUSE (typically requires membership in the fuse group on Linux). Check daemon logs for specific API errors indicating connectivity or authentication issues with the Bee node.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}