Quick Start

The goal is a first local login without real payments or remote resource creation. Run commands at the Flare repository root. Start with Get source if needed.

1. Check tools and the port

node --version
pnpm --version
pnpm install --frozen-lockfile

Use Node.js 22.12+ and pnpm 10.26.2. Flare listens on port 3000; when another app already uses it, set FLARE_DEV_PORT (for example FLARE_DEV_PORT=3100) in the terminal or root .env, and the local APP_URL follows it. Keep the browser origin aligned with localhost rather than switching to 127.0.0.1 during authentication.

2. Initialize local state

pnpm muse:init

This generates/preserves the local auth secret in apps/web/.dev.vars, applies local D1 migrations and inserts development accounts. Repeating init preserves existing credentials and secrets. The CLI loads root .env consistently, but init performs local operations and rejects --target.

Run pnpm muse:doctor afterwards. Without --target it checks local development only, needs no Cloudflare account, and reports each feature as ready, local, disabled, or missing; add --json for AI agents.

To choose a seed password, set MUSE_SEED_PASSWORD to at least eight characters before the first initialization. PowerShell example:

$env:MUSE_SEED_PASSWORD = "CHOOSE_A_LOCAL_PASSWORD"
pnpm muse:init

Changing the variable later does not reset an existing account. Use local password recovery or isolated development state; never delete production data to fix local login.

3. Start the app

pnpm dev

Wait for Vite and Paraglide generation, then open http://localhost:3000. Chinese starts at /zh. The public example is flare.musemvp.com, but it does not use local seed accounts.

Use your chosen password if set before initial seeding. Remote deployments never create these accounts.

4. Complete a visible journey

1. At /auth/login, request a code for a local address, read the newest six-digit code at /dev/mail, then submit it. A new address can create an account.
2. To use a seed password, select “Use password” and sign in at /auth/password.
3. Upload a TXT smaller than 1 MiB at /app/files. Confirm its row, download identical contents and delete it.
4. Generate an image at /app/image. Locally it runs in mock mode: the result lands in /app/library and the credit line appears in /app/usage without any key or spend.
5. Save a name at /app/settings and verify persistence after reload.
6. Sign out; /app must redirect to login and ordinary users must not access Admin.

To test email verification, register a new email at /auth/register, refresh /dev/mail and follow that recipient's verification link. Password reset messages appear there too. Development mail is captured, not delivered externally.

Local and external capabilities

Local D1/R2 and captured mail support first run. Billing is disabled and AI uses free mock mode. For real OpenAI text, images and speech, add OPENAI_API_KEY to apps/web/.dev.vars and run AI_MODE=live pnpm dev (PowerShell: $env:AI_MODE = 'live', then pnpm dev). Video needs its separate provider key. Only local Workers AI calls need wrangler login and WORKERS_AI_REMOTE=true. See AI overview. Configure OAuth, Turnstile and merchant accounts separately.

Success checks

• Home, login and bilingual workspace render without hydration errors.
• Files and settings persist; admin access is isolated by role.
• A new registration cannot bypass email verification.
• /dev/mail exists only in development, never as a production acceptance tool.

Troubleshooting

Continue with Brand Configuration.