Kickstart

Kickstart is the starter's setup tool. It uses the credentials you added to create and connect the hosted database, sign-in, emails and test billing.

Keep your editor open in the project folder. You'll run three commands, checking the result of each before continuing.

Before you start

You should have completed Setup, Accounts and Configuration. That means npm ci finished, your root .env contains the required credentials and you've reviewed your installation settings. The default setup needs three credentials; the Stripe test key is optional if you disabled billing before installation.

To include AI in this first run, also add your OpenRouter API key and set AI_ENABLED=true. Otherwise, leave AI_ENABLED=false: Kickstart works without OpenRouter, but the app will have no AI chat.

For a new installation, the generated fields should still be blank. If you've already run kickstart, keep its saved values and see safe reruns.

Run the read-only check

npm run kickstart:check

This checks access to the required provider accounts without creating resources. If it reports a failure, fix that issue before continuing. An API key can be valid but still lack the permissions setup needs.

For a fresh installation, some project checks are marked as deferred. That's expected because the Supabase project doesn't exist yet. The installer checks those after creating it.

You're ready for the next command when the account checks pass and there are no required failures. Passing this check doesn't mean your app has been installed.

Create the hosted foundation

npm run kickstart

If you have several Supabase organizations or verified sending domains, the terminal asks which to use. Choose the ones intended for this app. Leave the terminal open while setup runs.

Kickstart saves the generated settings in .env and records its progress in private recovery files. If it stops with an error, use the recovery instructions below.

Start the app

After kickstart finishes successfully, run:

npm run dev

Open the address configured in APP_URL, normally http://localhost:3000. Keep the terminal running while you use the app.

If the terminal chooses a different port because 3000 is busy, resolve the conflict before testing sign-in. Authentication depends on using the configured address. See development-server troubleshooting.

Check your first account

1. Create an account in your local app.
2. Complete or skip the onboarding questions.
3. Confirm that the customer dashboard opens with your own workspace.
4. Reload the page, then sign out and sign in again.

Check password recovery with an allowed recipient too. The default setup doesn't require email verification at signup. You can change that later in authentication settings.

Try a test purchase

If billing is enabled, open Settings → Billing in your dashboard, choose a plan and continue to Stripe Checkout. Check that the page shows test mode, then pay with Stripe's test card 4242 4242 4242 4242, any future expiry date and any three-digit CVC. No real money moves.

After Checkout, you return to your app. Within a few seconds, Billing should show the plan as active; choose Refresh status if it doesn't. Subscriptions covers plan changes, cancellation and failed payments.

Open the admin panel

The admin panel at /admin gives you a read-only view of users, workspaces, subscriptions and feedback across your app. Workspace roles don't grant access to it, so give your own account access from the project folder:

npm run admin:grant -- --email YOUR_EMAIL

Replace YOUR_EMAIL with the email of the account you just created. Then open /admin, or choose Admin in your account menu. Maintenance explains how to add other operators.

Safe reruns

Keep .env, .kickstart and .secrets in the same project folder. The last two record what Kickstart created, so a rerun continues from earlier progress instead of creating duplicates. They're already excluded from Git. Back up all three somewhere private, such as an encrypted drive or a password manager's secure notes.

Fix the reported permission, quota, sender or network issue, then run the same command again. Don't delete the recovery files or create a replacement project to force setup past an error. If a provider request has an uncertain result, follow uncertain-operation recovery.

After deployment, the hosted services use your production address. Use the origin recovery guide before attempting to switch back to local setup.

You're finished when

• npm run kickstart completed without errors.
• You can sign up, sign in and reach your own workspace at http://localhost:3000.
• Password recovery emails arrive at your Resend account address.
• If billing is enabled, a test purchase shows the plan as active.