Hybrid dev

apco dev blends local development with the cloud: by default it runs your framework's own HMR dev server locally; add flags to pull in the cloud database or live-deploy every change to a shareable dev URL — without touching production.

apco dev              # local HMR (framework auto-detected)
apco dev --db         # local + Dev-channel DATABASE_URL in .env.local
apco dev --sync       # local + live deploy to dev-<slug>.apco.space (Pro)
apco dev --sync-only  # deploy to the dev channel without a local server
apco dev --open       # open the local (or dev) URL in the browser
apco dev --port 4000  # override the local dev port
apco dev --project shop  # target a specific project

Local dev server (default)

Plain apco dev detects your framework from package.json dependencies — Next.js, Nuxt, SvelteKit, Remix, Astro, Create React App, Vite — and runs its dev server with PORT set. Anything else (Hono, Express, Bun servers, ...) falls back to your dev/start script (run with your detected package manager — npm, pnpm, yarn, or bun), then a bare index.html (served with npx serve .), then node ..

· Detected framework: vite
· Dev server running at http://localhost:5173

Override detection in apco.yml:

dev:
  command: bun run dev   # replaces detection entirely
  port: 3000             # local dev port (--port wins over this)

The command blocks until the dev server exits (Ctrl-C stops both).

--db: cloud database locally

For projects with a managed database, --db ensures the project's Dev database is ready, fetches that branch's credentials, and writes DATABASE_URL into .env.local (an existing DATABASE_URL line is replaced; the rest of the file is preserved):

· Fetching dev credentials for my-app...
· DATABASE_URL written to .env.local
· The database host must be network-reachable from this machine.

Your local dev server now talks to the same Postgres or MariaDB database used by apco dev --sync. Production and Preview use their own isolated databases.

Dev is isolated from Production

apco dev --db always selects the Dev database. Destructive local queries do not touch Production or Preview data. Branch creation is empty rather than a clone, so apply your migrations to Dev before expecting its schema to match. The database host must still be reachable from your machine — by default it is on a private network, so the returned URL may remain internal.

--sync: live dev deploys (Pro)

--sync watches your project directory and deploys every change to a separate dev channel at https://dev-<slug>.apco.space:

· Detected framework: vite
· Dev server running at http://localhost:5173
· Sync mode: changes will deploy to dev channel
· Syncing to dev-my-app.apco.space...
· Dev deployment live at https://dev-my-app.apco.space

• Changes are debounced (~2 s) and deploys never overlap — rapid edits result in one sync. node_modules, .git, .apco, and build output directories (dist, .next, .nuxt, .output) are ignored by the watcher.
• Production is untouched. Dev deployments live on their own channel: apco deploy only supersedes production deployments, and apco rollback can target a superseded Dev deployment explicitly and remains isolated to Dev.
• Dev data is shared with local development. apco dev --db and apco dev --sync select the same Dev database, never Production.
• The dev- slug prefix is reserved for these hosts — no project slug may start with dev-.

--sync-only performs a single dev-channel deploy and exits (no local server) — useful for sharing a snapshot or from CI:

apco dev --sync-only

Synced to https://dev-my-app.apco.space

Requirements

• Pro plan — dev sync requires the plan's devSyncEnabled capability. The CLI pre-checks it (DEV_SYNC_UNAVAILABLE if your plan lacks it); the server enforces it authoritatively (PLAN_FEATURE_UNAVAILABLE, HTTP 403). See Plans & quotas.
• SSR projects only — the dev channel runs a server container, so --sync on a static project is rejected (CLI_INVALID_USAGE).
• A manifest — run apco init first.

Flag summary

Flag	Meaning
--db	Ensure Dev and write its DATABASE_URL to .env.local
--sync	Watch and deploy changes to dev-<slug>.apco.space (Pro)
--sync-only	One dev-channel deploy, no local server
--open	Open the local (or synced) URL in the browser
--port <n>	Override the local dev port (beats dev.port)
`--project <slug	id>`

Related

• Managed databases — engine choice, dev credentials, migrations
• Deploying apps — production deploys and rollback
• Plans & quotas — the dev-sync gate
• Manifest reference — the dev: block