PeerTube: self-hosting a federated video platform with P2P delivery

What PeerTube replaces, and for whom

PeerTube is a video platform built as an alternative to services that centralize data and attention, named in the README as YouTube, Dailymotion and Vimeo. The unit of deployment is not a global service but an instance: the project describes a network of multiple small federated, interoperable video hosting providers. You follow creators across instance boundaries, and the README states that you do not need an account on the instance where you watched a video in order to follow its author. That follow can happen from PeerTube itself, from another fediverse application such as Mastodon or Pleroma, or over RSS.

The audience splits three ways, and the README addresses each separately: viewers, content creators, and administrators. The administrator is the one who carries real weight. Running an instance means owning storage, transcoding, moderation and upgrades. The creator gets an upload endpoint and a support button that links to donation accounts. The viewer gets a web client with no recommendation feed. If you are a viewer only, you do not install anything; you join an existing instance, and the homepage links to a directory of them.

WebRTC sharing, ActivityPub federation and instance redundancy

Three mechanisms sit on top of each other, and they fail independently.

The first is delivery. Visitors use P2P with WebRTC to share the load among themselves. In practice the browser fetches segments from the origin server and from other viewers watching the same video at the same time. That reduces egress for a popular video and does nothing for a video with one viewer. It also means the benefit is a function of concurrency, not of catalogue size.

The second is federation. PeerTube speaks ActivityPub, the same protocol Mastodon uses, which is why a Mastodon account can follow a PeerTube channel. The README links a video demonstrating communication between PeerTube and Mastodon. Federation is what makes a video discoverable beyond its own instance: the README says adding a description and tags makes a video discoverable by the entire video fediverse, not just your instance.

The third is redundancy between instances. Instances can cache one another's videos. The README frames this as a way for small instances to show content to a wider audience, shouldered by friend instances, and points to a redundancy guide in the architecture documentation. This is the mechanism that separates PeerTube from a plain self-hosted media server: your catalogue can outlive your server. It is also optional, and the README does not describe a default redundancy policy.

Installing PeerTube and creating a first instance

The repository is a pnpm workspace. The root package.json declares engines of node >=22.x and pnpm >=10.9, so both must be present before anything else works. The dependency install script is frozen against the lockfile:

pnpm install --frozen-lockfile

The same script is exposed as install-node-dependencies in package.json. Because it uses --frozen-lockfile, a lockfile that does not match package.json will fail rather than resolve, which is the intended behaviour for reproducible builds.

Building is split by target. The client, the embed player, the server, the CLI and the runner each have their own script, and the aggregate build script runs them together:

pnpm run build

Individual targets are available when you only need one, for example pnpm run build:server or pnpm run build:client. The README points readers to a Create your own instance section for the full path from source to a running server, and the repository carries a config directory plus a generate-config-schema script, which is where instance configuration lives. The README does not document rollback, so plan your upgrade path before you have data you care about.

For a first real use, the fastest path is not installation at all. The homepage links to instances you can join, and the README lists demonstration instances: peertube.cpy.re for stable, peertube2.cpy.re for nightly and peertube3.cpy.re for release candidates. Watching a video there, then following the same channel from a Mastodon account, shows the federation behaviour in a few minutes without touching a server.

Where PeerTube is the wrong tool

P2P delivery is a bandwidth strategy, not an availability strategy. WebRTC sharing depends on other viewers being online and watching the same content at the same moment. For a private archive with a handful of viewers, the P2P layer contributes almost nothing and you are paying for the full cost of storage and transcoding yourself.

Discovery is the second constraint. There is no global index. Each instance decides what it lists, and the README explicitly offers the option to not list videos of an instance while still letting your users subscribe to them. That is a deliberate feature, and it also means a video can be perfectly reachable and effectively unfindable. If your requirement is that anyone searching the web finds your content, a federated instance is a worse fit than a public platform.

Moderation is the third. An instance that accepts uploads accepts the consequences of them, and federation means content decisions on one instance become visible to others. The README lists a security policy and a code of conduct in the repository, but it does not describe an automated abuse pipeline. Expect this to be human work.

Finally, the licence is AGPL-3.0. If you modify PeerTube and offer it to users over a network, the AGPL's network clause applies. That is a real constraint for anyone planning a modified hosted offering, and it is not a constraint the README discusses.

PeerTube against a plain media server or a central platform

The closest comparison is a self-hosted media server such as one built around static file hosting plus a player. That approach gives you full control over the catalogue and no federation semantics at all. There is no ActivityPub identity, so a Mastodon user cannot follow your channel, and no redundancy protocol, so another instance cannot cache your videos. You get a simpler stack and a smaller attack surface. PeerTube's difference is that the video is an actor in a social graph, not just a file behind a URL.

The other comparison is the central platform. The README's argument is about ownership and attention: no vendor lock-in, no ad model, no recommendation feed, and an interface administrators and users can change. The cost is that you now operate the thing. On a central platform someone else runs transcoding, CDN, abuse handling and upgrades. On PeerTube those are yours, and the repository's build and CI scripts (build, ci, build:server, build:client, build:peertube-cli, build:peertube-runner) exist precisely because there are several moving pieces to keep in step.

Upgrade cost, release cadence and the AGPL

The repository is not archived and the last push was on 2026-09-17. Releases arrive on a regular cadence: v8.3.0 on 2026-09-15, preceded by v8.3.0-rc.1 on 2026-08-25 and v8.2.4 on 2026-08-04. The presence of a release candidate two weeks before the stable tag suggests a staging step rather than shipping straight from develop, and the README lists a nightly and an RC demonstration instance alongside the stable one, which matches that practice.

For an operator, that cadence sets the upgrade budget. The root package.json pins Node >=22.x and pnpm >=10.9, and the install script uses --frozen-lockfile, so a Node major bump or a lockfile change is a deliberate event rather than something that happens silently. The build is scripted per target, which keeps upgrades mechanical, but the README does not document rollback or a database migration policy, so verify both against the release notes before upgrading a populated instance.

The licence is AGPL-3.0, stated in both the LICENSE file and package.json. The practical implication is the network clause: users interacting with a modified version over a network are entitled to the corresponding source. That matters if you plan to fork and host. It does not restrict running an unmodified instance. This is a description of the licence text, not legal advice; get your own if the fork is commercial.

Editorial conclusion

Adopt PeerTube if you want to run video hosting you control and can accept the operational work of a Node 22 and pnpm stack, plus the moderation load that any open upload endpoint brings. Do not adopt it if you need a single global catalogue, guaranteed playback for every viewer, or a service you never have to upgrade. Verify first that the instance you plan to join is the one you actually want to be federated with, and check whether redundancy is configured, because that setting decides whether your videos survive your own instance going down.

Frequently asked questions

Official sources

1. Chocobozzz/PeerTube on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases