Pre-alpha. Nothing is stable yet, and Unseenet has not had a security
review. Do not rely on it to protect anyone yet.
📖 Documentation: unseenet.org
What it is
In the old days, you connected to your news server. Your server
exchanged articles with other servers, and before long your post had
travelled around the world. Nobody owned Usenet. Anyone could run a
server. You could read it with any newsreader.
Unseenet brings that model back, with what we have learned since:
- Decentralized. Anyone can run a node - on a Raspberry Pi, a homelab
container, a free cloud VM. Nodes replicate groups to each other the way
Usenet servers did. No central server, no company, nobody to remove a
group or sort what you see.
- Hidden. Every node is a Tor onion service: it has no address outside
Tor, needs no public IP or port forwarding, and nobody needs to know where
it is or who is reading.
- Signed and encrypted. Every post is signed by its author's key, so
nobody else can forge or change it. Closed groups and private posts are
end-to-end encrypted; the nodes that carry them see only ciphertext.
- Hard to spam. Posting costs a little proof-of-work, and new keys must
ripen before they post cheaply - no central moderation needed.
- No algorithm - unless you write one. Your feed is newest first and a
group is its threads in order; nothing is pushed up or down for someone
else's reasons. Want friends first or a subject out of sight? Write your
own rules: they run only in your client, nobody sees them, and Show all
shows any view without them.
- Moderation without a centre. Spam reports and content labels come from
issuers and labellers you choose to follow - the project's, a group
owner's, anyone's - and only describe: your client decides what to hide,
blur or show, and the nodes decide nothing. Authors warn about their own
posts (spoiler, violence, sexual …), and an age guide sets what a child's
device shows.
- Tags and languages. Authors tag their posts with topics, a click shows
everything with a tag across your groups, and the client suggests the
language you write in - from your text, told on your own machine.
- Everything people know from today's networks, on one technique:
threaded discussions, chats, private posts, feeds you follow, sites and
pages, pictures and reactions - all articles in groups, carried the same
way.
- An open protocol. A strict profile of NNTP, specified in numbered
RFC-style documents, so others can write their own nodes and clients -
exactly like in the old days.
How it all fits together, in plain prose: How it works,
and what is hidden from whom: the threat model.
The protocol
The protocol is defined in the UN-RFC series, in rfc/ and on
unseenet.org/spec. The documents are the
authority; this code is one implementation. To change the protocol or build
something compatible, start with UN-RFC 0000 and
0001. All are drafts while Unseenet is pre-alpha, and each
says in its header what is already built (Implemented:).
This repository
The heart of Unseenet: the protocol and the code every other part builds on.
| Where | What |
|---|
| The specification | rfc/ | The UN-RFCs above. |
| The core | src/unseenet/core/, client/ | The library: articles, signing and keys, the vault, postage and key ripening, groups, profiles, pages, files; Session, which every client, bot and gateway is built on; the local client API (client/localapi/). On PyPI as unseenet. |
| The node | src/unseenet/node/, deploy/, docker/ | unseenet-node, which stores groups and peers with other nodes over Tor; its installer, systemd units and Docker image; unseenet-monitor, the operator's view; unseenet-registrar for names. |
| The command-line client | src/unseenet/cli/ | unseenet: everything the core can do, from a shell or a script. |
| The project | tools/project/, |
The build tools are in their own repositories:
unseenet-portable for the
portable builds, unseenet-bootable
for the bootable images.
Get it
| |
|---|
| Use Unseenet | The terminal client or the graphical client, portable with Tor inside, bootable from a stick, or in a browser through a web entrance. Start here: Getting started. |
| Run a node | curl -fsSL https://raw.githubusercontent.com/unseenet/unseenet/main/deploy/install-node.sh | sudo bash on Debian or Ubuntu, or Docker. Guide |
| The core and the CLI | pipx install unseenet (Python 3.11+ and tor), then unseenet --help; unseenet[language] adds a larger language model for telling what a text is written in. Build on it: Write a client. |
| Other newsreaders | Read the open groups with tin, Thunderbird and friends: Other newsreaders. |
The project's own groups, unseenet, unseenet.help and
unseenet.announce (all @ph5fc5hop5232qsz), are on the project's nodes; the
clients subscribe you on first start.
How it works
A client keeps its keys in an encrypted vault and talks to a node over Tor
(ONNTP, UN-RFC 0005). It signs every article and pays its postage; the node
checks both, stores the article and passes it to the nodes it peers with,
without knowing who wrote it or where it came in. Groups are owned by a key
whose signed manifest says who may post and how the group is shown; closed
groups and inboxes carry only ciphertext. Everything else - chats, feeds,
sites, reactions, profiles - is articles in groups too. So are spam reports
and content labels: signed statements in their issuers' channels, which a
client applies only for the people who chose to follow them.
Read it chapter by chapter: How it works.
Develop
pip install -e ".[dev]"
pytest -q # nodes on localhost, no Tor
tools/docs_check.sh serve # this repository's docs pages
Protocol changes go through the UN-RFC process (an issue first, then a
draft); code changes through ordinary pull requests. See
Development for the architecture and the
design decisions, the milestones
for what comes next, and the issues
for everything else.
Versions and releases
Semantic versioning, pre-1.0: a minor version (0.5 → 0.6) may change the
protocol, and nodes are updated first. Tags vX.Y.Z on main; the release
workflow checks the tag against __version__ and CHANGELOG.md,
publishes to PyPI and announces the
release in unseenet.announce. The newest minor version gets security and bug
fixes until the next (SECURITY.md). Clients and services
number their own releases and say which core they need.
Part of Unseenet
License
Anyone may implement the protocol; no license is needed for that.
