Everything an admin or developer needs beyond the setup guide: what Yakyard runs on, the free plan math, every setting, updates, backups, tests and where the code lives.
What you need
- A Cloudflare account. The free plan is enough (see Free plan). File storage (R2) asks for a payment card before you can turn it on, even though the first 10 GB are free.
- Node.js 22.5 or newer on your computer, only to deploy. Works on macOS, Linux and Windows.
Yakyard uses Workers, Durable Objects, D1 (database), R2 (files), Workers AI (transcripts) and the Images binding (photo previews).
Free plan math
Yakyard is built to fit Cloudflare's free plan with zero paid features turned on. Free plan limits (November 2026): 10 ms of CPU per request, 100,000 Worker requests a day, 100,000 Durable Object requests a day, 5 million database rows read and 100,000 written a day, 10 GB of files, 10,000 Workers AI neurons a day, 5,000 photo previews a month. Daily limits reset at midnight UTC.
CPU per request. Every request, and every background job, has to finish in under 10 ms of CPU, including the first request on a fresh copy of the code, which also pays to compile what it runs. Two checks: npm run cpu-bench runs each path as the first thing a fresh process does (a local estimate of a cold start, database time left out), and scripts/cpu-check.mjs measures a copy of Yakyard on Cloudflare itself with the 10 ms limit switched on (SETUP.md). The API is a table of small handlers, so a request compiles only the one it uses. Per piece of work:
| What | CPU | How it fits |
|---|---|---|
| Password sign-in | 0.05 ms | The slow part (PBKDF2-SHA256, 600,000 rounds, about 130 ms) runs in your browser, like Bitwarden. The server only does one SHA-256 of a salt and that key. |
| Sign-in of an account made before browser-side stretching | 0.05 ms | The server never runs the old 18 ms hash. The person is asked to set a new password once, from a sign-in link (see Old accounts). |
| Unknown email at sign-in | 0.05 ms | Same work as a real account, so the reply doesn't reveal who has one. |
| Opening a conversation (50 messages) | 0.05 ms | Database time doesn't count as CPU. |
| One phone notification | about 1 ms | Encryption only (Web Push, written out in src/webpush.js, no library). The signed VAPID token is made by the fan-out job and kept in the database for 11 hours. Sending a message only starts a background job; that job works out who gets a buzz and starts one more job per device. |
| Slack import, one page of 50 messages | 2 ms | Each import is a chain of background jobs: 3 pages (150 messages) per job, the next job 4 seconds later. |
| Voice note to transcript, per minute of audio | under 1 ms | Native base64. Each note gets its own background job, which retries if Workers AI is busy and waits for tomorrow if today's free time is used up. |
| Link previews and outside pictures | small | Page parsing is native (HTMLRewriter), capped at 512 KB. Pictures are streamed, 5 MB max. |
Calls (Pop in) go browser to browser. The server only relays the short setup messages.
Background jobs. Scheduled messages, reminders, transcripts, Slack imports and phone notifications each run as their own job: a small Durable Object woken by its own alarm. The alarm only keeps time; the work runs as a separate call to the Worker itself (JobRunner, through Cloudflare's automatic ctx.exports loopback), usually on an isolate that is already warm. Every job is its own run with its own 10 ms, so nothing waits behind anything else, and a scheduled message goes out within seconds of its time. A check every 5 minutes (the cron) only re-wakes anything that is overdue. Cloudflare Queues are on the free plan too, but their 10,000 operations a day are shared by the whole account, and one Slack import plus a day of notifications can use them up. Durable Objects allow 100,000 requests a day.
How many people. Rough daily numbers for one active person: 40 messages sent, 150 conversations opened, 5 app opens.
| Allowance | Per active person a day | Free plan a day | People |
|---|---|---|---|
| Worker requests | about 400 (sends, opens, read marks, uploads) | 100,000, minus 288 for the 5-minute check | about 250 |
| Durable Object requests | about 300 (live updates, plus about 2 per background job) | 100,000 | about 330 |
| Database rows read | about 20,000 | 5,000,000 | about 250 |
| Database rows written | about 350 | 100,000 | about 285 |
| Voice transcripts | depends | about 214 minutes for the whole team | |
| File storage | depends | 10 GB (Yakyard stops new uploads at 9 GB) |
The tightest line is about 250 people. Real teams are bursty and some people are heavy users, so plan on a fifth of that: up to about 50 people, comfortably. The first things a busy team feels are voice transcripts (about 4 minutes per person a day for 50 people) and photo previews (5,000 a month).
When something runs out, nothing breaks:
- Voice transcripts: notes still send and play. The transcript says it comes tomorrow and its background job fills it in after midnight UTC.
- Photo previews: photos show at full size for an hour, then Yakyard tries again.
- Database: pages and the app show "Your team used up today's free database allowance" instead of an error page, until midnight UTC.
- File storage: uploads stop with a clear message at 2 GB per person or 9 GB for the team. Change both with
STORAGE_PER_PERSON_GBandSTORAGE_TOTAL_GB.
Admins see storage and today's voice minutes on the Usage card in Admin. Requests and database use are in the Cloudflare dashboard.
When to pay $5 a month (Workers Paid). More than about 50 busy people, more than about 3 hours of voice notes a day, or if you see "free database allowance" or error 1102 more than once. Upgrade in the Cloudflare dashboard. Nothing in Yakyard changes.
Try it on your computer first
git clone https://github.com/yakyard/yakyard.git
cd yakyard
npm ci
cp .dev.vars.example .dev.vars # then put a long random code after SETUP_TOKEN=, for example from: openssl rand -hex 24
npm run db:init:local # creates the tables in a local database
npm run dev # open the address it prints, usually http://localhost:8787
The first visit shows Set up Yakyard. The setup code is the SETUP_TOKEN in .dev.vars.
Notes for local testing:
.dev.varsholds secrets forwrangler dev, oneNAME=valueper line. It is in.gitignore. PutVAPID_PRIVATE,TOKEN_KEYand others here when you test those features.- Workers AI always runs on Cloudflare, even locally, so voice transcripts need
npx wrangler loginand count against your account. - If every page shows
no such table: users, runnpm run db:init:localagain.
Deploy
The step-by-step version, for people who don't use a terminal every day, is SETUP.md. The short version:
npx wrangler login
npm run deploy
Settings live in wrangler.jsonc, which works as it is. The first npm run deploy creates the D1 database and the R2 bucket (Wrangler's automatic provisioning, so there are no ids to paste), deploys, brings the database tables up to date, and makes a setup code that it prints once. Turn on R2 in the Cloudflare dashboard first.
Or use the Deploy to Cloudflare button in the README: it does the same from your browser, keeps a copy of Yakyard in your GitHub, and redeploys when you push to it. Type your own long random setup code when it asks for SETUP_TOKEN.
Open the address it prints. The first visit shows Set up Yakyard: enter the setup code, then create the owner account. The setup code makes sure nobody else can claim your new workspace. It only works once. If you set OWNER_EMAILS, the owner email must be on that list.
Then invite your team from the menu (Invite people). Invites make a link: you send it yourself, by email, chat or text.
To keep R2 tidy, add a lifecycle rule to the bucket in the Cloudflare dashboard (R2, the bucket, Settings, Object lifecycle rules) that aborts incomplete multipart uploads after 1 day.
Notifications
npm run vapid # prints VAPID_PUBLIC, VAPID_SUBJECT and a private key
# put VAPID_PUBLIC and VAPID_SUBJECT in wrangler.jsonc under "vars", then:
npx wrangler secret put VAPID_PRIVATE # paste the private key line
npm run deploy
VAPID_SUBJECT is an email address push services can reach you at, written as mailto:you@example.com. Until these are set, the owner sees "Phone notifications are off" in the first-run checklist.
On iPhone, people add Yakyard to the Home Screen first (Share, Add to Home Screen), then turn notifications on inside the app.
Optional features
| Feature | What to set |
|---|---|
| Sign in with Google | Create an OAuth client in Google Cloud (redirect https://YOUR-URL/auth/callback). Set GOOGLE_CLIENT_ID, "GOOGLE_ENABLED": "1", secret GOOGLE_CLIENT_SECRET. ALLOWED_DOMAINS lets anyone with your company email in. |
| Calls on strict networks | Create a TURN key in Cloudflare Realtime. Secrets TURN_KEY_ID and TURN_KEY_TOKEN. |
| Slack import | Create a Slack app with user scopes channels:read groups:history groups:read im:history im:read mpim:history mpim:read users:read users:read.email files:read reactions:read, redirect https://YOUR-URL/slack/callback. Set SLACK_CLIENT_ID and SLACK_TEAM_ID (your Slack workspace id, starts with T), secrets SLACK_CLIENT_SECRET and TOKEN_KEY. TOKEN_KEY must be exactly 32 random bytes written as base64: make one with openssl rand -base64 32 and paste the whole line into npx wrangler secret put TOKEN_KEY. Instead of the SLACK_CLIENT_SECRET secret, the owner can paste the Client Secret on the import page. It is stored encrypted with TOKEN_KEY. Guests can't import. |
| Team clocks | "TEAM_LOCATION": "1". See Team clocks and privacy. |
| Weather on team clocks | "WEATHER": "1" as well. See Team clocks and privacy. |
| Better transcripts | VOICE_LANGUAGE (e.g. en, fr, es) and VOICE_HINT with names and words to spell right. |
| Your own domain | Add a custom domain to the yakyard Worker in the Cloudflare dashboard and update APP_URL. |
Team clocks and privacy
Team clocks are off unless you set "TEAM_LOCATION": "1". Even then, nothing is collected until a person turns on Share my city and local time in Status and notifications. Then Yakyard stores the city, region, country and time zone that Cloudflare reports for their connection, and shows them to teammates (never to guests). Turning it off deletes the stored city right away.
With "WEATHER": "1", coordinates rounded to about 10 km are also stored for people who share, and sent to Open-Meteo to get the weather. Open-Meteo's free API is for non-commercial use only. A company running Yakyard is likely commercial use: check their terms and get an API plan if needed, or leave WEATHER off.
Each person's time zone is always saved from their own browser (not their location), so do-not-disturb hours work. It is only shown to others if they share.
All settings
Settings marked vars go in wrangler.jsonc, under "vars". Secrets are set with npx wrangler secret put NAME (the full list is in .dev.vars.example).
| Name | Where | Needed | What it does |
|---|---|---|---|
WORKSPACE_NAME |
vars |
no | Team name on the sign-in page. Default "Yakyard". |
OWNER_EMAILS |
vars |
no | Comma-separated emails that are always owners. When set, setup only accepts one of them. |
APP_URL |
vars |
no | Public address for reminder links. Default: the address setup was done on. |
SETUP_TOKEN |
secret | first run | Setup code for the first visit, 24+ characters. npm run deploy makes one if it is missing. |
STORAGE_PER_PERSON_GB, STORAGE_TOTAL_GB |
vars |
no | File space caps. Default 2 and 9 (R2 is free up to 10 GB). |
VAPID_PUBLIC, VAPID_SUBJECT |
vars |
for notifications | From npm run vapid. |
VAPID_PRIVATE |
secret | for notifications | From npm run vapid. |
ALLOWED_DOMAINS |
vars |
no | Email domains that may sign in with Google without an invite. |
GOOGLE_CLIENT_ID, GOOGLE_ENABLED |
vars |
no | Google sign-in. |
GOOGLE_CLIENT_SECRET |
secret | with Google | Google sign-in. |
SLACK_CLIENT_ID, SLACK_TEAM_ID |
vars |
no | Slack import. |
SLACK_CLIENT_SECRET, TOKEN_KEY |
secret | with Slack import | TOKEN_KEY is base64 of 32 random bytes. |
TURN_KEY_ID, TURN_KEY_TOKEN |
secret | no | Calls behind strict networks. |
VOICE_LANGUAGE, VOICE_HINT |
vars |
no | Transcript language and spelling hints. |
TEAM_LOCATION, WEATHER |
vars |
no | Team clocks and weather. Both default to off. |
DEV_LOGIN |
vars |
no | Local testing only: /auth/dev?email=... signs in on localhost. Keep "0" in production. |
IMG_CACHE_MB |
vars |
no | Room in R2 for copies of outside pictures, link previews and weather. Default 200. |
SLACK_API |
vars |
no | Tests only: point the Slack import at a mock server. |
VOICE_AI_URL |
vars |
no | Tests only: a local stand-in for Workers AI (localhost addresses only). |
PUSH_TEST_URL |
vars |
no | Tests only: a local stand-in for the push services (localhost addresses only). |
Updating
npm run backup # a copy of the database first, see "Backups"
npm run update # gets the newest Yakyard and deploys it
npm run update sets your own settings in wrangler.jsonc aside, pulls the new version, puts your settings back and runs npm run deploy. Deploying updates the database before the new code goes live (scripts/migrate.mjs): it adds any column an existing table is missing, then creates any new tables, indexes and triggers from schema.sql. Safe to run again and again. An install from before wrangler.jsonc keeps its settings: the first deploy moves them over from wrangler.toml.
With the Deploy button, Cloudflare redeploys your GitHub copy on every push. To update it, sync your copy with the original on GitHub (Sync fork, or a pull request from the original).
Open apps show "New version of Yakyard" and update in one tap. If the new version misbehaves, npx wrangler rollback puts the previous one back. The database changes only add, so it keeps working. Cloudflare can't roll back past the update that adds background jobs, because it adds a Durable Object class: back up first (details in SETUP.md).
Backups
npm run backup # saves backups/yakyard-remote-<date>.sql
npm run restore -- backups/<file> # puts it back (asks first); --local works on your computer's copy
wrangler d1 export can't make a backup Yakyard can restore: it stops on the full-text search tables, and its option for them writes a file D1 can't import. npm run backup reads every table itself and writes plain SQL. npm run restore loads it, rebuilds both search indexes and recounts storage. Photos and voice notes live in R2 and are not in the backup. Details and a restore drill in SETUP.md.
Old accounts
Accounts made before Yakyard moved password stretching into the browser hold an older kind of password hash. Checking it would take about 18 ms of CPU, over the free plan's limit, and the server can't check that a new browser key matches the old password without the same cost. So these people set a new password once, from a link: they see "This account needs a new password, once" at sign-in. The owner sends them a new link (Invite people with their email). An owner who can't sign in makes their own link from the computer they deploy from:
npm run signin-link -- you@example.com
Sign-in throttling
Sign-in allows 30 tries per network address and 25 per account in 15 minutes, from anywhere. That means someone who keeps guessing at one person's email can keep that person locked out of password sign-in for a while. Google sign-in and a new link from an admin still work. Admins can only send new links to people who never signed in. The owner can send one to anyone.
The step before sign-in (the browser asking for its password salt) allows 100 requests per address in 15 minutes. Changing a password allows 10 tries per person.
Tests
npm test
Runs the unit tests, then the security checks against a local server if one is running (npx wrangler dev --local --port 8797 on a fresh npm run db:init:local). The security checks need Python 3 with requests and playwright. To use another port and database copy: node scripts/migrate.mjs --local --persist-to=/tmp/yy, npx wrangler dev --local --persist-to /tmp/yy --port 8811, then YY_BASE=http://localhost:8811 YY_PERSIST=/tmp/yy npm test.
How it's built
No framework and no build step. Plain JavaScript in public/app.js, a Cloudflare Worker in src/.
| Part | File |
|---|---|
| API, sign-in, files | src/worker.js |
| Live updates, presence, calls signaling | Hub Durable Object in src/worker.js |
| Push, status, search, reminders, scheduled send | src/features.js |
Background jobs (one Durable Object per job, work done by JobRunner) |
Job, JobRunner and runJob in src/worker.js, arm, jobAlarm and the job runners in src/features.js |
| 5-minute safety check and hourly tidy-up | scheduled() in src/worker.js, sweep and housekeeping in src/features.js |
| Voice notes and transcripts | src/voice.js |
| Slack import | src/slackimport.js |
| Link previews | src/unfurl.js |
| Database tables | schema.sql, brought up to date by scripts/migrate.mjs |
| Backups | scripts/backup.mjs, scripts/restore.mjs |
| CPU check on Cloudflare | scripts/cpu-check.mjs |
| Password stretching in the browser | public/auth.js |