Run your own Fretlark.

Open source and free to host on your own Cloudflare account. Your songs, your accounts, your data.

Quick start

You need a free Cloudflare account and Node.js 22 or newer. About five minutes.

Get the code.

git clone https://github.com/jscr3ator/Fretlark.git
cd Fretlark
npm install

Sign in to Cloudflare.
```
npx wrangler login
```
Run the setup. It creates the database and file storage, applies the schema, sets the secrets, and deploys.
```
npm run setup
```
Open your site. The command prints your address. Create an account, then make yourself the owner:
```
npm run make-owner -- your-username
```

Want to try it on your computer first? npm run dev starts everything locally at http://127.0.0.1:8787 with no Cloudflare account.

Let an AI agent do it

Paste this into Claude Code, Codex, Cursor or any coding agent. It reads the repo and sets everything up, asking you only for what it can’t do itself.

I want to self-host Fretlark, an open-source Guitar Pro style tab editor and player, on my own Cloudflare account.

Repo: https://github.com/jscr3ator/Fretlark
1. Clone it (or use the current folder if it is already cloned) and read AGENTS.md and SELF-HOSTING.md fully before changing anything.
2. Follow AGENTS.md to install, run the tests, and deploy to Cloudflare with `npm run setup`.
3. Ask me before: logging in to Cloudflare, choosing a custom domain, enabling Ko-fi supporter plans, or closing public sign-ups. Never print or commit secrets.
4. When it is deployed, open /api/session on the new site to confirm it responds, create the first account, run `npm run make-owner -- `, and tell me the final URL and anything I still need to do.

If anything fails, read the Troubleshooting section of SELF-HOSTING.md, fix it, and continue.

Or point your agent at this page: it contains the same steps and settings.

Settings

Everything is configured in wrangler.jsonc (plain settings) or as Cloudflare secrets (private values). npm run setup handles the required ones.

Name	Type	What it does
`REGISTRATION_OPEN`	setting	`"true"` lets anyone sign up. Set `"false"` to close sign-ups, for example after you and your friends have accounts.
`OWNER_ACCOUNT_ID`	setting	The account that can manage other users. `npm run make-owner` sets it for you.
`MFA_ENCRYPTION_KEY`	secret	Encrypts two-factor secrets. Created by setup. Keep a copy: losing it disables everyone’s two-factor login.
`KOFI_URL`	setting, optional	Your Ko-fi page. Shows a “Get Plus” button on the pricing section. Leave empty to hide it.
`KOFI_VERIFICATION_TOKEN`	secret, optional	Lets Ko-fi payments upgrade accounts to Plus. Set the Ko-fi webhook to `https://your-site/api/kofi`.
`BACKUP_BUCKET`	binding, optional	A second R2 bucket. When present, a daily job copies the database and songs into it.

Storage limits

Free accounts get 20 MB of cloud storage and Plus accounts 500 MB. Change FREE_BYTES and PLUS_BYTES in lib/plans.mjs. Songs saved “only on this device” never use cloud storage.

Custom domain

Add your domain to Cloudflare, then run npm run setup -- --domain tabs.example.com (it adds the route and redeploys). Without it you get a free *.workers.dev address.

Updating

git pull
npm install
npm run deploy:update

That applies any new database migrations and redeploys. Your data is kept.

Help

How much does it cost?

The Cloudflare Workers free plan is enough for personal use or a small group. Cloudflare charges only if you go past its free limits. Nothing else is needed: there is no email service and no third-party database.

I forgot my password.

Accounts use a username and a recovery key that is shown once at sign-up. On the sign-in page choose “Forgot password” and enter the username and recovery key. If both are lost, the owner can delete the account and the person can sign up again.

Two-factor login stopped working.

Check that MFA_ENCRYPTION_KEY is still set to the value it had when people enabled two-factor. It must not change.

npm run setup says the database already exists.

That’s fine. Setup reuses it. If you want a different name, run npm run setup -- --name my-tabs.

Sound is missing or very quiet.

Playback uses a bundled soundfont and needs a browser tap or click before it can play. Open the site over HTTPS (the workers.dev address is) and press play.

Where is the full guide?

SELF-HOSTING.md in the repository covers every step, setting and fix in detail.