> ## 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

> Build and ship Cubby apps with OpenAI Codex using the CLI and the generated AGENTS.md

# 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.

<Info>
  The fastest start is the agent-neutral [Expert from paste](/tutorials/expert-from-paste)
  prompt — it works in Codex verbatim. This page is the Codex-specific detail.
</Info>

## 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.

## Recommended flow

<Steps>
  <Step title="Paste the bootstrap prompt">
    Drop the [Expert from paste](/tutorials/expert-from-paste) prompt into Codex with
    your email filled in.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.**
  </Step>

  <Step title="Have Codex read AGENTS.md">
    Tell Codex: *"Read AGENTS.md and follow it."* It overrides anything on the Cubby
    website.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Local dev — Codex should ask you">
    SQLite / no-DB → `npm run dev` (no Docker). Neon → `cubby dev` (Docker).
  </Step>

  <Step title="Check and deploy">
    `cubby check`, then `cubby deploy`. Deploy is async (\~3–5 min) with a live timer.
  </Step>

  <Step title="Secrets after the first deploy">
    `cubby secrets set <NAME> --env prod`, then redeploy or `cubby secrets apply --env prod`.
  </Step>
</Steps>

## 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.

## Related

* [Expert from paste](/tutorials/expert-from-paste) — the paste prompt
* [Using Cubby with Cursor](/tutorials/using-with-cursor)
* [Using Cubby with Claude](/tutorials/using-with-claude) — adds an optional MCP path
* [CUBBY.md file](/platform/cubby-md)