Skip to main content

​
cubby dev

Start a local development environment. This gives your app a Cubby-shaped runtime locally: hot reload, local secrets, and a DATABASE_URL that matches the database path you chose.
cubby dev runs your app in a container and requires Docker — it is the right tool when you want a local Neon Postgres database (it runs a local postgres:17-alpine). For the default SQLite template (or a no-database app), you do not need cubby dev or Docker at all: just run npm run dev. Cubby runs prisma db push for you on deploy, so no local database is required for frontend work. See cubby init.

​
Usage

​
Flags

​
Examples

​
What Happens

  1. Validation - Checks for cubby.yaml and Docker
  2. Port detection - Finds available ports (default: 3000 for app)
  3. Secret injection - Loads local secrets (set via cubby secrets set)
  4. Compose generation - Creates docker-compose.dev.yml
  5. Container build - Builds your app container
  6. Database setup - Prepares the local database environment for your selected template
  7. Schema sync - Runs prisma db push when Prisma is present
  8. Log streaming - Shows app and database logs when available

​
Output

​
How It Differs from npm run dev

​
Database Persistence

Data persists between cubby dev sessions in the local database storage for your selected template. To start fresh:
This deletes local development data and creates a fresh database.

​
Local Secrets

Secrets set with cubby secrets set are automatically injected:
The secret is available as process.env.OPENAI_API_KEY in your app.

​
Port Conflicts

If the default app port is in use, cubby dev automatically finds an alternative:

​
Stopping Development

Press Ctrl+C to stop. This:
  • Kills log streaming
  • Stops containers
  • Cleans up docker-compose.dev.yml
Your database data is preserved for next time.

​
Requirements

  • Docker must be running (required for cubby dev; not required for npm run dev on a SQLite or no-database app)
  • Project must have cubby.yaml (run cubby init first)

​
Troubleshooting

​
”Docker is not running”

Start Docker Desktop and try again.

​
”Not a Cubby app directory”

Run cubby init first, or cd to a directory with cubby.yaml.

​
”Database failed to become healthy”

This applies to the Neon/Postgres local container. It may be slow to start — try:
On a SQLite app you don’t need cubby dev at all — run npm run dev instead (no Docker, no database container).

​
Schema Sync Warning

If prisma db push fails, you’ll see a warning but dev continues:
Run npx prisma db push manually to see the full error.