---
title: Import an existing project
description: Take a Next.js or Node app you already have and run it on CoDuck.
category: projects
order: 1
agent: "'coduck create-existing' imports the current directory as a CoDuck project. Auto-detects Next.js / Vite / Express / Nest from package.json. Writes coduck.json. One CoDuck project = one Docker container."
---

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

> [!NOTE]
> Be specific in your first prompt. "An online store for handmade products with Stripe checkout, product reviews, and a seller dashboard" gives CoDuck enough to scaffold something real; "a store" does not.

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

```bash
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`](/docs/reference/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.

> [!NOTE]
> One CoDuck project = one container. If your repo has a separate frontend and backend in subdirectories, either wrap both into a single start command (e.g. with `concurrently`), or create two CoDuck projects and wire them together with an env var pointing the frontend at the backend's public URL.

### 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](/docs/database/overview).
- **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

| Feature | Notes |
|---|---|
| Container | 1.5 GB RAM, 1.0 CPU, runs as non-root |
| Postgres database | Per-project, auto-provisioned, connection injected as `DATABASE_URL` |
| Subdomain | `<project>.coduck.app` with HTTPS automatic |
| Backups | Nightly automatic + on-demand |

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

## Next

- [Deploying](/docs/projects/deploy)
- [Custom domains](/docs/domains/custom-domains)