Run your own Fretlark.

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

Fretlark is open source under the MIT license. The full SELF-HOSTING.md guide covers every step, setting and fix.

Quick start

You need a free Cloudflare account, Node.js 22.13 or newer, and R2 enabled once in the Cloudflare dashboard. 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, 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.
`STORAGE_LIMIT_MB`	setting, optional	Cloud storage per account in MB. Defaults to `"500"`.
`BACKUP_BUCKET`	R2 binding, optional	A second R2 bucket. When present, a daily job copies the database and songs into it.

Storage limits

Each account gets one cloud storage limit, 500 MB by default, set by STORAGE_LIMIT_MB in wrangler.jsonc. Each account is also capped at 200 songs. Songs saved only on the device use browser storage and do not count toward either limit.

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 and R2 free allowances are enough for personal use or a small group. Cloudflare may ask for a payment method to enable R2, but the free allowance still applies. Nothing else is needed: there is no email service and no third-party database.

I forgot my password.

Accounts use a username, a password of 12 or more characters, 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.