# How to Mount the Swarm Network as a Local Filesystem Using Bee-AFS > Mount the Swarm network as a local filesystem using Bee-AFS. This FUSE client lets you access Swarm via a standard directory with POSIX file operations through the Bee HTTP API. - Repository: [Ethersphere/awesome-swarm](https://github.com/ethersphere/awesome-swarm) - Tags: how-to-guide - Published: 2026-03-01 --- **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/main/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: ```bash 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`: ```bash # 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: ```bash 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: ```bash 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: ```bash # 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`](https://github.com/ethersphere/awesome-swarm/blob/main/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.