# Peergos: a peer-to-peer encrypted filesystem you can self-host

> Peergos is an AGPL-3.0 Java project that layers signed, encrypted storage over IPFS and adds a private social graph. It is for people who want to run their own encrypted storage node rather than rent one, and the README is honest that anonymity is not there yet.

**Peergos/Peergos** — A p2p, secure file storage, social network and application protocol

- Repository: https://github.com/Peergos/Peergos
- Website: https://peergos.org
- Stars: 2,530 · Forks: 200
- Language: Java
- License: AGPL-3.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/peergos-peergos

## What Peergos actually is, and who it is for

Peergos is a peer-to-peer encrypted global filesystem with fine-grained access control, plus a secure messenger, an encrypted email client and bridge, and a private social network. That is the README's own description, and it is a lot of surface area for one project. The stated aims are narrower than the feature list suggests: store files privately in a network with no central node, share them without exposing who shares with whom, run web apps from Peergos in a sandbox, and be self-hostable so a user can run it on a machine at home and get their own storage space and social platform from it.

The audience is therefore not the average Dropbox user. It is someone willing to run a JVM service, understand that a user must have at least one Peergos instance storing their data for it to be available, and accept that the network is designed to resist surveillance of data content and friendship graphs rather than to hide that you use it at all. The project's anti-aims section is unusually candid: Peergos does not provide anonymity yet, and the README suggests creating and only ever accessing an account over Tor if you want it.

One thing to note about the naming: the README says Peergos comes from the Greek Πύργος, meaning stronghold or tower, spelled phonetically with a nod to peer-to-peer. It is pronounced peer-goss, as in gossip. That is cosmetic, but it explains why searches for the project turn up unrelated results.

## The six-layer architecture: IPFS, signed writes, merkle-champ storage

The README lays out six layers. Layer 1 is peer-to-peer and data: IPFS provides storage, routing and retrieval, and the project ships its own minimal IPFS implementation called Nabu, written in Java. Layer 2 is authorization: a key pair controls who can modify parts of the filesystem, and every write is signed. Layer 3 is storage: a merkle-champ (a hash array mapped trie) of encrypted chunks sits under random labels, with no cross links visible to the server, so the README states the server cannot deduce the size of files. Layer 4 is encryption, done on the user's machine with TweetNaCl, with each 5MiB chunk of a file encrypted independently. Layer 5 is the social layer, implementing following and friendship without exposing the friend network. Layer 6 is cryptographic sharing of files with friends.

Two design decisions stand out. Encrypting each 5MiB chunk independently rather than the file as a whole means the server sees a set of unrelated blobs, which is where the size-hiding claim comes from. Random labels for the chunks do the rest. The cost is that the client does the work of assembling and decrypting, and the README gives no throughput or latency figures, so performance is an open question for anyone with large files.

Nodes are split as well. There is a pki node that ensures unique usernames using a structure similar to certificate transparency, and that data is mirrored on every Peergos server. A new node contacts any public Peergos server to join. Trust has a self-referential twist: new versions of the software are delivered through Peergos itself, and the README notes this can be turned off by the user. If you are evaluating supply-chain risk, that is the line to read twice.

## Building and running a first node from the repository

The README does not give an installation procedure. It points to a paid server at https://peergos.net/ for sign-up and to the separate web-ui repository for the interface, and the repository layout shows build.xml, reproducible-test.sh and ReproducibleJar.java at the top level, which indicates an Ant-based Java build rather than a packaged distribution. Because the README gives no install steps, the honest position is that you should treat the repository as the source of truth and start from its build files.

What the layout supports is a checkout-and-build flow. The commands below reflect the files present in the repository, not a documented procedure:

```bash
git clone https://github.com/Peergos/Peergos.git
cd Peergos
ant -f build.xml
```

The README does not document the Ant targets, so expect to read build.xml to find the one that produces a runnable server. There is also a reproducibility helper in the tree:

```bash
./reproducible-test.sh
```

That script exists to check reproducible builds, per its name and its companion ReproducibleJar.java; the README does not explain what it verifies or how long it takes.

For the client side, the README says the web interface is mostly Java cross-compiled to JavaScript, with TweetNaCl and scrypt libraries plus some Vue.js GUI code, and directs readers to https://github.com/Peergos/web-ui for screenshots and releases. If you want a working UI, you are building two repositories, and the README does not describe how they are wired together. For a first real use, the README's own suggestion is a read-only secret link to a folder on peergos.net, which shows the sharing model without requiring you to run anything:

```bash
# read-only secret link from the README
# https://peergos.net/secret/z59vuwzfFDovgun2sU9YF8LqJRVXaoVR39XAkvRR6sNp7CJnseecHhV/3647803968#oqmlU2vyq0Fe
```

Opening that link in a browser is the fastest way to see what a shared Peergos folder looks like before you spend an afternoon on the build.

## Where Peergos is the wrong tool

The clearest limitation is stated by the project itself: Peergos does not provide anonymity yet. If your threat model includes hiding the fact that you use the service, this is not the tool, and the README's mitigation (create and access the account only over Tor) is a workflow you have to enforce yourself, not a feature the software provides.

Availability is the second constraint, and it is structural rather than a bug. The README says a user must have at least one Peergos instance storing their data for it to be available. That is the price of removing the central node: your data is reachable because some node holds it, and if that node is your home machine, you own the uptime problem. A p2p network is not a backup strategy by itself.

The third is packaging. The repository has no Dockerfile in its top-level entries, and the README documents no container image, no package for a system package manager, and no mobile client. Searches for a Peergos Docker image or an iOS app are common, but nothing in the README answers them. If your deployment standard is a container, you are writing that container yourself from a Java build.

Finally, there is the trust question the README raises and does not resolve: updates arrive through Peergos itself. The README says this can be turned off, which is good, but turning it off means you take on update delivery manually, and the README does not document that path.

## Peergos compared with Nextcloud and Pydio Cells

The natural comparison is Nextcloud, which is what most self-hosters reach for, and the difference is architectural rather than cosmetic. Nextcloud is a server application: you install it, it stores your files, and encryption is a feature you enable on top of a system that still knows your account structure, your file tree and your sharing relationships. Peergos inverts that. Encryption happens on the user's machine with TweetNaCl before anything reaches storage, writes are signed by a key pair, and the chunks land in a merkle-champ under random labels so the server cannot see cross links or deduce file sizes. The server, in the README's framing, is a peer that happens to hold your data, not the authority over it.

The cost of the inversion is operational. Nextcloud has a mature install story and a large ecosystem of apps; Peergos gives you an Ant build, a separate web-ui repository, and a README that sends you to a tech book and a paid hosted server rather than a quickstart. Pydio Cells sits closer to the Nextcloud model as a self-hosted content platform, and it appears in search data alongside Peergos, but it does not share Peergos's p2p or IPFS-based design.

If your requirement is encrypted storage where the server cannot read content or map your social graph, Peergos is addressing a problem Nextcloud does not set out to solve. If your requirement is a file sync product that a non-technical team can administer, Peergos is not competing there yet, and the README does not claim it is.

## Licence, maintenance and the upgrade path

Peergos is licensed under AGPL-3.0. For anyone embedding it in a service, the practical consequence is the network-copyleft clause: if users interact with a modified version over a network, the source of that modified version has to be offered to them. That is a summary of the licence's intent, not legal advice, and it is the single most important thing to check with counsel before building a product on top of it.

On maintenance, the repository is not archived and the last push was on 2026-09-28, so the project is being worked on. The README points to release notes at https://peergos.net/public/peergos/releases and to releases in the web-ui repository, and it lists two security audits, one from 2024 and one from 2019, with reports kept in the audits directory of the repository. Those audit reports are the most concrete evidence available about the security posture, and reading them is more useful than any summary here.

The upgrade cost is unusual because of the self-hosting model. Updates are delivered through Peergos itself by default, which means the upgrade mechanism is also part of the attack surface, and the README notes it can be turned off by the user. There is no documented release cadence, no versioned distribution channel in the README, and no rollback procedure described anywhere in it. If you self-host, plan for the possibility that reverting a bad update is a manual exercise involving the build files in the repository.

## Conclusion

Peergos suits engineers who want to run their own encrypted storage node and can read Java build output when something fails; it is the wrong choice if you need an anonymity guarantee, a packaged Docker image, or a mobile client today, because the README says anonymity is not provided yet and mentions no container or iOS build. Before committing, verify the build path in the repository (build.xml, reproducible-test.sh) and whether the web interface is built from the separate web-ui repository, since the README points there for the UI but does not describe an installation procedure.

## FAQ

### Is Peergos free?

The source is licensed under AGPL-3.0 and the README says it is self-hostable, so you can run your own instance without paying for the software. The project also runs a paid server at https://peergos.net/, which is a separate hosting arrangement from the licence.

### What is peer to peer encryption in the context of Peergos?

In Peergos, encryption happens on the user's machine using TweetNaCl, with each 5MiB chunk of a file encrypted independently, and the encrypted chunks are stored under random labels in a merkle-champ. IPFS provides the peer-to-peer storage, routing and retrieval layer, so no central node holds the plaintext or the file structure.

### How do I install Peergos?

The README does not document an installation procedure. The repository contains build.xml, reproducible-test.sh and ReproducibleJar.java at the top level, which points to an Ant-based Java build, and the README directs readers to the separate web-ui repository for the interface.

### Does Peergos provide anonymity?

No. The README's anti-aims section states that Peergos does not provide anonymity yet, and suggests that anonymity can be achieved by creating and only ever accessing an account over Tor.

### What happens to my files if no Peergos node stores them?

The README states that a user must have at least one Peergos instance storing their data for it to be available. There is no central node holding a copy on your behalf, so availability depends on at least one node keeping the data.

## Sources

- [Issues](https://github.com/Peergos/Peergos/issues)
- [License: AGPL-3.0](https://github.com/Peergos/Peergos/blob/master/LICENSE)
- [Peergos/Peergos on GitHub](https://github.com/Peergos/Peergos)
- [Project website](https://peergos.org)
- [README](https://github.com/Peergos/Peergos/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/peergos-peergos