Quick Start | GoShipped Docs

From a fresh checkout to a running app. Skip Stripe, email, and the rest until you need them.

Let’s get GoShipped running first. You can worry about the rest later.

pnpm install
pnpm run setup
pnpm run doctor
pnpm dev

When it works, you will have:

Next.js at https://localhost:3000
FastAPI at https://localhost:8000

Hosted Supabase is the easiest first run. You only need Docker if you want the whole stack on your machine.

Use `pnpm run`

Always type pnpm run setup and pnpm run doctor.

Bare pnpm setup and pnpm doctor are built-in pnpm commands. They will not run GoShipped’s scripts.

What you need

Requirement	Details
Node.js	20 or newer
pnpm	10 (the repo pins `pnpm@10.14.0`)
Python	3.11 or newer
Supabase	A hosted project, or local via Docker
OpenAI or Anthropic	At least one API key for chat

If you're missing one of these, the official setup guides are linked in the table.

Python packages install into apps/api/.venv automatically when you run pnpm dev. You do not set that up by hand.

Docker is not required unless you run local Supabase (pnpm supabase:start). A hosted project is enough. If you do want local, install Docker first — see Supabase local development.

Not required to start

Stripe, Resend, MCP, and Sentry are optional. Skip them in setup. You can add them later.

1. Install

From the repository root:

pnpm install

This installs workspace dependencies, including the pinned Vercel and Supabase CLIs.

2. Run setup

pnpm run setup

Setup is a guided wizard. It walks you through product config, env files, Supabase, AI, and optional extras — one step at a time.

It:

Validates starter.config.json
Creates missing env files from the examples (it never overwrites existing files)
Connects Supabase and applies migrations
Configures at least one AI chat provider
Offers Stripe, Resend, and other extras — skip them if you are not ready
Prints a short summary

Setup needs an interactive terminal. In CI, use pnpm run doctor instead.

If you skip Stripe

Billing is on by default in starter.config.json. If you skip Stripe keys and leave features.billing as true, doctor will still report those keys as missing.

Not using Stripe yet? Skip it, then set features.billing to false. The app still runs. Users get the default plan (DEFAULT_PLAN_WHEN_BILLING_DISABLED, which is pro).

HTTPS in local dev

pnpm dev serves the app over HTTPS. If mkcert is installed, the API cert is trusted automatically. Otherwise it is self-signed and the browser will warn once.

3. Let doctor check it

pnpm run doctor

Run it whenever you are unsure. Doctor only checks things. It never changes your setup.

It tells you what is missing, which file it belongs in, and where to get the value — without printing secrets.

Disabled features are reported as skipped. Their exclusive credentials are not required.

Exit code 0 means required checks passed (warnings are allowed). Exit code 1 means something required is still missing.

4. Start the app

pnpm dev

App	URL
Frontend	`https://localhost:3000`
Backend	`https://localhost:8000`
API health	`https://localhost:8000/health`
API reference	`https://localhost:8000/docs`

Both servers use local HTTPS. Your browser will warn about the certificate the first time. Accept it.

Hosted Supabase + local HTTPS

Set the Supabase Site URL to https://localhost:3000 (not http://). Allow-list the HTTPS redirect URLs, or confirmation and password-reset links will break.

You can also start the apps separately:

pnpm dev:web
pnpm dev:api

5. Send the first message

Open https://localhost:3000
Create an account
Confirm the email (hosted Supabase inbox, or Mailpit if you run local Supabase)
Open chat and send a message

If chat works, you are running. Go build.

What you actually needed

You only needed three things to boot and chat:

Required	Why
Supabase	Auth, Postgres, and (if files are on) Storage
One chat provider	`OPENAI_API_KEY` and/or `ANTHROPIC_API_KEY` in `apps/api/.env`
OpenAI, if Files or Memory stay on	Embeddings currently use OpenAI even when Anthropic is the chat provider

Files and Memory are enabled by default. If you only have an Anthropic key, either add OpenAI for embeddings or turn features.files and features.memory off in starter.config.json.

Skip these for now

Integration	Default	How to skip
Stripe	Billing flag on; keys not required to boot	Skip in setup, or set `features.billing` to `false`
Resend	`EMAIL_ENABLED=false`	Leave it disabled. Auth email still goes through Supabase.
Sentry	Off when the DSN is empty	Leave empty
MCP	`features.mcp=false`	Leave off
Web research / stocks / shopping	Tools on; provider keys optional	Skip the keys. Those tools fail until configured.

None of these block a local first run.

Local vs hosted Supabase

Hosted (typical first run): setup links your project and pushes migrations. No Docker. Create a project in the Supabase dashboard if you do not have one yet.

Local (offline / full stack on your machine):

pnpm supabase:start

That needs Docker. Auth emails then show up in Mailpit (the URL is in pnpm supabase:status). See Supabase local development if the CLI stack is new to you.

If something fails

Run doctor first:

pnpm run doctor

Symptom	What to do
`pnpm setup` does the wrong thing	Use `pnpm run setup`.
Browser warns about HTTPS	Expected. Accept the warning, or install mkcert.
Auth emails open `http://localhost:3000` and fail	Set Supabase Site URL to `https://localhost:3000`.
Chat works but files or memory fail	Add `OPENAI_API_KEY`.
Doctor complains about Stripe	Add keys, or set `features.billing` to `false`.

You're running

Nice. The foundation is live.

Next, learn which files you actually edit — and which ones you can ignore.

Project Structure

A map of the repo for builders, not a tour of every folder.

⚡ Quick Start