# CoDuck

> CoDuck is a hosting, AI-build, and operations platform you drive from a single CLI. 
> Install: `npm install -g @coduckai/cli` — auth: `coduck login` — deploy: `coduck deploy`.

Web app: https://coduck.ai
CLI on npm: https://www.npmjs.com/package/@coduckai/cli
Full reference (single file): https://coduck.ai/llms-full.txt

## Start

- [Getting Started](https://coduck.ai/docs/raw/getting-started.md): The fast path — install, log in, import or scaffold a project, deploy. Read this first.

## Projects

- [Import an existing project](https://coduck.ai/docs/raw/projects/create-existing.md): '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.
- [Deploying](https://coduck.ai/docs/raw/projects/deploy.md): 'coduck deploy' builds and runs the project. 'coduck stop', 'coduck restart', 'coduck status', 'coduck logs --follow'. One Docker container per project on CoDuck's VPS, running with --network=host (so localhost inside the container IS the host's loopback). Container reachable at .coduck.app subdomain unless a custom domain is attached. Instance sizes: small (1 CPU / 1.5 GB), medium (2 CPU / 2.5 GB), large (3 CPU / 4 GB). See /docs/reference/runtime for the full runtime architecture (DB ports, networking, filesystem).

## Domains

- [Custom domains](https://coduck.ai/docs/raw/domains/custom-domains.md): Custom domains attach to a project via 'coduck domains add <domain>'. Two-phase verify (ownership + routing). TLS auto-issued via Let's Encrypt once verified.

## Database

- [Database](https://coduck.ai/docs/raw/database/overview.md): Each project has its own Postgres DB. DATABASE_URL is injected at runtime — it points at PgBouncer on the VPS loopback at 127.0.0.1:6432 (transaction-pool mode, max_prepared_statements=100, ?pgbouncer=true&connection_limit=1 already applied). Works for ALL stacks — Prisma, drizzle-orm, node-postgres, knex, sequelize. DIRECT_URL points at postgres directly at 127.0.0.1:5433 — used by 'prisma db push' / 'prisma migrate deploy' only, NOT the runtime request path. Read-only introspection via 'coduck db schema' / 'coduck db tables --table users'. No external connection URL exposed. Footgun: 'DROP SCHEMA public CASCADE' destroys the PgBouncer auth function (user_lookup) and breaks DATABASE_URL — don't do that. See /docs/reference/runtime for the container + networking model.

## Email

- [Sending email](https://coduck.ai/docs/raw/email/sending.md): Send transactional email from app code with a server-side POST to ${CODUCK_API_URL}/email/send using 'Authorization: Bearer ${CODUCK_API_KEY}' (both env vars are injected at deploy). From must be a verified domain or noreply@${NEXT_PUBLIC_CODUCK_PROJECT_SUBDOMAIN}.coduck.app. Also available from the terminal via 'coduck email send' once a domain is verified with 'coduck email domains add / verify'. SES-backed; includes suppression list and pause/resume. There is no @coduckai/sdk email helper yet.

## Payments

- [Stripe payments](https://coduck.ai/docs/raw/payments/stripe-connect.md): Connect a Stripe account to a project via 'coduck stripe connect' — OAuth flow. Your app receives payments to that account directly. CoDuck's CODUCK_STRIPE_KEY env var is auto-injected. Status/transactions/revenue via 'coduck stripe payments'.

## SDK

- [SDK overview](https://coduck.ai/docs/raw/sdk/overview.md): @coduck/sdk reference. Auto-installed + env-configured at deploy. Modules: root client (coduck.meta), @coduck/sdk/server (cookie auth: getSession/signInWithPassword/signUpWithPassword/signOut), @coduck/sdk/client (useUser hook), @coduck/sdk/auth (low-level AuthClient), @coduck/sdk/forms, @coduck/sdk/storage, @coduck/sdk/analytics. Server modules need CODUCK_API_KEY; auth needs CODUCK_AUTH_KEY (deploy-only).
- [Auth](https://coduck.ai/docs/raw/sdk/auth.md): @coduck/sdk auth. Server (cookie-based, @coduck/sdk/server): getSession()->{user}|null, signUpWithPassword(email,password,name?), signInWithPassword(email,password), signOut(). Client (@coduck/sdk/client): useUser(meUrl='/api/me')->{user,loading,refresh} — needs a GET /api/me route returning {user}|null. Low-level (@coduck/sdk/auth): auth.signup/login/refresh/verify/me/logout with AuthSession{user,accessToken,refreshToken,expiresIn}. Requires CODUCK_AUTH_KEY, injected only on deploy — auth does NOT work in the in-editor preview.
- [Forms](https://coduck.ai/docs/raw/sdk/forms.md): @coduck/sdk/forms. submit(formName, fields) is PUBLIC/browser-safe (needs NEXT_PUBLIC_CODUCK_PROJECT_ID). list({formName?,limit?}) and markRead(id) require CODUCK_API_KEY (server only). FormSubmission{id,projectId,formName,fields,submitterIp,userAgent,read,createdAt}. Submissions also appear in the cloud panel Forms tab.
- [Storage](https://coduck.ai/docs/raw/sdk/storage.md): @coduck/sdk/storage. list()->StoredFile[], upload(name, Blob|Buffer|Uint8Array)->StoredFile, delete(name), url(name)->string. Requires CODUCK_API_KEY (server only). 50MB/file cap; names limited to letters/digits/+._-. StoredFile{name,size,modifiedAt}.
- [Analytics](https://coduck.ai/docs/raw/sdk/analytics.md): @coduck/sdk/analytics. track(name, properties?)->void, or the bound `track` export. Requires CODUCK_API_KEY (server only). Pageviews are captured automatically from nginx logs — use track() for custom events (signups, purchases, etc.).

## CLI

- [Install the CLI](https://coduck.ai/docs/raw/cli/install.md): Install via 'npm install -g @coduckai/cli'. Requires Node 20+. Verify with 'coduck --version'.
- [Authentication](https://coduck.ai/docs/raw/cli/auth.md): Run 'coduck login' — opens a browser, user approves, CLI gets a 90-day token. No password handling in the CLI ever. 'coduck token list', 'coduck token revoke <id>', 'coduck logout'.
- [Commands reference](https://coduck.ai/docs/raw/cli/commands.md): Comprehensive CLI command reference. Auth, projects, files, deploy, generate, env, domains, db, email, storage, stripe, backups, activity, tokens. All commands honor --json and --no-input for agent use.

## Reference

- [coduck.json reference](https://coduck.ai/docs/raw/reference/coduck-json.md): Authoritative reference for coduck.json — the per-project config that drives every deploy. Fields: dir, runtime, install, build, preStart, start, port, instanceSize. Re-read on EVERY deploy (edit + push to change). Also lists reserved env keys and the deploy phase order. Read this before debugging why a build/start/migration didn't run as expected.
- [Runtime architecture](https://coduck.ai/docs/raw/reference/runtime.md): One Docker container per project on CoDuck's VPS. --network=host: localhost inside the container IS the host's loopback (no proxy, shim, or NAT). DATABASE_URL points at PgBouncer on 127.0.0.1:6432 (transaction-pool mode; max_prepared_statements=100 server-side, so prepared-statement-using clients like drizzle-orm/node-postgres/knex/sequelize work; ?pgbouncer=true&connection_limit=1 already applied for Prisma) — this is the runtime request path for ALL stacks. DIRECT_URL points at postgres directly on 127.0.0.1:5433 — used by Prisma's schema engine ('prisma db push' / 'prisma migrate deploy'), NOT the runtime path. Footgun: running 'DROP SCHEMA public CASCADE' on your project DB destroys the PgBouncer auth function (user_lookup) and breaks DATABASE_URL until restored — don't do that. Container runs as uid 1001 with working dir /app. Read this when reasoning about what a connection string, env var, or 'localhost:...' actually points at.

## Changelog

- [Changelog](https://coduck.ai/docs/raw/changelog.md): What changed in CoDuck recently — platform (hosting/deploy) and CLI releases, newest first. Check here before assuming old behavior: if a deploy or CLI behavior seems different from what you expect, a recent change probably explains it.