Integrating Swarm Storage with Nextcloud Using the Nextcloud Swarm Plugin

The Nextcloud Swarm Plugin enables decentralized storage by routing Nextcloud file uploads through the Bee API to the Swarm network, storing data as immutable chunks referenced by Swarm hashes while maintaining the native Nextcloud user experience.

The Nextcloud Swarm Plugin bridges the popular self-hosted collaboration platform with Swarm's incentivized peer-to-peer storage network. According to the ethersphere/awesome-swarm repository, this integration allows Nextcloud users to store files as immutable chunks on the decentralized Swarm network while retaining the familiar Nextcloud interface for file management and sharing.

Architecture Overview

The integration operates through four interconnected layers that translate Nextcloud storage operations into Swarm network transactions.

1. Nextcloud Core – Provides the user interface, authentication, file-system abstraction, and sharing logic.
2. Nextcloud Swarm Plugin – A server-side Nextcloud app that registers a new "Swarm" storage backend.
3. Bee API – The HTTP REST interface exposed by a running Bee node. The plugin communicates with Bee to store, retrieve, and pin data.
4. Swarm Network – Stores data as immutable chunks addressed by Swarm hashes (bzz://…). The hash is returned to the plugin and persisted in Nextcloud's database as the file's reference.

Nextcloud UI  →  Plugin (PHP)  →  Bee REST API  ↔  Swarm network

When a user uploads a file, the plugin streams the content to the Bee /bytes endpoint. Bee calculates the Swarm hash and returns it, which the plugin records in Nextcloud's filecache table with the storage type marked as Swarm. During retrieval, the plugin reconstructs a download URL using /bzz/{hash} and streams the content to the client. Optional pinning ensures the Bee node retains the content locally, guaranteeing availability even if the original uploader goes offline.

For a concise description of the plugin in the awesome-swarm catalogue, see the entry on line 70 of the repository's README.

Installing the Nextcloud Swarm Plugin

Cloning the Repository

Install the plugin by cloning the source code directly into your Nextcloud applications directory and installing PHP dependencies:

# Inside your Nextcloud installation

cd apps
git clone https://github.com/MetaProvide/nextcloud-swarm-plugin.git swarm
cd swarm
composer install      # install PHP dependencies

Enabling the Application

Activate the plugin through the Nextcloud command-line interface or the web admin panel:

# Enable via occ

sudo -u www-data php occ app:enable swarm

Alternatively, navigate to Apps → Disabled apps → Swarm → Enable in the Nextcloud web interface.

Configuring the Bee Endpoint

In the Nextcloud admin settings, open Settings → Administration → Swarm and configure the following parameters:

Field	Example value
Bee API URL	http://localhost:1633
Pin uploaded files	✅ (optional)
Chunk size	4MiB (default)

These values persist in Nextcloud's config/config.php under the swarm key:

<?php
return [
    // …
    'swarm' => [
        'api_url'      => 'http://localhost:1633',
        'pin'          => true,
        'chunk_size'   => 4 * 1024 * 1024,
    ],
];

How the Plugin Handles File Operations

Uploading Files to Swarm

When a user uploads a file through the Nextcloud interface, the plugin handles the transfer to the decentralized network. In src/Service/SwarmService.php, the upload() method streams the file to the Bee node's /bytes endpoint, retrieves the calculated Swarm hash, and optionally pins the content:

// Pseudocode extracted from the plugin's source (src/Service/SwarmService.php)
public function upload(string $localPath): string
{
    $fh = fopen($localPath, 'r');
    $response = $this->httpClient->post(
        $this->config['api_url'] . '/bytes',
        ['body' => $fh, 'headers' => ['Content-Type' => 'application/octet-stream']]
    );
    $hash = json_decode($response->getBody(), true)['reference']; // Swarm hash
    if ($this->config['pin']) {
        $this->httpClient->post(
            $this->config['api_url'] . "/bytes/$hash/pin"
        );
    }
    return $hash;
}

The returned $hash is saved in Nextcloud's file metadata. Later, this hash is used to construct download URLs via the /bzz/{hash} endpoint.

Downloading Files from Swarm

During file access, the plugin retrieves content by referencing the stored Swarm hash. The download() method in src/Service/SwarmService.php fetches the data stream from the Bee API:

// When a user downloads a file, the plugin streams from Bee:
public function download(string $hash): StreamInterface
{
    $response = $this->httpClient->get(
        $this->config['api_url'] . "/bzz/$hash"
    );
    return $response->getBody(); // streamed to the client
}

Pinning Strategies

Enabling the pin configuration option ensures that the Bee node retains uploaded content in local storage. This guarantees file availability even if the original uploader's node goes offline, providing durability for critical data stored through the Nextcloud Swarm Plugin integration.

Key Source Files and Implementation Details

The plugin's functionality is distributed across several core files that handle registration, API communication, and HTTP request processing:

• src/AppInfo/Application.php – Registers the Swarm app with Nextcloud's application framework and initializes dependency injection containers.
• src/Service/SwarmService.php – Contains the core logic for uploading, pinning, and downloading content via the Bee API, including the upload() and download() methods.
• src/Controller/UploadController.php – Handles HTTP requests from Nextcloud when users initiate file storage operations, bridging the web interface with the service layer.
• config/config.php (Nextcloud installation) – Stores the Bee endpoint configuration and plugin options including api_url, pin status, and chunk_size.

These files collectively enable the seamless translation of Nextcloud storage actions into Swarm network transactions.

Summary

• The Nextcloud Swarm Plugin creates a bridge between Nextcloud's file management interface and Swarm's decentralized storage network through the Bee API.
• Files are stored as immutable chunks on Swarm and referenced by unique Swarm hashes persisted in Nextcloud's database.
• The plugin supports optional pinning to ensure content remains available on the local Bee node regardless of the original uploader's online status.
• Configuration is managed through Nextcloud's admin interface and stored in config/config.php with parameters for the Bee API URL, chunk size, and pinning behavior.
• Core functionality is implemented in src/Service/SwarmService.php, which handles the HTTP communication with Bee's /bytes and /bzz endpoints.

Frequently Asked Questions

What is the Nextcloud Swarm Plugin?

The Nextcloud Swarm Plugin is a server-side application that adds Swarm as a native storage backend to Nextcloud. It allows users to store files on the decentralized Swarm network while interacting with them through the standard Nextcloud web interface, effectively combining Nextcloud's collaboration features with Swarm's distributed durability.

How does the plugin store files on Swarm?

When a file is uploaded, the plugin streams the binary data to the Bee node's /bytes endpoint. The Bee node segments the content into immutable chunks, calculates a cryptographic hash (the Swarm reference), and distributes these chunks across the network. The plugin stores this hash in Nextcloud's filecache table, enabling future retrievals without storing the actual file data locally.

Can I pin files to ensure they remain available?

Yes. The plugin supports an optional pinning feature configurable in the Swarm settings panel. When enabled, the plugin sends a POST request to /bytes/{hash}/pin immediately after upload, instructing the Bee node to retain the content in local storage permanently. This ensures the files remain accessible even if the original uploading node disconnects from the network.

Where is the Swarm hash stored in Nextcloud?

The Swarm hash (reference) is stored in Nextcloud's filecache database table alongside standard file metadata. The plugin marks these entries with a distinct storage type identifier ("Swarm"), allowing Nextcloud to route subsequent access requests through the plugin's download methods rather than the local filesystem.

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