Installation & Setup
RondoFlow is local-first: everything runs on your machine. You can install it two ways — a Local dev setup (Node tooling on your host, PostgreSQL in Docker) or a Docker setup that runs every service in containers. Pick whichever matches how you like to work.
Prerequisites
| Requirement | Why you need it | Notes |
|---|---|---|
| Node.js 20+ | Runs the dev servers and tooling | Only required for Local dev; the repo pins Node 20 (.nvmrc) and the workspace declares engines.node: ">=20". Not needed for the full Docker path. |
| Docker | Hosts PostgreSQL (and all services in Docker mode) | Docker Desktop or a compatible engine with docker compose. |
| Claude Code CLI | Assistants (agents) are Claude Code subprocesses | Install it and authenticate so your assistants can run. See Claude Code provider. |
If the Claude Code CLI is missing, RondoFlow still starts, but it shows a banner and assistants cannot run until the CLI is detected. The startup prerequisites check treats a missing CLI as a warning, not a hard blocker.
RondoFlow can also use OpenAI and Perplexity for assistants. Those need API keys but no CLI. See Providers.
Install
Local dev
Use this path when you want hot reload and to run the Node tooling directly on your host. PostgreSQL still runs in Docker.
Clone the repository
git clone https://github.com/rondoflow/rondoflow.git
cd rondoflowRun setup
npm run setupnpm run setup does everything you need to get started, in order:
npm install— installs all workspace dependencies.node scripts/setup-env.js— generates a root.envfrom.env.examplewith a freshly generated randomBETTER_AUTH_SECRET. If a.envalready exists, it is left in place (the script only appendsBETTER_AUTH_SECRETandBETTER_AUTH_URLifBETTER_AUTH_SECRETis missing — your existing config is never overwritten).docker compose up -d --wait postgres— starts PostgreSQL and waits until it’s healthy.npm run db:migrate— applies the Prisma migrations (prisma migrate dev).npm run db:seed— loads sample data and, if the admin env vars are set, bootstraps the first admin.
Setup generates a working .env, but the Claude credential is left blank. To run assistants on Claude, add an ANTHROPIC_API_KEY or a CLAUDE_CODE_OAUTH_TOKEN (from claude setup-token). If both are set, the setup token wins. See Configuration.
RondoFlow is invite-only, so set RONDOFLOW_ADMIN_EMAIL and RONDOFLOW_ADMIN_PASSWORD (optionally RONDOFLOW_ADMIN_NAME) in .env before this seed step runs — that bootstraps the first admin account. If you ran setup before adding them, edit .env and re-run npm run db:seed. See First run.
Start the dev servers
npm run devThis runs the full stack via Turborepo. Three apps come up:
- UI on port 3000 — open
http://localhost:3000 - Server (Fastify + Socket.IO) on port 3001
- Docs (this site, Nextra) on port 3002, proxied at
http://localhost:3000/docs
You can also start packages individually:
npm run dev:ui # Next.js frontend only (port 3000)
npm run dev:server # Fastify backend only (port 3001)
npm run dev:docs # Docs site only (port 3002)Ports
Both paths expose the same ports:
| App | Port | URL |
|---|---|---|
| UI (frontend) | 3000 | http://localhost:3000 |
| API (Fastify + Socket.IO) | 3001 | http://localhost:3001 |
| Docs (Nextra) | 3002 | Served at <host>/docs (proxied through the UI) |
| PostgreSQL | 5432 | postgresql://localhost:5432/rondoflow |
The docs site sets a base path of /docs and the UI reverse-proxies it, so you read the documentation at http://localhost:3000/docs — the same origin as the app. Port 3002 is the docs app’s direct port.
First run
RondoFlow is invite-only — there is no self-registration. The login page reads “Access is invite-only. Ask an administrator to create your account.” To get the first administrator account, you bootstrap it at seed time.
Before seeding, set these in your root .env:
RONDOFLOW_ADMIN_EMAIL=you@example.com
RONDOFLOW_ADMIN_PASSWORD=<a strong password>
RONDOFLOW_ADMIN_NAME=Administrator # optional, defaults to "Administrator"The seed step then creates that first admin. Bootstrap is skipped if either the email or password is blank, and it is idempotent — if the user already exists, it just ensures their role is admin.
There are two paths to run the seed:
-
Local dev:
npm run setuprunsnpm run db:seedfor you, so the admin is created automatically as long as the two env vars are set before you run setup. (You can re-runnpm run db:seedafter editing.env.) -
Docker: the
migratecontainer runsprisma migrate deployonly — it does not seed. Run the seed step yourself to create the first admin, with the admin env vars set and PostgreSQL reachable:npm run db:seed
On Docker, if you skip the seed step, no admin is created and — because self-registration is disabled — everyone is locked out of sign-in. Run npm run db:seed (with the admin vars set) to create the first administrator.
Sign in as that admin with email and password (GitHub/Google sign-in also work for accounts an admin has already created). A guided onboarding wizard then walks you through choosing a working directory, a work mode, and a first action. If the Claude Code CLI isn’t detected, the wizard surfaces install instructions until it is.
To add more people, create their accounts from the Users panel — only an admin can do this. New users default to the read-only viewer role.
Database & Docker scripts
Manage the database and the PostgreSQL container from the repo root:
| Command | What it does |
|---|---|
npm run db:migrate | Apply Prisma migrations (prisma migrate dev) |
npm run db:seed | Load sample data and bootstrap the first admin (if the admin env vars are set) |
npm run db:studio | Open Prisma Studio to browse the database |
npm run docker:up | Start only the PostgreSQL container (docker compose up -d postgres) — used by the Local dev path |
npm run docker:down | Stop all containers (docker compose down) |
The default database connection is postgresql://rondoflow:rondoflow_dev@localhost:5432/rondoflow. These credentials are for local development only — change them before exposing the database anywhere.