Install Swarm on your own Cloudflare account.

One command creates everything Swarm needs on your account, deploys it on a domain you already have, and gives you a sign-in link. It takes a few minutes, and you can look at every step first.

What you need

Three accounts and a computer with a terminal and a browser.

A Cloudflare account with a domain

The domain must be active on Cloudflare. Swarm only adds subdomains; your main site and its mail are left alone. You need a plan with Queues and Durable Objects: the Workers Paid plan has both.

Node.js 22, pnpm 10 and git

Run corepack enable once to get pnpm. A browser on the same computer lets wrangler sign in to Cloudflare.

An email service

Resend is the quickest to start with; Amazon SES is the cheapest at volume. Mailgun, Postmark and your own mail server are previews.

The commands

Clone the repository, install its dependencies and run the installer. It explains each step as it goes.

If it stops for any reason, run pnpm swarm again: finished steps are skipped, nothing is created twice, and keys are never replaced.

Install from a terminal
git clone https://github.com/jntegz/swarm-newsletter.git swarm
cd swarm && pnpm install
pnpm swarm
Optional: see every step first, changing nothing
pnpm swarm --dry-run

Back up the .swarm/ folder the installer creates. It holds the keys for your install and is not in git. Without it you cannot update, and encrypted subscriber fields could never be read again.

What the installer asks, and what it creates

Everything is created on your own account. The DNS token you paste is used during the install and is not given to any worker.

  1. Cloudflare sign-in. A browser window opens so wrangler can use your account.
  2. Which domain, and the addresses it will set up, for you to confirm.
  3. A DNS token, from a link with the permissions filled in.
  4. Subdomains to leave alone, so sites you already run keep working.
  5. Your name and email. You become the owner and sign in with this address.
  6. Your first publication: its name and web address.
  7. How to send email: the service, the region, and its key.

It creates

What the installer creates on Cloudflare
KindWhat
Workersrealtime, track, events, site, capture, send, jobs and api
DatabaseOne D1 database
StorageA KV namespace, and R2 buckets for media, imports, exports and reports
QueuesSend, jobs and webhooks queues, each with a dead-letter queue
DNSAddresses for the dashboard, forms, links, media and events, publication websites, and DMARC for the mail domain
EmailThe sending domain with your email service, its records, and bounce and complaint reports back to Swarm

Addresses, for the domain example.com

Addresses for the domain example.com
AddressWhat it is
app.example.comThe dashboard and the API
forms.example.comSignup forms and subscriber settings
link.example.comClick and open tracking
<publication>.example.comPublication websites
mail.example.comThe sending domain

What it costs

Swarm is free and open source, and takes no share of what readers pay you. You pay the services it runs on, directly. Prices change, so check each one.

  • Swarm: freeOpen source under AGPL-3.0, with 0% of paid subscriptions.
  • CloudflareA plan that includes Queues and Durable Objects, plus any usage beyond what it includes.
  • A domainOn Cloudflare, with its nameservers pointing there.
  • Your email serviceUsually the main cost as your list grows. Resend has a free plan of 100 emails a day; Amazon SES charges per email.
  • Stripe, if you sellStripe's own fees on each payment. Swarm adds nothing.
  • Copilot, if you turn it onThe writing assistant starts off, because it uses a paid AI service.

After you install

The installer prints a one-time sign-in link that works for 60 minutes. Open it, and Home shows four steps to your first send.

Getting started guide

  1. Sending domain. Add your own under Sending & delivery and publish the records it shows. You can send from the shared domain meanwhile.
  2. DMARC set to quarantine. A domain sends only with an enforced DMARC record; Home shows the one to add.
  3. First subscribers. Import a list with a dry run first, add people by hand, or publish a signup form.
  4. First post. Write it, send yourself a test, and send. Warm-up spreads a large first send over a few days.

A fresh install is invite-only: only you and the people you invite can sign in. Owners and admins add a passkey or an authenticator app within 14 days.

Commands for later

Run these on the computer you installed from, in the Swarm folder. doctor changes nothing and says how to fix what it finds.

Commands after the install
ToRun
Check an installpnpm swarm doctor
Update to a new versionpnpm swarm update
Get a new sign-in linkpnpm swarm signin-link
Turn things on laterpnpm swarm enable custom-domains, enable payments, enable google, enable debounce
Switch features on or offpnpm swarm feature list, pnpm swarm feature <key> on
Change email servicepnpm swarm mail switch <service>

Pre-release. Swarm has no tagged release yet. Beyond --dry-run, the installer has not yet been run against real accounts. The README lists what is tested and what is not; please open an issue with what worked and what didn't.

Ready when you are.

Run the installer with --dry-run first if you like: it asks the same questions, lists every call it would make, and changes nothing.

Install from a terminal
git clone https://github.com/jntegz/swarm-newsletter.git swarm
cd swarm && pnpm install
pnpm swarm

Want to look first? pnpm swarm --dry-run shows every step and changes nothing.