Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cubby.pro/llms.txt

Use this file to discover all available pages before exploring further.

​
Expert from paste

Copy one prompt into your coding agent and it becomes an effective Cubby developer immediately: it installs the CLI, logs in, scaffolds with the right template, makes the correct local-dev call, defaults to the correct data model, and deploys — without the trial-and-error of guessing Cubby’s conventions. This page is agent-neutral. Codex, Claude, and Cursor all work the same way: the cubby init scaffold writes the agent-rules files each tool already reads (AGENTS.md for Codex, CLAUDE.md for Claude, .cursor/rules/cubby.mdc for Cursor), so the deep, template-correct contract lands in your project automatically. MCP is an optional Claude add-on — see Using Cubby with Claude — not a requirement for any of the three.
Why a thin prompt, not a giant one. The paste prompt’s job is not to teach your agent everything — a static block can’t stay correct per template and will drift. Its job is to get the agent to run cubby init, then read the generated CUBBY.md / AGENTS.md / CLAUDE.md, which are template-aware and authoritative. Those generated files override this website where they disagree.

​
The paste prompt

Paste this into Codex, Claude Code, or Cursor at the start of a Cubby project: 
You are building an app to deploy on Cubby (cubby.pro). Follow this exact order and
do not invent your own steps.

1. Install the CLI: `npm install -g cubbypro` (skip if already installed).
2. Authenticate: `cubby login <my-email>` (positional email works; add --force to
   re-auth). Then run `cubby whoami` to confirm identity — that is the reliable check.
3. Choose a template DELIBERATELY, then scaffold:
   - nextjs-sqlite (DEFAULT) — full-stack Next.js with a simple embedded SQLite DB.
     Most apps. No external database to manage.
   - nextjs-neon — full-stack Next.js + Neon POSTGRES. Choose only when I need real
     Postgres features, heavy relational data, or DB branching/snapshots.
   - nextjs — Next.js with NO database (frontend-only).
   - byo — bring my own Dockerfile.
   Run `cubby init <name> --template <choice>` (or `cubby init . --template <choice>`
   to scaffold into the current directory). Do NOT rely on the non-interactive
   default — pass --template so the choice is mine.
   The default template is SQLite, NOT Postgres. Do not assume Postgres.
4. READ the generated CUBBY.md, AGENTS.md, and CLAUDE.md in the project now. They are
   template-aware and OVERRIDE anything on the Cubby website. Follow them.
5. Data scoping — decide before writing any schema. DEFAULT TO SHARED: one deployment
   = one shared dataset. Cubby's gateway already restricts access to the owner +
   explicitly-shared users, so do NOT key rows by x-cubby-user-id unless I explicitly
   say the app is per-user. The x-cubby-user-id header is an access gate, not a
   partition key. A family/team/household seed means the data is SHARED.
6. ASK me about local dev: "Do you have Docker (for a local database), or is
   frontend-only local dev fine?" Then:
   - SQLite / no-DB template → `npm run dev` (no Docker, no local test DB).
   - Neon template → `cubby dev` (requires Docker for a local Postgres).
   Do not start a Prisma/Docker rabbit hole on a SQLite app.
7. Validate: `cubby check` (read-only). Run it once and fix what it flags.
8. Deploy: `cubby deploy` (async, ~3–5 min; a live elapsed timer means it is safe to
   wait).
9. Secrets come AFTER the first deploy. Use `cubby secrets set <NAME> --env prod`
   (NAME only — it prompts for the value; no KEY=VALUE, no --app flag). The default
   env is local, so pass --env prod for production. Then redeploy or run
   `cubby secrets apply --env prod`.

Never build your own auth (Cubby SSO authenticates every request — read x-cubby-user-id
and x-cubby-username headers in API routes). Never commit secrets. Memory, CPU, HTTPS,
and billing are Cubby's job, not the app's.
Replace <my-email> with the email on your Cubby account before pasting, or your agent will ask for it on step 2.

​
What happens after cubby init

cubby init writes the same template-aware brief into three files, one per agent:
AgentFile it readsNotes
CodexAGENTS.mdSee Using Cubby with Codex
ClaudeCLAUDE.mdSee Using Cubby with Claude (MCP optional)
Cursor.cursor/rules/cubby.mdcSee Using Cubby with Cursor
All three contain the same canonical order as the prompt above, plus the template-specific detail (Docker vs no-Docker, SQLite vs Postgres, the data-scoping worked example). Because they are generated per template, they are correct for your app in a way a static prompt cannot be. The richer CUBBY.md is the deep-dive companion.

​
The canonical order (reference)

This is the order encoded in the generated files and the prompt above:
1

Install

npm install -g cubbypro
2

Log in

cubby login <email> then cubby whoami to confirm.
3

Choose a template, then scaffold

cubby init <name> --template <choice>. Default is SQLite, not Postgres.
4

Read the generated files

CUBBY.md / AGENTS.md / CLAUDE.md — they override this site.
5

Decide data scoping — default shared

One deployment = one shared dataset. The auth header is an access gate, not a partition key.
6

Ask about local dev (Docker)

SQLite / no-DB → npm run dev (no Docker). Neon → cubby dev (Docker).
7

Validate

cubby check — run once, fix what it flags.
8

Deploy

cubby deploy — async, ~3–5 min.
9

Secrets after first deploy

cubby secrets set <NAME> --env prod, then redeploy / cubby secrets apply --env prod.

​
Data scoping — default to shared

The single most common mistake: keying every row by the signed-in user. Cubby’s gateway already controls who can open the app (owner + explicitly-shared users). The x-cubby-user-id header answers “is this person allowed in?” — never “whose row is this?”
  • Default to SHARED. One deployment = one shared dataset. Proceed shared unless you explicitly declare the app per-user.
  • Auth gate ≠ partition key. Do not use x-cubby-user-id as a where filter unless the app is genuinely per-user.
  • localStorage → DB is the trap moment. Porting a single-browser prototype tempts “one row per user” — re-examine scope right then.
  • A family / team / household seed is a tell the data is shared. Want a separate group? Deploy a separate copy.

​
Local dev — ask first

Always ask the user “do you have Docker, or is frontend-only local dev fine?” before running anything locally — don’t guess.
  • SQLite (nextjs-sqlite) or no-DB (nextjs): npm run dev — no Docker, no local test DB. On a SQLite app, Cubby runs prisma db push for you on deploy. If you want a live local DB to click through, the data/ dir must exist FIRST (mkdir -p data, then npx prisma db push, which creates the SQLite file); without the data/ dir prisma db push fails with P1003 Database does not exist. Never use a ../ DATABASE_URL.
  • Neon (nextjs-neon): cubby dev — requires Docker running (it spins up a local postgres:17-alpine). No Docker? Point DATABASE_URL at a real Neon branch in .env.local and run npm run dev.
See cubby dev for the full local-dev reference.