Local Development

Run Gencow locally with Bun, PGlite, local storage, and hot reload

gencow dev uses cloud development by default. Add --local when you want the API, database, storage, and Admin Dashboard to run on your computer.

Choose a Development Mode

Mode Command Database Best for
Cloud development bunx gencow@latest dev Managed cloud PostgreSQL Testing the same hosted runtime used by deployed apps
Local development bunx gencow@latest dev --local PGlite in .gencow/data/ Offline work, fast iteration, and disposable local data

Cloud development requires authentication:

bunx gencow@latest login
bunx gencow@latest dev

Local development does not require a cloud login:

bunx gencow@latest dev --local

GENCOW_LOCAL=1 is also supported for scripts:

GENCOW_LOCAL=1 bunx gencow@latest dev

What Local Mode Starts

  • Hono API server with Bun hot reload, normally at http://localhost:5456
  • Admin Dashboard at http://localhost:5456/_admin
  • PGlite data under .gencow/data/
  • Local file storage under .gencow/uploads/
  • Migration generation and typed client codegen
  • Local cron execution for registered defineApi({ crons }) schedules

Cloud-only durability does not apply to a stopped local process. Scheduled work and workflows that must survive sleep, crashes, or deploys should be verified in cloud development before production.

Environment Files

Local env files are split by responsibility:

File Purpose
Root .env Frontend build-time variables such as VITE_API_URL
gencow/.env Backend secrets and runtime variables for local mode

Example root .env:

VITE_API_URL=http://localhost:5456

Example gencow/.env:

MY_BACKEND_API_KEY=replace-me

Both files are gitignored by gencow init. Do not put backend secrets in root .env when the frontend can bundle or expose them.

Local AI Key

Cloud AI calls use platform-managed credentials. Set a provider key only when testing a supported local direct/fallback path:

# gencow/.env
OPENAI_API_KEY=replace-me

Database Commands

# Generate versioned SQL migration files without connecting to a database
bunx gencow@latest db:generate

# Apply the local desired-state development path
bunx gencow@latest db:push --local

# Run gencow/seed.ts against the running local server
bunx gencow@latest db:seed --local

# Back up and reset local data
bunx gencow@latest db:reset --local

# Restore the newest local backup
bunx gencow@latest db:restore

db:reset is local-only. Cloud database resets remain protected and are not performed by the CLI. db:studio is not available yet; use the local Admin Dashboard to inspect tables.

Cloud db:push uses an immutable migration bundle and journal. The --local path is intentionally a direct local development path and is not evidence that a cloud migration is safe. Use db:check before managed cloud migration work.

Local Logs

bunx gencow@latest logs --lines 100
bunx gencow@latest logs --follow

For cloud logs, use bunx gencow@latest deploy logs instead.

Switching Back to Cloud

Local backend variables are not uploaded automatically. Push only the backend env file you intend to deploy:

bunx gencow@latest login
bunx gencow@latest env push
bunx gencow@latest dev

Review secrets before env push; root frontend .env is not used as the backend env source.

Next Steps

Hosting & Custom DomainsWorkflow Agents