> ## 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 local development environment

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

<Note>
  `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`](/cli-reference/init).
</Note>

## Usage

```bash theme={null}
cubby dev [flags]
```

## Flags

| Flag          | Description                                             | Default |
| ------------- | ------------------------------------------------------- | ------- |
| `--reset`     | Reset database (deletes all local data)                 | `false` |
| `--prod-mode` | Simulate production environment (`NODE_ENV=production`) | `false` |

## Examples

```bash theme={null}
# 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`

| Feature     | `cubby dev`                       | `npm run dev`           |
| ----------- | --------------------------------- | ----------------------- |
| Database    | Cubby-shaped local `DATABASE_URL` | Manual setup required   |
| Secrets     | Injected from `cubby secrets`     | Manual `.env` file      |
| Environment | Production-like container         | Node.js directly        |
| Schema sync | Automatic                         | Manual `prisma db push` |
| Cleanup     | Automatic on Ctrl+C               | None                    |

## Database Persistence

Data persists between `cubby dev` sessions in the local database storage for your selected template.

To start fresh:

```bash theme={null}
cubby dev --reset
```

This deletes local development data and creates a fresh database.

## Local Secrets

Secrets set with `cubby secrets set` are automatically injected:

```bash theme={null}
# 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:

```bash theme={null}
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.

## Related Commands

* [`cubby init`](/cli-reference/init) - Create a new app
* [`cubby secrets`](/cli-reference/secrets) - Manage local secrets
* [`cubby deploy`](/cli-reference/deploy) - Deploy to production