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.

​
Using Cubby with Codex

Codex works with Cubby through the CLI and the AGENTS.md file that cubby init generates in your project. No MCP server is required — Codex reads AGENTS.md automatically, and that file carries the full, template-aware Cubby contract.
The fastest start is the agent-neutral Expert from paste prompt — it works in Codex verbatim. This page is the Codex-specific detail.

​
How Codex gets Cubby context

When you run cubby init, the scaffold writes AGENTS.md into the project root. Codex reads AGENTS.md as standing instructions, so the moment the file exists, Codex knows Cubby’s rules: never build auth, default to a shared dataset, choose the template deliberately, set secrets with --env prod after the first deploy, and the recovery loop when a deploy fails. The contract is template-aware — a SQLite app and a Neon app get different local-dev instructions.
1

Paste the bootstrap prompt

Drop the Expert from paste prompt into Codex with your email filled in.
2

Let Codex install and log in

npm install -g cubbypro, then cubby login <email>. Codex runs cubby whoami to confirm — that is the reliable identity check; it does not false-report “Session expired” on a valid session.
3

Scaffold with an explicit template

cubby init <name> --template <choice>. The non-interactive default is nextjs-sqlite (and the CLI prints a one-line nudge when you omit --template), so pass --template to make the choice yours. Default is SQLite, not Postgres.
4

Have Codex read AGENTS.md

Tell Codex: “Read AGENTS.md and follow it.” It overrides anything on the Cubby website.
5

Decide scope, then build

Default to a shared dataset (one deployment = one shared dataset). Only key rows by x-cubby-user-id if the app is explicitly per-user.
6

Local dev — Codex should ask you

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

Check and deploy

cubby check, then cubby deploy. Deploy is async (~3–5 min) with a live timer.
8

Secrets after the first deploy

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

​
Codex sandbox notes

Codex usually runs in a sandbox. Two things to keep in mind:
  • Deploys are async. cubby deploy returns a deploy ID and shows a live elapsed timer; it is safe for Codex to wait the full 3–5 minutes rather than abort.
  • The scaffold ships no test runner. npm test has no script unless you add one — don’t treat a missing test script as a failure. Use cubby check as the gate.
If Codex’s environment has no local filesystem for an MCP transport, that does not matter here — Codex uses the CLI, not MCP, so cubby deploy runs in its shell directly.

​
Common pitfalls (and the current truth)

  • Don’t reason from a Postgres-default assumption. The default scaffold is SQLite-on-a-persistent-volume. If you need Postgres, choose nextjs-neon.
  • Don’t go down a local prisma db push rabbit hole on a SQLite app. Cubby runs prisma db push for you on deploy. Locally, npm run dev needs no DB. If you want a live local DB, create the data/ dir first (mkdir -p data) before npx prisma db push (which creates the SQLite file), or you hit P1003 Database does not exist. Never rewrite file:./data/app.db to a ../ path — it escapes the project.
  • Set secrets with --env prod. The default env is local; a bare cubby secrets set NAME writes a local secret that never reaches production.