“...just as much about technological solutions as it is about the social tissue that we can nurture-culture, [as a way] to distribute ownership and establish a shared immune system.”

CoBox is an encrypted p2p file system and distributed back-up tool. With CoBox, there are no centralised servers, no data centers, and no surviellance architecture. Its just you and your peers, providing mutual support.

  • Want to create a real-time private box for you and your mates to drop in files, share projects and collaborate?
  • Want to back-up an extensive archive of videos or photos across several remote devices?
  • Scared your rampaging toddler is going to destroy your external hard drive?

Don't worry, CoBox has got you.

Our software creates encrypted private folders on your laptop, which seed and synchronise across a distributed network. A CoBox folder is a private area accessible across multiple devices - a device can be owned by another person, or it can be another computer you own. Each folder contains its own filesystem, and, under the hood, comes with an append-only log which is used to send folder-specific messages. For example:

  • Declaring information about the current device to other friends (e.g. a name)
  • Annotating files with custom metadata
  • Sending messages to other friends within the folder, privately or publicly
  • Informing other collaborators that you have invited a new peer to collaborate within the folder

Getting Started

DISCLAIMER: Please note that CoBox is experimental software still in development. We are currently in a peer review and testing phase. Therefore, use this software at your own risk. If you do use it, and/or would like to participate in giving feedback, we have made it possible to participate in providing automatic and manual feedback within the Client App.

Magma Collective, 09.03.2020

Install the App

The App is how most people will navigate CoBox. Similar to Dropbox this opens a folder on your own computer. The big difference with Dropbox is that you can then provide a code to peers running seeders and they will host an encrypted copy of your data. You will know who has your back-ups, and how many there are. You can also invite collaborators to each encrypted folder. Follow these instructions to create your own CoBox folder

Install the Seeder

You can als join the CoBox network by running a seeder, contributing to the cooperative cloud by seeding (hosting) encrypted seeds (backups) of other peoples data for them. Follow the 5 min installation instructions to set up your own seeder.


You install the CoBox App on your laptop or desktop. Using the app you can:

  1. Create private folders for you and your friends
  2. Generate and accept invite codes for folders
  3. Interact with a shared file system

For those running a seeder, in the app you can also: 4. Tell your seeder to replicate other's folders


The recommended way to download the app is through a single file binary distribution version with the one line install command below. The binary includes a copy of node and CoBox packaged inside a single file, so you just have to download one file in order to start sharing your files.

curl -o- https://cobox.cloud/releases/cobox-v1.0.0-alpha.1/download.sh | bash

You can also download with wget instead...

wget -qO- https://cobox.cloud/releases/cobox-v1.0.0-alpha.1/download.sh | bash

Once the download has completed, to complete the install, simply run the command shown, or once exported to your PATH, just run cobox.

First time setup

Now to set up CoBox for the first time, you'll want to type cobox start.

cobox start

This starts CoBox in a background process. It should also pop open the UI in the browser, where you can choose your nickname, create your first folder, and invite some friends. When its running, the app can be found at http://localhost:9112.

What happens when I close my laptop?

When you close your laptop, your CoBox app will stop syncronizing data.

To make sure your data is always available across multiple devices, you'll need other people to seed your data. There are several ways you can do this:

  1. Ask a seeder to seed your data for you.
  2. Invite friends or other computers you own into the folder. As long as they are online, you will synchronise with them.
  3. Setup your own seeder and seed your own data and for your friends. Head on over to the seeder install section to start seeding your and your friends data.

P.S. If you want CoBox to always run in the background when you start your computer, follow the instructions for pm2 startup (read more).

P. P. S. Stay tuned for a desktop and mobile application :)


Once you have the client app started, you'll be prompted to give yourself a name. This is the name by which you will be known in all your folders. You can change your name at any time, but the folders you create with the old nickname will persist (we'll work on being able to edit historical nicknames in a future release).

You can view a list of all your folders, and you can go into each of them.

Create Folders

Click the + icon and select the create a folder option, give it a name, and hey presto, you now have your very own private folder!

Using Folders

The client app can be used to check folder health, open the folder, delete the folder and invite friends. You can also see how much diskspace is being used.

Open Folder

Clicking this option will open the folder using your systems default file browser.

Folder health

This section contains your folders cobox folder address. You need to pass this cobox folder address to a Seeder admin for them to seed an encrypted copy of your folder.

When you close your laptop, your CoBox app will stop synchronizing data. To make sure your data is always available, it needs more seeders.

Invite Collaborators

If you have a friends cobox key then you can generate them a code which they can use to join your folder. The code is encrypted to their cobox key so only they can use the code. The code contains the name of the folder and provides the encryption key for the folder. This will allow them read files and write files within the folder.

Friends cannot be removed once added. Removing friends is on our Roadmap.

Accept an Invite

If you have been provided with an invite you can click the + icon from the homepage and choose the Join a folder option. You can then paste the code. You will now have access to the folder.


This action will remove the folder data from the machine you are issuing the delete action. However friends may still have copies of the data, and seeders may still retain encrypted copies.

You will need to type the name of the folder before the delete button appears. This action is not reversable, but you can join the folder again if there are other friends who still have the folder.

Seeder Install

A CoBox Seeder is the software to backup or 'seed' your files, similar to how BitTorrent seeders increase resilience. More seeders is a good thing.

The CoBox Seeder takes this concept further by introducing encrypted copies of the seeds. CoBox Seeders seed data without holding the encryption keys. That means anyone running a seeder won't be able to read the content of your files on your encrypted file system.

You can configure a stable computer, such as a Raspberry Pi in your home, or a Virtual Private Server somewhere on the Internet, to begin seeding data.

Once installed, the Seeder enables you to:

  1. Create a code to invite friends (or your other devices) to be administrators of the Seeder.
  2. Start or stop seeding peers encrypted folders (seeds).


To install or update cobox-seeder, you should run the install script. To do that, you may either download and run the script manually, or use the following cURL or Wget command:

curl -o- https://cobox.cloud/releases/cobox-seeder-v1.0.0-alpha.1/download.sh | bash
wget -qO- https://cobox.cloud/releases/cobox-seeder-v1.0.0-alpha.1/download.sh | bash

Running either of the above commands downloads a script and runs it. The script downloads a tarball that contains the release binary required by your operating system with additional assets and unpacks the contents to the install directory.

Troubleshooting on Linux

cobox-seeder: command not found: On Linux, after running the install script, if you see no feedback from your terminal after you type command -v cobox-seeder, simply close your current terminal, open a new terminal, and try verifying again.


This will start the seeder in a background process using pm2:

cobox-seeder up


Configure the seeder using $HOME/.coboxrc


Use the following command to print out the keys that you will need to use to backup data here.

cobox-seeder keys

Becoming or Adding Admins

There are a few ways of becoming an admin for a CoBox seeder.

1. During installation

When following the setup a seeder an initial admin is setup.

2. Using an Invite Code

Once you have installed the seeder you can generate an invite code to add friends (or your own devices) as an admin for this seeder.

cobox-seeder invites create <cobox-address> 

Doing so will add them as a superuser to this seeder, with the same powers as the original admin. Doing so will mean the seeder can be remote controlled from within the CoBox App.

Once the invite code has been received there are two ways to use the code.

Using the App UI

The Seeder Admin interface can be accessed in Settings > Seeders. Click the + icon and then paste the invite code in the corresponding section.

Using the App CLI

From the app CLI you can issue the following command:

cobox seeders up --code <code>

Seed a Folder

So you've been sent an address to seed someone's folder. Lets go through what you need to do. Go to Settings > Seeders > Seeder. Once inside your seeder you can then paste the folder address. Thats it! You're successfully seeding a folder using CoBox. Congratulations!

Secure your Keys

Finally, its incredibly important to back up your CoBox secret keys. If you lose this, you will no longer appear to other peers to be the same person.

Navigate to Settings > Manage Keys > Export Secret Keys. Restoring accounts using this backup will be available in v2 of CoBox.

In the future, we will make it so you can recover your old CoBox Secret Keys using a social key recovery mechanism - you'll be able to get your friends to restore your original keys!


We stand on the shoulders of giants. We've drawn on the amazing work that others have started and continue today. We've been inspired by many other projects, and we've had a lot of help along the way.

Thanks to:

Shout outs: