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.

​
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

cubby dev [flags]

​
Flags

FlagDescriptionDefault
--resetReset database (deletes all local data)false
--prod-modeSimulate production environment (NODE_ENV=production)false

​
Examples

# Start development
cubby dev

# Start fresh with empty database
cubby dev --reset

# Test production build locally
cubby dev --prod-mode

​
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

Starting development environment...
Finding available ports...
Injecting 2 local secret(s)
Generating Docker Compose configuration...
Building containers (this may take a moment on first run)...
Starting containers...
Waiting for database to be ready...
Database schema synchronized
Development environment ready!

  App:      http://localhost:3000
  Database: file:./dev.db

Streaming logs (Ctrl+C to stop)...

​
How It Differs from npm run dev

Featurecubby devnpm run dev
DatabaseCubby-shaped local DATABASE_URLManual setup required
SecretsInjected from cubby secretsManual .env file
EnvironmentProduction-like containerNode.js directly
Schema syncAutomaticManual prisma db push
CleanupAutomatic on Ctrl+CNone

​
Database Persistence

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

​
Local Secrets

Secrets set with cubby secrets set are automatically injected: 
# Set a secret for local development
cubby secrets set OPENAI_API_KEY

# Start dev (secret is injected)
cubby dev
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: 
Default port in use. Using: app=3001

​
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: 
cubby dev --reset
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: 
Schema sync warning: [error message]
Continuing without schema sync...
Run npx prisma db push manually to see the full error.