Skip to content
RED

Quick Start

This is the shortest path from license key to a running RED app.

1. Scaffold RED

Section titled “1. Scaffold RED”

You need Bun, Node.js 20+, a Convex account, and a valid RED license key.

Terminal window
bun create red-app my-project --license <your-license-key>
cd my-project
bun install

The scaffold writes two important files:

  • .red-version — commit this; it tells /red-update which RED base version you are on.
  • .red-license — keep this git-ignored; the CLI and skills use it to access RED releases.

2. Initialize Your Project

Section titled “2. Initialize Your Project”

Open Claude Code from the project root and run the setup skill:

/red-init

The skill asks for:

  • Convex backend setup.
  • Project name.
  • What to do with the Books demo: keep, remove, or replace.
  • Signup mode and organization creation policy.
  • Optional modules: AI Chat, Billing, API Keys.
  • Whether to keep or remove apps/docs/.

Nothing is modified until the skill shows a summary and you confirm. If Convex is configured, the skill verifies with bunx convex dev --once, runs lint, and runs bun run seed to create the global admin user.

For the first run, keep the AI module and the demo features. That gives you the Brief AI Assistant as a working reference before you customize anything.

3. Start the App

Section titled “3. Start the App”
Terminal window
bun dev

Open http://localhost:5173.

If you skipped Convex during /red-init, run this first in a normal terminal:

Terminal window
bunx convex dev --once

Then run:

Terminal window
bun run seed

The seed command prints the admin credentials it created.

4. Verify the Brief AI Assistant

Section titled “4. Verify the Brief AI Assistant”

Sign in with the seeded admin user, create or open a Brief workspace, then try this:

Add a section called "Goals" with a few product goals.

The assistant should read the brief, add a section, and summarize what changed.

Now test background work:

/export

The assistant calls exportBrief, which starts an internal background task. The chat stays usable while task progress is written as events. When the export finishes, the engine adds a task_event message and the assistant can reply with the artifact.

That loop is the core RED pattern: agent + tools + shared state + background tasks.

5. Check the Admin Portal

Section titled “5. Check the Admin Portal”

Go to /admin with the seeded admin user.

Use it to inspect:

  • Users and organizations.
  • Audit logs.
  • Waitlist and auth configuration.
  • Billing sync and plan state if Billing is enabled.
  • Global configuration.

Troubleshooting

Section titled “Troubleshooting”

Convex setup did not finish

Section titled “Convex setup did not finish”

The Convex CLI requires browser login and project selection. Run:

Terminal window
bunx convex dev --once

Then make sure .env.local contains VITE_CONVEX_URL and VITE_CONVEX_SITE_URL. Vite only exposes variables prefixed with VITE_.

Admin credentials do not work

Section titled “Admin credentials do not work”

Run:

Terminal window
bun run seed

The command creates or refreshes the development admin and prints the current credentials.

Emails do not arrive

Section titled “Emails do not arrive”

In development, Resend is not automatically live. Configure it in Convex when you need real email delivery:

Terminal window
npx convex env set RESEND_API_KEY <your-key>

Then set your Site URL from Admin > Configure > General so email links and CORS use the right origin.

Next Steps

Section titled “Next Steps”