Get started

From zero to a running app.

You need Node 18+ (for npx) or Bun. Everything else the wizard checks for and offers to install.

Run the wizard

npx init-offense my-app
# or, with Bun
bunx init-offense my-app
# or install it once
npm i -g init-offense
init-offense my-app

Every command the wizard runs is shown before it runs, and nothing irreversible happens without asking. Add --dry-run to see the whole plan without changing anything.

What the wizard does

Your appThe display name (for example Widget App), a short name for code and URLs (widget-app), the folder, and whether to create a GitHub repository and a PageSpace drive.
Public or privateOn a free GitHub plan only public repositories get free CI minutes and enforceable merge rules. The wizard explains the trade-off and lets you choose; --yes never makes code public.
ToolsGit, Bun, Docker (it must be running), the GitHub CLI and the PageSpace CLI. On macOS it uses Homebrew and OrbStack; on Linux, your package manager.
Accountsgh auth login and pagespace login in your browser. The wizard mints a temporary PageSpace setup key, uses it, and revokes it when it finishes; you never handle a token.
CreateGenerates and renames the project, installs dependencies, creates the repository and the drive, and offers to set up the review gate (two clicks in your browser).
RunPicks free ports, starts Postgres and Redis in Docker, runs the app, and opens it and your drive.

Sign in to your app locally

Local development needs no email provider. Request a sign-in link on /sign-in, then open the link printed in your terminal:

[dev-mail] ------------------------------------------------------------
[dev-mail] To:      you@example.com
[dev-mail] Subject: Sign in to Widget App
[dev-mail] Link:    http://localhost:3000/auth/confirm?token=…

The terminal mailer runs only in development, on localhost, and only when no Resend key is set. Production, staging and tests refuse to start without real email.

Day to day

bun slot:up && bun dev   # start the database stack and the app
bun check                # every quality gate, before you push
bun verify               # check + integration + browser tests

Several projects can run on one machine: set <APP>_POSTGRES_PORT, <APP>_REDIS_PORT and <APP>_APP_PORT in .env (the wizard does this for you when the defaults are taken).

When you are ready for more

Step	How
Real email	Add `RESEND_API_KEY` and `AUTH_EMAIL_FROM` to `.env` and your deploy secrets.
Review gate	`bun github:review-app` if you skipped it in the wizard (two browser clicks).
Autonomous agents	A GitHub machine user and `.env.agent` from `.env.agent.example`, so agents never act as you.
Staging	Create the Fly apps, then `gh variable set STAGING_ENABLED --body true`.

Next: the agent workflow