# Integrating Swarm Storage with Nextcloud Using the Nextcloud Swarm Plugin

> Integrate Swarm storage with Nextcloud using the Swarm Plugin. Seamlessly upload files to Swarm, storing data decentrally with immutable hashes while keeping your Nextcloud experience.

- Repository: [Ethersphere/awesome-swarm](https://github.com/ethersphere/awesome-swarm)
- Tags: how-to-guide
- Published: 2026-03-01

---

**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:

```bash

# 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:

```bash

# 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`](https://github.com/ethersphere/awesome-swarm/blob/main/config/config.php) under the `swarm` key:

```php
<?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`](https://github.com/ethersphere/awesome-swarm/blob/main/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:

```php
// 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`](https://github.com/ethersphere/awesome-swarm/blob/main/src/Service/SwarmService.php) fetches the data stream from the Bee API:

```php
// 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`](https://github.com/ethersphere/awesome-swarm/blob/main/src/AppInfo/Application.php)** – Registers the Swarm app with Nextcloud's application framework and initializes dependency injection containers.
- **[`src/Service/SwarmService.php`](https://github.com/ethersphere/awesome-swarm/blob/main/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`](https://github.com/ethersphere/awesome-swarm/blob/main/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`](https://github.com/ethersphere/awesome-swarm/blob/main/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`](https://github.com/ethersphere/awesome-swarm/blob/main/config/config.php) with parameters for the Bee API URL, chunk size, and pinning behavior.
- Core functionality is implemented in [`src/Service/SwarmService.php`](https://github.com/ethersphere/awesome-swarm/blob/main/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.