Getting started

Run Buoy on your computer, finish the owner setup, then add your first account. Local use needs no Cloudflare account or mail provider.

Get Buoy and start it

You need Git and npm on macOS, Linux or Windows with WSL2. From your terminal:

git clone https://github.com/just-every/run-buoy.git
cd run-buoy
npx -y @runeditrun/rer cli install
export PATH="$HOME/.local/bin:$PATH"
rer dev

Install the rer command once per computer. rer dev installs the checkout’s locked dependencies, selects its declared Node and pnpm versions, prepares local data and creates a local owner. A first launch can take several minutes. Progress and queue messages explain what is happening; if the shell stops waiting, run rer dev again to resume.

Open the private RER_OPEN link printed in your terminal on this computer. It opens Buoy signed in as the owner. Keep the link private: it grants access to the local installation. RER_READY is the app address; RER_SITE, when printed, is this public information site.

Finish setup

At Finish setup, confirm the owner and complete the first-run form. Until this is saved, the app returns the owner to setup. Then open Accounts and use the First use checklist.

An empty installation has no business records. Start with one real account and its confirmed renewal terms, or follow Move in to import your own records. Follow Accounts and evidence to understand what to enter.

Choose your owner mailbox

For a fresh installation with your own mailbox, use the separate setup steps before starting:

rer install
rer setup
rer dev

Enter the mailbox in the setup prompt. Setup also supports rer setup --owner-email you@example.com. Repeating setup preserves an existing owner and data; it does not replace the owner with a different identity.

Stop development, then start with the local outbox sign-in flow:

rer dev --stop
rer dev --login

Open the outbox link RER prints. Request sign-in for the saved owner email on the app’s sign-in page, then follow the newest ordinary sign-in message in the outbox and confirm it. Local mail stays on this computer. A successful sign-in consumes the link once.

Stop and return later

rer dev --stop

Run rer dev from the same checkout to return. Local database state persists in .wrangler/state; private settings live in .dev.vars. Keep both outside Git. Stop development and preview before builds or data transfer. Create a backup before discarding a checkout or resetting an installation.

Install beyond your computer

The public site and an installed Buoy are separate. Your installed app has its own sign-in and data. For deployment into your Cloudflare account, follow the repository’s deployment instructions, including private credentials and a working mail provider. A local dry run does not prove hosted sign-in or mail delivery.