#Creating a project

A project on CoDuck is one container plus one private Postgres database plus one subdomain on .coduck.app. There are two ways to create one: describe what you want to build (the usual path), or bring code you already have.

#Describe what you want

Sign in at https://coduck.ai. The home page has a prompt textarea — its placeholder rotates through example ideas like "Generate an online store for selling handmade products." Type what you want to build in plain English and submit.

CoDuck's AI scaffolds a Next.js + Postgres app, generates the code, provisions the database, and opens the project in the editor. From there, the chat on the left lets you keep iterating — ask for a checkout flow, a new page, a schema change, and CoDuck edits the code in place.

#Bring existing code

If you already have a Next.js, Vite, Express, or Nest app on disk, CoDuck adopts the folder as a project, provisions a database, and deploys it under a .coduck.app subdomain — keeping your source layout and tooling.

npm install -g @coduckai/cli
coduck login
cd my-app
coduck create-existing            # auto-detects runtime + build/start from package.json
coduck push                       # upload source
coduck deploy                     # build + run

npm install -g @coduckai/cli
coduck login
cd my-app
coduck create-existing            # auto-detects runtime + build/start from package.json
coduck push                       # upload source
coduck deploy                     # build + run

create-existing writes a coduck.json at the repo root describing how to build and run your app. It auto-detects most fields; edit them and re-push/deploy to change how the deploy behaves (the file is re-read on every deploy). Flags like --dir ./web, --start, --build, --pre-start, and --push --deploy let you do it in one shot.

#Gotchas when importing an existing app

These trip people up most often — check them before your first deploy:

• Bind process.env.PORT. CoDuck assigns the port; an app hardcoding 3000 fails the health check. The port in coduck.json is informational only.
• The database starts empty. CoDuck provisions Postgres but not your tables. Run migrations in a preStart command (e.g. prisma migrate deploy, drizzle-kit push) or you'll hit relation "…" does not exist. See Database.
• Some env keys are reserved (DATABASE_URL, NODE_ENV, CODUCK_*, …). Setting them is rejected; coduck env import skips them and imports the rest. List them with coduck env reserved.
• Heavy builds may need a bigger instance. If the build OOMs on the default small tier, deploy with coduck deploy --size large.
• Monorepo? If your app lives in a subdirectory, set dir and use @coduckai/cli ≥ 0.1.11 so the root coduck.json is delivered to the server.

#Inside a project

After it's created, a project lives at https://app.coduck.ai/project/<id>. The list of all your projects is at https://app.coduck.ai/projects.

The project view has three regions:

• Chat (left). Where you talk to the AI agent — describe changes, ask questions about the code, request new features.
• Editor (center). The generated source tree, openable and editable.
• Cloud panel (right, or switchable). Everything operational. Tabs: Settings, Hosting (with sub-tabs for Domains, Env, Deploys, API Key), Analytics, Data, Logs, Forms, Email, Payments, Activity.

You can drive almost everything from chat or the Cloud panel — set an env var, attach a custom domain, inspect logs, browse the database — without leaving the project.

#What comes with each project

Custom domains, environment variables, deploy history, and the rest are managed from the Hosting tab of the Cloud panel.

#Next

• Deploying
• Custom domains