Running Your Own Mastodon Server on Cloudflare
The recent surge of interest in the Fediverse has left many users considering a move away from centralized social platforms. For those wanting to join the Mastodon network, the choice is usually between signing up on an existing community server or self-hosting the official Ruby/Node.js implementation, which also requires managing PostgreSQL and Redis. That second path is a heavy lift: it demands a VPS, careful network setup, and constant maintenance — a practical barrier for most individuals and small communities.
Wildebeest is Cloudflare's answer to that problem. It's an open-source ActivityPub server that is Mastodon-compatible and designed to run entirely on Cloudflare's edge platform. You can deploy your own instance under your own domain using your own Cloudflare account, without having to provision a traditional server or worry about patching and abuse protection.
This is not a hosted service. Your instance, code, and data live in your Cloudflare account. The project aims to give you ownership over your account and content while removing the operational overhead of running the infrastructure yourselves.
What Wildebeest Does Today
The initial release covers what's needed to participate in the Fediverse as an active member rather than a passive observer. A list of the key capabilities:
- Interoperability protocols: ActivityPub, WebFinger, NodeInfo, WebPush, and the standard Mastodon-compatible APIs. The server can both send and receive from other Fediverse instances.
- Client support: Works with popular Mastodon web clients such as Pinafore, desktop clients, and mobile apps. A simple read-only web interface is also included to browse timelines and profiles.
- Standard actions: Publish, edit, boost, and delete toots, with support for text and images (video planned soon).
- Following and search: Full federation allows others to follow you and you to follow anyone, plus content search.
- Accounts: Register one or multiple accounts on an instance. Authentication works through email or any Cloudflare Access-compatible identity provider, including GitHub and Google.
- Profiles: Edit your avatar, header image, and other profile details.
Deployment and Administration
Given that it's built on Cloudflare Workers and related products, there's no software installation or database administration on your end. You deploy the code into your account, point your domain at it, and the infrastructure handles scaling and security automatically at the edge. The project is open source, and its roadmap is driven by community pull requests and contributions.
If your reason for wanting a Mastodon instance is to create a niche community, own your data outright, or avoid other servers' policies, Wildebeest extracts the heavy engineering out of the equation — you're left with the conversation and the network.
Under the hood
Wildebeest is a Cloudflare Pages project with its application logic implemented in Pages Functions. Pages Functions provides full access to the Workers runtime, and its file-based router determines which code handles each HTTP endpoint request—the same routing approach used by frameworks like Next.js. For example, Mastodon's /api/v1/timelines/public endpoint maps to /functions/api/v1/timelines/public.ts. Because endpoint handlers are plain exported functions, unit testing is straightforward: tests call the handler directly without spinning up a server.
Functions also supports bindings to other Cloudflare products like KV, R2, D1, and Durable Objects. Wildebeest uses this to implement large parts of the official Mastodon API, which keeps it compatible with the wider Fediverse ecosystem of servers and client apps. The same Pages project also serves a read-only web frontend, with non-API requests caught by a dynamic route (/functions/[[path]].js) that hands off to Qwik City, the router inside the Qwik framework used for the frontend. Qwik adds SSR and SSG support, and Tailwind CSS handles styling. The result is a full-stack application—backend APIs and server-side-rendered client—running under one project.
Data storage with D1
All persistent data lives in D1, Cloudflare's SQLite-based SQL database for the Workers platform. The initial schema is defined in a SQL file that will evolve as features are added; D1 migrations handle schema updates without destroying existing data. The client API lets Pages Functions query and mutate tables, as seen in the follow logic, which inserts a new following relationship row.
Two SQLite limitations surfaced during development. First, SQLite lacks built-in UUID generation (PostgreSQL has functions for this), but the Workers runtime's Web Crypto support provides crypto.randomUUID(). Second, PostgreSQL supports sub-second date resolution while SQLite does not; the workaround uses strftime() in the column defaults to store fractional timestamps.
Media pipeline
Rich media is central to Mastodon content. Rather than building an image processing pipeline, Wildebeest uses Cloudflare Images APIs for upload, transformation, and CDN delivery of post images, avatars, and headers. Image handling code lives in /backend/src/media/image.ts, and the Cloudflare dashboard provides a convenient interface for browsing and managing the image catalog.
Background jobs with Queues
ActivityPub is chatty. Every post can trigger dozens of HTTP deliveries to followers' inboxes across federated servers, and blocking client requests on that traffic is unacceptable. The official Mastodon server solves this with Sidekiq; Wildebeest uses Cloudflare Queues for the same asynchronous job pattern.
A queue is a buffered topic that scales automatically. Producers enqueue structured messages (JSON objects), and consumers subscribe, polling for messages and processing them at their own pace. In Wildebeest, outgoing deliveries are queued when a user posts; similarly, messages arriving from remote servers at the inbox handler create asynchronous jobs instead of blocking the API. A separate consumer Worker, independent from the Pages project, processes those jobs sequentially. When load spikes, the queue grows but the main API stays responsive—and jobs still complete.
Caching with Durable Objects
Timeline generation is expensive, so Wildebeest caches completed timelines. Cache invalidation is the catch: with eventually consistent storage like Workers KV, a client may post and then read a stale cached timeline that doesn't include the new post. That failure was observed with a popular client app. Workflows centered on Account or Actor data require the same class of consistency guarantees.
Durable Objects provide just that. Each Durable Object is a single-instance Worker with a transactional storage API, ideal for coordination and strong consistency. Wildebeest implements a simple key-value cache on top of a Durable Object—only a few lines of code, exposing HTTP PUT and GET primitives. The transactional storage ensures that the latest write is always visible to the next read.
Authentication via Zero Trust
Handling user registration with email verification is a burden that Mastodon server operators inherit. Wildebeest sidesteps it with Cloudflare Zero Trust Access, which already supports email OTP and SSO via identity providers like Google, GitHub, and any SAML 2.0-compatible IdP. Access is configured using policies that decide who gets in and how.
The flow implements the OAuth 2 spec. Client login requests redirect through Access; on success, Access injects a JWT in request headers at the /oauth/authorize endpoint. Wildebeest verifies the JWT and returns an authorization code via redirect. First-time users are then prompted once for a Username and Display Name, which create their public Mastodon profile. The client exchanges the authorization code at /oauth/token for an API access token, which is sent on subsequent requests as an Authorization: Bearer header.
Deployment and updates
Wildebeest is distributed as an open-source GitHub repository. Installation relies on a "Deploy with Workers" button, which walks the new user through questions, authorizes GitHub access, forks the repository into their account, and triggers a GitHub Actions workflow that provisions and deploys the project.
That deployment workflow is a YAML file running on every change to the main branch. Keeping an instance updated is just clicking "Sync" on the GitHub fork. Updates are incremental and non-destructive. The trick is Terraform, with its state stored in a KV key. On redeploy, Wildebeest reads the previous state, computes the diff, and applies only the needed configuration changes. Database changes are likewise additive, using D1 migrations rather than recreating tables.
Built-in protection and observability
A deployed Wildebeest instance sits behind Cloudflare's standard protections as a normal Pages project: DDoS, WAF, and Bot Management are toggles away. Network and content optimization follow automatically, and Cloudflare analytics provide insight into how the instance performs and how it is used. No extra setup is needed.
The protocols: more than Mastodon API
Mastodon popularized the Fediverse, but the identity layer stands on older W3C specifications. Wildebeest implements the following:
- ActivityPub: the W3C decentralized social networking recommendation. It defines Actors (profiles), Objects (posts), inboxes, and outboxes, plus client APIs and server-to-server federation APIs. Its vocabulary comes from ActivityStreams.
- WebFinger: the HTTP discovery mechanism that maps an
acct:URI (like[email protected]) to resource objects. A WebFinger request returns JSON describing that actor's profile and interaction endpoints. - Mastodon API: the REST API catalog that powers client operations like server info, profiles, timelines, notifications, and search. Wildebeest implements these endpoints and supporting primitives, plus WebPush for notifications and NodeInfo for server metadata.
With those interfaces, Wildebeest can federate with other ActivityPub implementations and serve multiple existing Mastodon client apps. Confirmed compatible clients include the official Mastodon apps for Android and iOS, Pinafore, Mammoth, and tooot. The list will expand as Wildebeest develops.
Getting started and what's next
Deployment steps are documented in the public GitHub repository's README. Most dependencies have generous free tiers, though an Images plan is required (the lowest tier should cover typical workloads). Depending on load, Workers Unbound usage may also incur cost.
Wildebeest is now production infrastructure for Cloudflare: the @[email protected] and @[email protected]-owned accounts run entirely on Wildebeest. It is intended as a minimally viable server today, but the team will keep adding features. Community input is welcome via the GitHub issues tab, or in the dedicated Wildebeest room on the Cloudflare Developers Discord server.
