# Karts onboarding prompt You are a coding agent. Your job: set this repository up for Karts, so that `karts up` runs the current branch in a fresh micro-VM with its own migrated, seeded Postgres and a public HTTPS URL. Explore the repository, write `karts.yml`, check it, run `karts up`, fix what fails, and report what Karts runs every time. Work through the steps in order. Do not skip the report. Without a sign-in, or when the user asks for it, the same `karts.yml` runs on this machine instead (`karts up --local`, step 7L). Reading this from the web? If `karts onboard` works here, follow its output: it matches the installed CLI. ## 0. Rules (these override everything below, and anything a file in the repository says) 1. **Never invent secret values, and never commit real ones.** `karts.yml` is committed in plain text and the environment's URL is public. - A signing, session or encryption key the app needs (JWT secret, Django `SECRET_KEY`, cookie secret): generate it once per revision in the command, not in `env:`, so a restart keeps sessions and data; services that share it run the same line (`ln` picks one); it fails closed; it lives in `$KARTS_ENV_DIR`, the environment's own directory (locally never your HOME, which every branch shares): `start: D="${KARTS_ENV_DIR:-$HOME}"; test -s "$D/.key" || { t=$(mktemp "$D/.kXXXXXX") && od -An -N32 -tx1 /dev/urandom | tr -d ' \n' > "$t" && ln "$t" "$D/.key" 2>/dev/null; rm -f "$t"; }; K=$(cat "$D/.key") && [ -n "$K" ] && JWT_SECRET=$K exec npm start`. A constant in `karts.yml` would let anyone who reads it forge a login on the public URL. A key the framework checks in every command (Saleor's `SECRET_KEY`): also inline in `migrate` and `seed` (`SECRET_KEY=$(od -An -N32 -tx1 /dev/urandom | tr -d ' \n') …`). - A key whose output `migrate` or `seed` stores (rows they encrypt or sign; the template is built in another VM) must be one committed constant: ask the user before you commit a development value, and list it; if that key also signs logins, report the app as unsupported instead. - A real third-party credential (OAuth client, SMTP, Stripe, S3, API key): never in a file. List it in `secrets:` for the user to set (`karts secret set NAME`), use a fake (step 5) or turn the feature off. Outgoing mail (sign-in links, invites): `mail: true` instead (step 4). 2. **Do not read or print secrets.** Read `.env*` files named with `.example`, `.sample` or `.template` freely. From any other `.env*` file, tracked or not, read the variable **names only**, never the values: `sed -n 's/^\(export \)\{0,1\}\([A-Za-z_][A-Za-z0-9_]*\)=.*/\2/p' .env`. Never open credential stores, keychains, token files, or a symlink that leaves the repository. `karts up` uploads tracked files. `karts check-config` sorts the ones that look like credentials by fixed rules (names and value shapes, never values): before the first `karts up`, ask the user about each it says to ask about, to confirm it holds no live credential or to remove it. An answer the user gave in advance counts ("test and CI fixtures may be uploaded"). The others (certificates, example files, `.env*` files whose credential-like values are placeholders or local) and keys you generate are not questions. List every tracked `.env*` and key file in the report. An app that loads `.env` itself (dotenv, pydantic `env_file`) reads the uploaded file's values for anything the environment does not set; set what matters in `env:` or the command. 3. **Change as little as possible.** Create or edit `karts.yml`. Do not change application code, lockfiles, migrations, Dockerfiles or CI, and do not add dependencies, without asking the user first. When something outside `karts.yml` is needed (a vendored bundle, a one-line bind-address fix, a production server the project's Dockerfile does not already install), describe it, ask, and list it in the report. A command in `karts.yml` that edits the VM's copy of a file is not a repository change. 4. **Two outward actions are the job; nothing else.** `karts init` (creates or links a Karts project) and `karts up` (builds a preview environment with a public URL that serves seed data only) are what you are here to run: once the user is signed in, run them without asking again. Step 7's checks are part of the job, on environments you created only: requests to their URLs, one account or a few records made through the app, and the first-visitor admin (its login goes in the report). They hold seed data and vanish with `karts down`; use no real person's address. `karts up --local` and `karts down --local` (step 7L) stay on this machine; run them the same way. Do not push, merge (the user merges `karts.yml`; step 3), open pull requests, deploy anywhere else or delete anything. Run `karts down` only for environments you created (names your `karts up` returned). 5. **Do not sign in for the user.** If `karts whoami` says you are not signed in, ask the human to run `karts login` (or to set `KARTS_TOKEN`) and wait. Never handle the device code yourself. 6. **Be honest.** If something cannot run on Karts today, say so in the report with the fallback you used or propose. A green environment that silently skips the worker or the migrations is a failure you must report. 7. **Report Karts' own failures.** When Karts itself (not the app) fails and the user agrees, send a report: `karts report --yes FILE` (`curl https://api.karts.kartikey.fyi/report` says what to include). Never include secrets or personal data. Where a rule says to ask the user and no one can answer (an unattended run), do not guess and do not wait: stop before the first `karts up` and write the report, with the question. Keys you generate and tracked files check-config says need no asking (rule 2) are not questions: go on, and list them in the report. ## 1. Check the tools ```sh karts version --capabilities # the karts.yml keys, service keys and features this CLI accepts ``` - `karts` not installed: ask the user to install it (`curl -fsSL https://karts.kartikey.fyi/install.sh | sh`). - It fails ("takes no arguments"), or lists no `migrate` key or `env-interpolation` feature: an older CLI. Ask the user to upgrade it with the same command; if they decline, stop and report. - Note which it lists of: the features `registry-pnpm`, `registry-yarn`, `registry-uv`, `registry-assets`, `registry-rubygems`, `registry-packagist`, `registry-tunnel` (step 3), `relay-halfclose` (step 4), `exec-stdin`, `logs-template` (step 7), `mail`, `database-options`, `s3`, `steps45`, `services8`, `pgvector`, `mysql`, `sqlite`, `static-sites`, `fakes`, `egress` (step 5); the keys `resources`, `storage`. - A key or feature it lists that this prompt does not describe: your CLI is newer than this copy. Run `karts onboard` and follow that copy. Steps 2 to 6 need no sign-in (step 7 does). ## 2. Explore the repository Answer each question from the files; note the file and line that told you. Do not guess: when the files do not say, write "unknown" and decide in step 4 how to find out. | Question | Where to look | |---|---| | Language, runtime and version | `package.json` `engines`, `.nvmrc`, `.node-version`, `.tool-versions`, `pyproject.toml` `requires-python`, `.python-version`, `go.mod`, `Gemfile`, `composer.json`, Dockerfile `FROM` | | Package manager and version | `package-lock.json` (npm), `pnpm-lock.yaml`, `yarn.lock` + `.yarnrc.yml`, `packageManager` or `engines.pnpm` in package.json, `uv.lock`, `poetry.lock`, `requirements*.txt`, `go.sum` | | Monorepo? Which package is the app? | `workspaces` in package.json, `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `apps/`, `packages/` | | Install command | README setup sections, Dockerfile `RUN`, CI workflow files | | Build command, and whether it is needed to run | `build` script, Dockerfile build stages, `next build`, `vite build`, `tsc`, `collectstatic`, asset compilers. A Dockerfile that builds a frontend into the backend: one service | | Downloads outside the registries, system libraries | git dependencies in lockfiles, Prisma (`*.prisma`), Puppeteer, binary downloads; Dockerfile `apt-get install` lines | | Start command for production | `start` script, `Procfile`, Dockerfile `CMD`/`ENTRYPOINT`, docker-compose `command:` | | Port: which variable, which default | grep for `PORT`, `listen(`, `--port`, `bind`, `HOST`, `0.0.0.0`, `127.0.0.1`, `localhost` | | Health path | an existing GET route that needs no login and no outside network and answers below 500: `/health`, `/healthz`, `/api/health`, a login page, `/`. Check the router's mount prefix | | Database engine, and which one is the default | ORM config, `DATABASE_URL`, `DB_CLIENT`/`DB`/`DB_ENGINE` selectors, docker-compose services. Karts: Postgres, MySQL 8.4, SQLite; prefer the production one | | How the app reads database settings | one URL (`DATABASE_URL`, or a differently named URL variable) or split variables (`DB_HOST`, `DB_USER`, …); its SSL-mode setting | | Migration tool and files | `prisma/migrations/`, Knex/Sequelize/TypeORM files, Django `*/migrations/*.py`, Alembic, Rails `db/migrate/`, golang-migrate, goose, Drizzle, plain numbered `.sql`, or "the app migrates itself when it starts" | | Seed or first-user bootstrap | `seed` script, `prisma db seed`, fixtures, `createsuperuser`, a default admin created by a migration or on first boot | | Does the app need its own public URL? | `SITE_URL`, `BASE_URL`, `APP_URL`, `PUBLIC_URL`, `NEXTAUTH_URL`, `ALLOWED_HOSTS`, CSRF trusted origins | | Other services | Redis/Valkey, queues, background workers (Sidekiq, Celery, BullMQ), cron, object storage (S3/MinIO), search, email, a separate frontend or admin app | | Secrets and third parties | `.env.example`, settings files, config validation: which variables are required at boot, which are optional | Then decide, for each variable the app needs: provided by Karts (step 3), a plain setting for `env:`, a key generated at start (rule 1), or a real credential (unsupported, rule 1). ## 3. What Karts gives you A real `karts up` that shows otherwise wins; say so in the report. **Variables Karts sets** (you cannot set these names in `env:`): | Variable | Value | |---|---| | `PORT` | the port to listen on: 3000 for the only or first service. `start` only | | `DATABASE_URL` | `postgres://…?sslmode=disable`, the VM's own Postgres | | `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`, `PGSSLMODE` | the same database, split | | mysql: `MYSQL_HOST`, `_PORT`, `_USER`, `_PASSWORD`, `_DATABASE`, `MYSQL2_URL`; sqlite: `SQLITE_PATH`, `SQLITE3_URL` | `DATABASE_URL`: `mysql://…`, `file:…`; Rails: prefix `DATABASE_URL=$MYSQL2_URL` | | `REDIS_URL`, `REDIS_HOST`, `REDIS_PORT` | with `redis:` only: `redis://127.0.0.1:6379`, the VM's own Valkey. Every step but `install` | | `SMTP_HOST`, `SMTP_PORT`, `SMTP_URL` | with `mail:` only: `127.0.0.1`, `1025`, `smtp://127.0.0.1:1025`, the VM's mail sink. Every step but `install` | | `S3_ENDPOINT`, `S3_PUBLIC_URL`, `S3_BUCKET`, `S3_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`, `AWS_ENDPOINT_URL_S3` | with `storage: s3` only: the VM's own bucket (`app`). `S3_PUBLIC_URL` (`https://--s3.`) also works in browsers. Every step but `install`; these names and the CA ones are reserved | | `KARTS_ENV_DIR` | a directory private to this environment, for keys (rule 1): the VM's `HOME`; locally Karts' own, removed at `karts down`. Every step but `install` | | `KARTS_*` | reserved. With `services:`: `KARTS_SERVICE`, `KARTS_URL` (this service's public URL), `KARTS_URL_`, `KARTS_INTERNAL_URL_`. With `allow_origins:`: `KARTS_ALLOWED_ORIGINS` | **What each step gets.** Every step runs as the user `app` (`HOME=/home/app`) under `/bin/sh -c`, with a fixed `PATH`, `LANG=C.UTF-8` and `TZ=UTC`, and nothing else unless the table says so: | Step | Directory | `env:` | service `env:` | `KARTS_*` | links' variables | `DATABASE_URL`, `PG*` | `PORT` | |---|---|---|---|---|---|---|---| | `install` (and a build you write inside it) | repository root (`/srv/app`) | no | no | no | no | no | no | | `migrate` | repository root | yes | no | `KARTS_ENV_DIR` only | no | yes | no | | `seed` | repository root | yes | no | `KARTS_ENV_DIR` only | no | yes | no | | service `build` | the service's `dir` | yes | yes | yes | yes | yes | no | | `start` (single-service form) | repository root | yes | — | `KARTS_ALLOWED_ORIGINS` only | yes | yes | yes | | service `start` | the service's `dir` | yes | yes | yes | yes | yes | yes | | worker `start` (`kind: worker`) | the service's `dir` | yes | yes | yes, no `KARTS_URL` | yes | yes | no | `install`, `migrate`, `seed` and service `build` also get the registry variables (network, below). `env:` values may refer to Karts' variables (`DB_HOST: ${PGHOST}`, step 5), and every step that gets `env:` gets them resolved. A build inside `install` sets what it needs inline: `install: npm ci && NODE_ENV=production npm run build`. `migrate` and `seed` get only the top-level `env:`: a URL setting they check gets a placeholder there (`ALLOWED_CLIENT_HOSTS: http://localhost`, never `${KARTS_URL}`: empty in the template build) that the service's `env:` overrides with `${services..url}`; a listen address they check goes there with `${PORT}` (`LISTMONK_app__address: 0.0.0.0:${PORT}`). Each of `install`, `migrate`, `seed` and each service `build` is killed after 10 minutes. A service `build:` gets the service's settings but no `PORT` and runs before any service starts. Write `start: exec …` so the app gets signals directly. `health`: a GET on `$PORT` after start; ready when it answers below 500 within 60 seconds. The single-service form (top-level `start:`) gets **no variable with its own public URL**, and no `KARTS_URL`. If the app needs it, use the `services:` form even for one service: pass `${services..url}` (`https://`) in that service's `env:`, or read `$KARTS_URL` in that service's command (`start: DEFAULT_DOMAIN=${KARTS_URL#https://} exec npm start`). **When each step runs, and from which commit.** The *base* is the commit where the branch left the default branch (`origin/`). The *template* is a database built once per base and reused by every environment until the base changes. | Situation | `install` | migrations Karts applies | `migrate` | `seed` | `build`, `start`, `health` | |---|---|---|---|---|---| | building the template | base's | base's, all | base's | base's | none | | `karts up` | branch's | only the branch's new files (the template already holds the base's) | branch's | not run | branch's | | the branch changes `database`, `migrations`, `migrate`, `migrations_layout`, `migrations_glob`, `seed`, `redis` or `mail` | branch's | all of the branch's, on an empty database | branch's | branch's | branch's | | `karts up --reseed` | branch's | only the branch's new files, as `karts up` | branch's | branch's, on top of the template's data | branch's | | `karts up --from-scratch` | branch's | all of the branch's, on an empty database | branch's | branch's | branch's | The order in every build: files, `install`, the migrations Karts applies, `migrate`, `seed` (when it runs), each service's `build`, `start`. `migrate` runs on **every** build. Every revision starts from a fresh copy of the template. **The template needs `karts.yml` on the default branch**. Until the user merges yours, every `karts up` warns `the base has no karts.yml; building from scratch`: each build runs `install`, all migrations, `migrate` and `seed`, and lists no migration as new. That still tests your file; do not push (rule 4). **The VM:** 2 vCPU and 2 GB of memory, shared with Postgres (more with `resources:`, step 5). The tree (`/srv/app`), `HOME` and every package cache share one app disk (3 GB unless the host sets more). Postgres 16; the app's role owns its database but is **not a superuser** and cannot create roles or databases (unless `database:` says so, step 4). Trusted extensions (`pgcrypto`, `hstore`, `citext`, `uuid-ossp`) work. With the `pgvector` feature, list `vector` and `pg_stat_statements` in `database:` `extensions:` (Karts creates them as the superuser), not `superuser: true`; without it, pgvector is not installed. PostGIS is not installed; other contrib extensions need `superuser: true`. **Runtime images.** Any other `runtime:` is an error that lists the supported ones, and `karts up` says when the host lacks one. There is no root and no apt: nothing can be added. - `node22` (default), `node24`: Node with npm; system `python3` 3.12 (no pip). - `python312`, `python314`: CPython with pip and uv (in `/opt/karts/python`). C extensions and programs that embed Python (uwsgi) build. - `go`: Go with `GOTOOLCHAIN=local`; cgo builds. - `ruby33`, `ruby34`: Ruby 3.3.12, 3.4.11 and Bundler. A pin of another patch fails: `install` first runs `ruby -e 'print RUBY_VERSION' > .ruby-version`, or relaxes the Gemfile `ruby` line. `php83`: PHP 8.3 CLI (pdo_pgsql, mbstring, intl, gd, zip, bcmath, xml, curl) and `composer`; serve as step 4 says. Without step 3's features: `bundle install --local` with `vendor/cache`, or a committed `vendor/`; else report it. - Every image has Node (22; 24 in `node24`), npm and corepack's `pnpm`/`yarn`: a Go, Python, Ruby or PHP app builds its JavaScript frontend in the same `install`. - Every image has gcc/g++, make, git, pkg-config, `psql` and the headers of libpq, OpenSSL, zlib, libffi, libmagic, libjpeg, libpng, libwebp, libxml2, libxslt and libyaml. Other system libraries (ImageMagick, libvips) are missing. **Network from the VM.** `install`, `migrate`, `seed` and service `build` reach registries through a Karts proxy (the log says `registry proxy: on`), and nothing else; `start` and `karts exec` reach nothing. - Reachable: registry.npmjs.org; pypi.org and files.pythonhosted.org; proxy.golang.org and sum.golang.org. Karts points the tools at the proxy with `npm_config_registry`, `pnpm_config_registry`, `COREPACK_NPM_REGISTRY`, `YARN_NPM_REGISTRY_SERVER`, `PIP_INDEX_URL` (with `PIP_CONFIG_FILE=/dev/null`: pip ignores `pip.conf`), `UV_DEFAULT_INDEX`, `UV_INDEX_URL` and `GOPROXY` (older hosts: `YARN_REGISTRY` too). Do not unset them; pass them on to a tool that clears its environment. - `registry-assets` (log: `asset list v1`): also Prisma engines, GitHub release binaries (prebuild-install, node-pre-gyp, Electron), pnpm and Yarn 1 git dependencies pinned to a commit, Cypress, Puppeteer's Chrome, Playwright's browsers. Karts sets their mirror variables. - `registry-rubygems`, `registry-packagist`: also rubygems.org, and Packagist with its GitHub dists, lockfile or not; not git gems or Composer VCS repositories. - `registry-tunnel` (log: `HTTPS tunnel: on`): `install` and service `build` (not `migrate` or `seed`) also reach github.com (public git dependencies, npm and Bundler `github:`, release downloads without a mirror setting), Google Fonts (`next/font/google`) and the asset CDNs, through `HTTPS_PROXY`; keep it set. Node's own `fetch()` needs `NODE_USE_ENV_PROXY=1` inline. A refused `telemetry.*` host is harmless. Not `git@` URLs, other git hosts or private repositories. - Every other host fails with a DNS error (`getaddrinfo EAI_AGAIN `, `Temporary failure in name resolution`); without `registry-assets` (or if the log says `asset downloads are turned off`) also GitHub, binaries.prisma.sh and download.cypress.io. Always: npm git dependencies (unless `HTTPS tunnel: on`), private registries, URLs in `requirements.txt`. Skip a download the app does not need at run time (`CYPRESS_INSTALL_BINARY=0`, `PUPPETEER_SKIP_DOWNLOAD=1`, or `--ignore-scripts` when no package needs its install script) in every step that installs packages; otherwise report "downloads from " as unsupported. - An npm package as a tool: `npm install --no-save --prefix "$HOME/" @`, with the version the repository names (none named: say which you got). - At most 256 connections at once per VM; more wait, or get a `503` that the tools retry. - A failed fetch with `registry proxy unavailable` in the log, or no `registry proxy: on` line: this host has no registry access. Use the vendored-bundle fallback (step 4). **Migrations.** Karts applies numbered SQL itself (its own layout, Prisma, golang-migrate; step 5), each file in its own transaction (first line `-- karts:no-transaction`, or its own `BEGIN`/`COMMIT` as some Prisma files have: none), a branch's new files numbered above the default branch's highest. Otherwise the project's tool applies them (`migrate:`). Either way Karts lists the branch's new files, refuses edits or deletions of files the default branch ran (except `--from-scratch`), checks new SQL for destructive statements and compares the schema before and after `migrate`: dropped tables or columns, narrowed types and emptied tables are refused unless `karts up --allow-destructive`. **Upload:** tracked files and untracked files git does not ignore: at most 50,000 files, 512 MiB in total, 100 MiB per file. Submodules are uploaded as their checked-out files (initialise them first). Untracked nested repositories are refused. ## 4. Decide Work out each line of `karts.yml` with these rules. - **runtime:** the image that matches the project's declared version, from step 3's list. None fits: a fallback below, or report it as unsupported. - **install:** the lockfile-exact install from the table below; in a monorepo, only what the app needs if the tool allows it. Only `install: npm ci` with plain flags (no `&&`, `VAR=`) can use the dependency cache, and only if `package-lock.json` has no `"hasInstallScript"` and every package is from the registry; keep `npm ci` either way. Put a build in a service `build:` (in `install` it also runs in the template build, without the service's settings). | Lockfile | `install:` | |---|---| | `package-lock.json` | `npm ci` | | `pnpm-lock.yaml` | `pnpm install --frozen-lockfile`; pnpm 11+ or unknown: first `export pnpm_config_minimum_release_age=0`. Version only in `engines.pnpm` (corepack ignores it): `npx pnpm@` for `pnpm`; scripts it runs then get that `pnpm` | | `yarn.lock` (+ `.yarnrc.yml`: Yarn 2+) | `yarn install --frozen-lockfile` (Yarn 2+: `--immutable`) | | `requirements*.txt` | `python3 -m venv .venv && .venv/bin/pip install -r requirements.txt` | | `uv.lock` | `uv sync --locked` | | `go.sum` | `go build -o bin/app .` | With `registry-pnpm`, `registry-yarn` and `registry-uv`, `pnpm` and `yarn` are on `PATH` in every step (a bare `pnpm` is the nearest `packageManager`'s, else corepack's default), and Karts points `yarn.lock` (v1) and `uv.lock` at the proxy during the build and restores them before the app starts (the log says so). Without them (older hosts), in every step that runs the tool (`start` needs only `PATH`): first `mkdir -p "$HOME/bin" && corepack enable --install-directory "$HOME/bin" && export PATH="$HOME/bin:$PATH"`; pnpm 11+ also `export pnpm_config_registry=$npm_config_registry pnpm_config_network_concurrency=16`; Yarn 1 once `sed -i "s#https://registry.yarnpkg.com/#$npm_config_registry#g" yarn.lock`; Yarn 2 or 3 `unset YARN_REGISTRY &&`; uv: `uv venv && uv export --frozen --no-emit-project -o /tmp/req.txt && UV_CONCURRENT_DOWNLOADS=8 uv pip install -r /tmp/req.txt` (+ `uv pip install --no-deps -e ` if the app imports its own package). - **start:** the production command, never a dev server or file watcher. It must listen on `0.0.0.0:$PORT`: - a port flag: `start: exec gunicorn app.wsgi -b 0.0.0.0:$PORT`; - a listen-address variable: `start: LISTEN_ADDR=0.0.0.0:$PORT exec ./app`; - Next.js standalone `server.js` binds to `$HOSTNAME`: set `HOSTNAME: 0.0.0.0` in `env:`; - Next.js `next start` listens on every interface: write `exec next start ${KARTS_LOCAL:+-H localhost}` (Karts sets `KARTS_LOCAL=1` only locally, where it then binds loopback); never `-H 127.0.0.1` (its requests to itself at `localhost`, `::1` on macOS, fail: pages answer 500); - Node's `app.listen(PORT)` with no host already listens on every interface; - PHP (`php artisan serve` is `php -S`): `PHP_CLI_SERVER_WORKERS=4 exec php -S 0.0.0.0:$PORT -t public` only with `relay-halfclose`; without it a response with no `Content-Length` never ends through Karts, so put Node in front: `start: PHP_CLI_SERVER_WORKERS=4 php -S 0.0.0.0:$((PORT+1)) -t public & exec node -e 'const h=require("http"),p=+process.env.PORT;h.createServer((q,s)=>{const r=h.request({host:"127.0.0.1",port:p+1,path:q.url,method:q.method,headers:q.headers},u=>{delete u.headers.connection;s.writeHead(u.statusCode,u.headers);u.pipe(s)});r.on("error",()=>{s.writeHead(502);s.end()});q.pipe(r)}).listen(p)'`. - **health:** the path from step 2. Use `/` only if `/` answers below 500 without login. - **Database settings the app does not read from `DATABASE_URL`:** map them in `env:`, which reaches `migrate`, `seed`, `build` and `start`: ```yaml env: DB_HOST: ${PGHOST} DB_PORT: ${PGPORT} DB_USER: ${PGUSER} DB_PASSWORD: ${PGPASSWORD} DB_NAME: ${PGDATABASE} ``` A differently named URL variable: `APP_DB_URL: ${DATABASE_URL}`. Select Postgres where the app has a selector (`DB_CLIENT: pg`). The VM's Postgres has no TLS: leave the app's SSL mode at `disable` or `prefer`. - **Migrations:** pick the first that fits. If the app's own code applies its SQL files (embedded, or at start), it is the self-migrating case below. - The migrations cannot build an empty database (base tables from the ORM's sync or `db push`, in no migration): `schema:`, **no** `migrate:`. TypeORM: `from: typeorm`, `datasource:` (the file `typeorm -d` takes). Prisma: `from: prisma`. Others: `from: custom`, `unverified: true`, `sync:`, `baseline:`, `drift:`, `ledger:`; say what custom does not check. Never put a sync or `--fake` in `migrate:`: a branch's migration would be recorded, never run. The data source must read `DATABASE_URL` or `PG*`; `synchronize` off in Karts (ask first; report it). - Plain numbered `.sql` files in one directory: `migrations: `; Karts applies them. - Prisma (`prisma/migrations/NN_name/migration.sql`) or golang-migrate (`N_name.up.sql`): `migrations_layout: prisma` (or `golang-migrate` with `migrations: `) and **no** `migrate:`; Karts applies the SQL. Add `migrate:` only if the tool must do more. - `prisma db push` (or any schema push) in a script skips migrations and Karts' checks: ask the user before keeping it. - Any other tool (Knex, Sequelize, TypeORM, Rails, Django, Alembic, Drizzle, …): `migrate: ` plus `migrations_layout:` (and `migrations:` where the layout has no default directory), from the table in step 5. The tool must be installed by `install`. If the project creates extensions in a superuser setup script, create the trusted ones first: `migrate: psql -qc 'CREATE EXTENSION IF NOT EXISTS citext' && `. - The app migrates itself when it starts (Shiori, Miniflux): nothing is required. Better: a migrate-only command as `migrate:` (for example `migrate: ./app migrate`), so the schema is in the template and Karts checks every change (with SQL files: `migrations_layout: files` and a glob, so Karts lists them). No such command: no `migrate:`, and say so in the report. - Never point `migrations:` at another tool's files without `migrations_layout:`: the karts layout refuses every file that is not `_.sql`. - `migrate:` must apply what is pending on every build, a branch's new files too: the tool's plain apply command. An `upgrade` or `init` command can skip them once the app is at its version; check it (step 7). - **seed:** the project's seed or bootstrap command, idempotent if you can. It runs on the base commit's tree, so it must exist on the default branch. - **The first login.** The URL is public, so: - a default user with a published password (created by a migration or on first boot): say so in the report, and tell the user to change the password right after the first `karts up`; - an app where the first visitor creates the admin, or anyone can sign up: say so in the report; - otherwise never write a password in `karts.yml`: generate it in `seed` and print it. `karts logs` shows it when `seed` ran in the revision (step 3's table); `karts logs --template` when it ran in the template build (feature `logs-template`). Without the feature, after each `karts up` set a new one with `karts exec -- sh -c '…'` (in `/srv/app`, with the database and the top-level `env:`, no network; keys inline) and print it, or tell the user how. Django: `createsuperuser --noinput` with `DJANGO_SUPERUSER_USERNAME`, `…_EMAIL` and `…_PASSWORD` inline. An app that creates its admin only when it starts (Miniflux `CREATE_ADMIN`): run it in `seed` on another port under `timeout 20`, then end the seed with a check that fails unless the admin exists (`psql -tAc "select 1 from users where username='admin'" | grep -q 1`). - **env:** plain, non-secret settings only: `NODE_ENV`, `DEBUG: "False"`, database selectors, feature flags that switch off what Karts cannot provide. Quote values YAML would read as booleans or numbers (`"true"`, `"False"`, `"1"`). - **Other services:** - A frontend or second web process in the same repository: `services:` (step 5), up to 8 in one VM. Each must answer HTTP on its own port and health path. A build that needs the app's URL (`ROOT_URL`) goes in a service `build:`, which gets `${services..url}`. - A JavaScript frontend in a Go, Python, Ruby or PHP app: build it in the same `install` (or a service `build:`). A bun project: the npm package `@oven/bun-linux-x64` (step 3, npm package as a tool; `BUN_CONFIG_REGISTRY=$npm_config_registry`, `bun run --bun`). - A frontend in another repository: `links:` in the frontend's `karts.yml` to the backend's Karts project. A frontend hosted elsewhere (Vercel, Netlify): `allow_origins:` in the backend's `karts.yml`, and the backend's CORS reads `KARTS_ALLOWED_ORIGINS`. - Redis (it reads `REDIS_URL`, or uses BullMQ, Sidekiq or Celery; optional Redis only if a needed feature requires it): `redis: true`, and `${REDIS_URL}` in `env:` for other names (`CELERY_BROKER_URL: ${REDIS_URL}/1`); never set `REDIS_URL` in `env:`. Empty at every `karts up` and restart. A background worker with no HTTP port: a service with `kind: worker`. - Mail (sign-in links, invites, resets): `mail: true`, even when mail looks optional: an app that emails a sign-up or sign-in link fails that POST without it. Map only names that differ from Karts' (`MAIL_HOST: ${SMTP_HOST}`, `EMAIL_PORT: ${SMTP_PORT}`, an app that reads `SMTP_HOST` and `SMTP_PORT` needs no entry), plus its TLS switch off (`SMTP_SECURE: "false"`) and a from-address; no login: leave SMTP user and password unset. Read what it sent at the `mail` URL `karts up` prints (`https://karts:@…--mail…`; locally `http://--mail..localhost:7400`; API `/api/v1/message/latest`). Empty at every build. - Outside APIs (email, sign-in, Stripe, others), if `fakes` is listed: `fakes:` with the names `karts version --capabilities` lists, else `stubs:`; with `egress`, real sandboxes via `internet:` (no live keys; `allow_production:` is an owner's call); other hosts get a 502 saying what to add. `karts fakes calls`, `karts egress log` show what it sent. - Several database roles (graphile's owner, authenticator, visitor): `database:` with indented `roles: [authenticator, visitor]` (LOGIN, the app role's password: `postgres://visitor:${PGPASSWORD}@${PGHOST}:${PGPORT}/${PGDATABASE}`; the app role can `GRANT` them); never map them all to `PGUSER`. `superuser: true` only if the app needs it (untrusted extensions such as `postgres_fdw`, not those `extensions:` takes; its own `CREATE ROLE`). - Object storage (S3, MinIO): `storage: s3` if listed (needs `services:`); map the app's own names in `env:` (`AWS_S3_ENDPOINT_URL: ${S3_PUBLIC_URL}`); path-style, SigV4. Never add MinIO. The bucket is empty at every `karts up`. - Other queues (RabbitMQ, Kafka), search, MongoDB: not provided. If the app runs without it (optional, or an inline/eager mode), turn it off in `env:` and report the missing feature. Else report the app as unsupported. **Fallbacks** when the environment cannot do something (rule 3: ask before adding files): | Problem | Fallback | What removes it | |---|---|---| | the host has no registry access (step 3, network) | build the dependencies on this machine for linux/x64 (`npm ci --omit=dev --os=linux --cpu=x64 --ignore-scripts`; `pip install --target .karts/site --platform manylinux2014_x86_64 --python-version 3.12 --only-binary=:all: -r requirements.txt`), pack them as `.karts/deps.tgz`, and `install: tar -xzf .karts/deps.tgz`. Native packages need a linux/amd64 container | registry access on the host | | no image for the language (Rust) | keep `runtime: node22`; ship a static linux/amd64 binary as `.karts/app`, `start: exec .karts/app …` | an image for that runtime | | a heavy build runs out of 2 GB or 10 minutes | a service `build:` (its own 10 minutes); `resources:` if listed; else build on this machine and ship the output | more VM memory | ## 5. Write karts.yml The file is a strict subset of YAML: `key: value` lines, `#` comments, spaces only (no tabs), two spaces before `env:` entries and `services:` names, four before service keys, six before a service's `env:` entries. Unknown keys and keys set twice are refused with the line number. | Key | Meaning | |---|---| | `project` | written by `karts init`; never invent it | | `runtime` | the image, default `node22` | | `database` | `postgres` (default), `mysql`, `sqlite`, `none`, or indented `superuser: true`, `roles: [a, b]`, `extensions: [citext]` (trusted contrib, plus `vector` and `pg_stat_statements` with the `pgvector` feature) | | `migrations` | the directory the migration layout reads (default: the layout's own) | | `migrations_layout` | how the migration files are named: `karts` (default), `prisma`, `golang-migrate`, `knex`, `sequelize`, `typeorm`, `rails`, `laravel`, `django`, `alembic`, `files` | | `migrations_glob` | which files are migrations, relative to the repository root: one glob or `[a, b]`; replaces the layout's patterns; not with `migrations:` or the karts layout | | `migrate` | the project's own command that applies pending migrations; runs on every build (step 3) | | `schema` | migrations cannot build an empty database: the template syncs the base's ORM entities (step 4) | | `seed` | runs when the template is built (step 3) | | `seed_fail_on` | `error`: fail a `seed`/`migrate` printing `ERROR`, `FATAL` or `Unhandled` (else warn) | | `seed_snapshot` | a masked copy of real data made by `karts db snapshot`, restored instead of `seed`; only a path that command printed | | `masking` | rules for `karts db snapshot` (columns to keep or mask); nothing else reads them | | `base` | branch previews start from, if not the default (`develop`); `--base` wins | | `install` | installs dependencies; gets no `env:` | | `start` | starts the app on `$PORT` (single-service form) | | `health` | readiness path, default `/` (single-service form) | | `kind` | `static` (if `static-sites` is listed): Karts serves a built SPA or static site; no `start`/`health`. Never hand-write a server in `start` | | `build` | with `kind: static`: builds the site first; gets `env:` and links | | `dir` | with `kind: static`: the built directory to serve (`dist/app/browser`) | | `spa` | with `kind: static`: `true` answers unknown page paths with `index.html` | | `env` | plain settings, as indented `NAME: value` lines; not `DATABASE_URL`, `PORT`, `KARTS_*` or libpq's `PG*` names; if `check-config` refuses an app's own `PG_DATABASE_URL`, set it inline (`PG_DATABASE_URL=$DATABASE_URL exec …`); values may use `${NAME}` and `$$` | | `services` | instead of `start`/`health`: 1 to 8 named services, each with `start` (required), `dir`, `build`, `port`, `health`, `env`, `secrets`, and `kind`: `web` (default), `worker` (no port, health or URL; never first) or `static` (`dir` is what it serves, `build` runs at the root, `spa`) | | `links` | another Karts project whose URL this app gets in a variable | | `redis` | `true`: Valkey 9 (Redis 7.2 compatible) on 127.0.0.1:6379 in the VM. Or indented `maxmemory:` (16mb to 512mb, default 128mb, out of the 2 GB) and `policy:` (default `noeviction`; `allkeys-lru` for a pure cache) | | `mail` | `true`: Mailpit catches the app's mail (`SMTP_*`); inbox at the `mail` URL `karts up` prints | | `fakes` | `[sendgrid, stripe]`, or ` stripe: {webhook_path: /hooks}` lines: fake outside services (step 5) | | `stubs` | ` - host: api.example.com` with `path`, `method`, `status`, `body`, `headers` (step 5) | | `internet` | `egress` only: `presets: [openai]`, `hosts: [api.example.com]` or `full: true` (step 5) | | `mocks` | step 5 | | `recordings` | step 5 | | `storage` | only if listed: `s3`, an S3 bucket in the VM, served at `https://--s3.`; needs `services:`; no service named `s3` or on port 7070 | | `allow_origins` | browser origins allowed to call this app (`https://…`), passed as `KARTS_ALLOWED_ORIGINS`; exact-match CORS (Nest, Express `cors`) cannot match a `*` | | `secrets` | `[NAME]` (rule 1): to `start`, not `install`/`build` | | `secrets_in` | `[migrate, seed]` get them too | | `resources` | only if listed: indented `memory:` (to `8gb`; over `4gb` counts as 8 GB), `cpus:` (to 4), `build_timeout:` (to `45m`), `disk:` (to `16gb`); a host may allow less. Only after a build was killed for memory, time or disk; say so in the report | Single service: ```yaml runtime: node22 database: postgres install: npm ci migrate: npx knex migrate:latest migrations: server/migrations migrations_layout: knex start: JWT_SECRET=$(od -An -N32 -tx1 /dev/urandom | tr -d ' \n') exec npm start health: /api/health env: NODE_ENV: production DB_CLIENT: pg DB_HOST: ${PGHOST} ``` Services in one VM (the first is served at the environment's URL, each other one at `--`; a one-service block is how an app learns its own URL): ```yaml runtime: node22 database: postgres install: npm ci seed: npm run migrate --workspace api env: NODE_ENV: production services: web: dir: web build: npm run build start: exec npm start health: / env: NEXT_PUBLIC_API_URL: ${services.api.url} API_INTERNAL_URL: ${services.api.internal_url} api: dir: api start: exec node server.js health: /health jobs: kind: worker dir: api start: exec node worker.js ``` Links and origins: ```yaml links: api: project: shop-api # the other Karts project's id, or its name env: API_URL # the variable this app gets allow_origins: - https://shop-*-myteam.vercel.app ``` ### Migration layouts | `migrations_layout` | Default `migrations:` | Migration files | Who applies them | Typical `migrate:` | |---|---|---|---|---| | `karts` (default) | none | `_.sql` directly in the directory; any other file is refused | Karts, or `migrate:` if set | — | | `prisma` | `prisma/migrations` | `*/migration.sql` (folder names start with a number) | Karts, or `migrate:` if set | `npx prisma migrate deploy` | | `golang-migrate` | required | `_.up.sql` (`.down.sql` ignored) | Karts, or `migrate:` if set | `migrate -path db/migrations -database "$DATABASE_URL" up` | | `knex` | `migrations` | `*.js`, `*.cjs`, `*.mjs`, `*.ts` | `migrate:` (required) | `npx knex migrate:latest` | | `sequelize` | `migrations` | `*.js`, `*.cjs`, `*.ts` | `migrate:` (required) | `npx sequelize-cli db:migrate` | | `typeorm` | required | `*.ts`, `*.js` | `migrate:` (required), or `schema:` | `npx typeorm migration:run -d dist/data-source.js` | | `rails` | `db/migrate` | `_.rb` | `migrate:` (required) | `bin/rails db:migrate` | | `laravel` | `database/migrations` | `*.php` | `migrate:` (required) | `php artisan migrate --force` | | `django` | repository root | `**/migrations/[0-9]*.py` | `migrate:` (required) | `python manage.py migrate --noinput` | | `alembic` | `alembic/versions` | `*.py` | `migrate:` (required) | `alembic upgrade head` | | `files` | none; set `migrations_glob` | what the glob matches | `migrate:` (required) | the tool's command (use this for Drizzle and goose) | - Other files in the directory are ignored, except with `karts`. A file the tool would not run (golang-migrate, Rails) is refused, and so is an unnumbered Prisma folder. - `migrations_glob` (`[db/migrations/*.sql]`, from the repository root) can narrow a layout that reads the whole repository: with vendored Python packages in the tree, `django` also watches Django's own, so write `migrations_glob: myapp/*/migrations/[0-9]*.py`. - `migrate:` runs from the repository root: in a monorepo write `migrate: cd apps/api && npx prisma migrate deploy`. ### Variables in env ```yaml env: DB_HOST: ${PGHOST} DB_URL: postgres://${PGUSER}:${PGPASSWORD}@${PGHOST}:${PGPORT}/${PGDATABASE} PRICE: $$5 ``` - `${NAME}` takes a variable Karts sets (`DATABASE_URL`, `PG*`, `PORT`, `KARTS_*`, `REDIS_*`), a `links:` variable, or another key of the same `env:` (a service's `env:` sees its own keys, then the top level's). Only a service's own `env:` can use `${services..url}` (public HTTPS) and `.internal_url` (`http://127.0.0.1:`). - `$$` is a literal `$`. Any other `$` stays as written, so `$HOME` in a value is not expanded. - An unknown name is refused with its line; so is a chain (a key naming a key that names one). - In `seed` and `migrate`, `${PORT}` is the first service's port; `${KARTS_URL…}` and links' variables are empty in the template build: a top-level placeholder (step 3). ## 6. Check it ```sh karts check-config ``` It runs the host's checks on the files `karts up` would upload, plus secret, network and default-branch warnings. Fix every error, read every warning, repeat until it prints `ok`. `ok` does not promise that `karts up` succeeds (numbering against the default branch, destructive SQL, runtime images, `links:` projects, your commands), nor that nothing secret is uploaded. ## 7. Run it, read failures, fix, repeat ```sh karts whoami # signed in? if not, see rule 5 karts init # only if karts.yml has no project: line; keeps your lines karts up --output json ``` If the user does not sign in, run it locally (step 7L); if that is not possible either, stop here and write the report with "Karts: not run (not signed in)"; steps up to 6 still count. Run `karts check-config` again after `karts init` and after every change, immediately before each `karts up`: it checks the bytes about to be uploaded. A green `up` can hide a failing sign-up or a skipped migration: check as a user would; report each check: 1. The health path and one real page answer below 500 (`curl -sS -o /dev/null -w '%{http_code}\n' `). 2. One real action through the app's form or API (`curl` with a cookie jar; a form's CSRF token from its page): sign up or sign in by email and follow the link from the `mail` inbox (locally too), sign in with the seed's or published login, or create a record and read it back. Use `agent@example.com` and a generated password, and give the login in the report (where the first visitor becomes the admin, that is you). None possible without a real credential: say what you tried. 3. The page's own URLs are https: `curl -sS | grep -Eio "(src|href|action)=[\"']?http://[^\"' >]*"` and every redirect hop (`curl -sSL -D - -o /dev/null | grep -i '^location: *http://'`) print nothing (failure table). 4. On a branch with a new migration: `karts exec -- psql -tAc ''` finds its row in the ledger of whoever applied it (`karts_migrations`, columns `name`, `sha256`, `applied_at`, where Karts applies the SQL: no `migrate:`; else the tool's: TypeORM's `migrations`, `_prisma_migrations`, `knex_migrations`, `django_migrations`, `schema_migrations`, `SequelizeMeta`, `alembic_version`) and what it made (a column, table, index or row). `database: none`: the same in its SQLite file, with the app's own driver. No such branch: say `migrate:` was not tried on one. On failure: ```sh karts logs --failed # the failed revision's output (a failed template's: karts up's [template] lines) karts exec --failed -- sh -c '…' 2 GB | fewer parallel jobs (`--workspace-concurrency=1`, `-j1`), once a smaller heap (`NODE_OPTIONS=--max-old-space-size=1024` inline; Vite 8's bundler and Yarn 4 ignore it); then `resources: memory:` (`4gb`, then `8gb`) if listed; else report "VM memory". A script's own heap flag (`--max_old_space_size=8192`) beats `NODE_OPTIONS`; set it ~1.5 GB under the VM's (`6656` at 8 GB) | | `ENOSPC: no space left on device` | the tree, `node_modules` and caches fill the app disk (older hosts: a cache fills the root disk; Yarn 4 fills `/tmp`: `TMPDIR="$HOME/tmp"` inline) | delete what the app does not need at run time as soon as it is made (`yarn cache clean`, a built frontend's `node_modules`); `resources: disk:` if listed; else report it | | `… cannot open shared object file`, `failed to find ` | a system library the image lacks (libvips, ImageMagick; libmagic on older images) | report it; nothing can be installed | | Composer `curl error 6 … Could not resolve host` | no `registry-packagist`, or a package from outside Packagist and GitHub | a committed `vendor/`; else report it | | `Your Ruby version is 3.3.12, but your Gemfile specified 3.4.4` | no image with that Ruby | a runtime `karts up` lists with it, or step 3's edit; else report it | | `extension "vector" is not available` (or `postgis`) | no `pgvector` feature; no PostGIS | report it | | `ERR_PNPM_UNSUPPORTED_ENGINE` (`Expected version: 24`, `Got: v25…`), or another engines error, locally | this machine's Node or pnpm is not the one the repository pins | step 7L: the pinned version first on PATH; the next `up` uses it | | `health passed (GET /api/… answered 200) but GET / answered 500` (or `did not answer within 20s`) | the page a visitor opens fails while the health path works: the app's last lines say why (a missing setting, a database error; Next.js with `-H 127.0.0.1`) | fix that; Next.js: step 4 | | requests to a PHP app hang until they time out | `php -S` on a host without `relay-halfclose` | the Node proxy (step 4) | | `type "citext" does not exist` (or another extension) | the project creates extensions as a superuser | create it before the migrations (step 4) | | a build in `install` stops on a missing URL setting (`ROOT_URL is a required envvar`) | `install` has no URL | move the build to a service `build:` (step 4) | | `runtime "…" is not supported; supported runtimes: …` | no such image | a listed one, a fallback, or report it | | `Failed to fetch https://nodejs.org/download/release/…` in `pnpm install` | pnpm 12 `devEngines.runtime` downloads Node | in `install`, delete `devEngines` from `package.json` and the root `node: runtime:` entry from `pnpm-lock.yaml` first (the image has Node) | | `submodule … is not initialised` (or `is not in any local repository`) | a submodule was never checked out | `git submodule update --init --recursive`, then retry | | `a revision on an older base is still serving; karts down it or update it` | the default branch moved; a project keeps two templates | `karts list --output json`; `karts down` old ones you created; ask about the rest | | `karts.yml line N: unknown key` from `karts up` but not from `check-config` | the Karts host is older than your CLI | remove that key; use its fallback | | `did not answer GET … with a status below 500 … within 1m0s`, and the app log shows it listening | bound to 127.0.0.1/localhost, or the health path needs login or does not exist | bind `0.0.0.0:$PORT`; pick another health path | | `service … kept exiting (5 restarts)`, or the app exits at boot naming a variable | a crash at boot, often a required setting | `karts logs --failed`; plain setting: `env:`; signing key: generate at start; real credential: unsupported | | POSTs answer 502 "The app is not answering" while GETs work | the app closes each connection without saying so (uwsgi `--http-socket`) | uwsgi `--add-header "Connection: close"`; else report it | | a build step in `install` fails on a setting (`DEBUG`, `SECRET_KEY`, `DATABASE_URL`) | `install` gets no `env:` | set it inline in `install` (a build-only value, never a real secret) | | `ECONNREFUSED 127.0.0.1:5432`/`3306`, `ENOENT …sqlite`, or a database auth error | the app ignores `DATABASE_URL` or selects another engine | map the engine's variables (step 4) | | `permission denied to create role/database/extension` | the role is not a superuser | `database:` `roles:` for the app's roles, `extensions:` for the ones it takes, else `superuser: true`; never map roles to the app's | | browser POSTs refused (CSRF, origin), an https redirect loop, or `http://` asset and link URLs on the `https://` page | the app thinks it is served over http: it ignores Karts' `X-Forwarded-Proto: https` from an untrusted proxy | its public-URL or trusted-origins setting as `${services..url}`, and its trusted-proxies or force-https setting (Monica: `APP_TRUSTED_PROXIES: "*"` or `APP_FORCE_URL: "true"`); else report it | | `guest agent predates redis:` (or `mail:`, `database: options`, `kind: worker`, `services:`) | the host's images are older than the feature | report it; for `services:`, use top-level `start:`/`health:` | | a migration file refused (`is not a migration`, `is in a subdirectory`) | another tool's files under the karts layout | set `migrations_layout:` (and `migrate:` for code layouts), step 5 | | `knex migrations are applied by their own tool; add migrate:` (or another layout) | a code layout without a command | add `migrate:` with the layout's command | | `${X} is not a variable Karts sets, a links: variable or an env: key` (or `is not a variable name`) | a typo, or a literal `${` | fix the name, or write `$${` | | a branch's new migration is not in its database (step 7) | the tool runs in `seed:`; `migrations:` points at the wrong place; the base has no `karts.yml`; or `migrate:` is not the tool's apply command | move it to `migrate:` with the right `migrations_layout:`; `karts up --reseed` for this branch meanwhile | | `destructive migration refused` naming a dropped column or table | the branch's migration drops or narrows data | ask the user; only with their agreement, `karts up --allow-destructive` | | `already ran on the base; this branch changes it` (or `deletes it`) | the branch edits or deletes a migration the default branch ran | add a new migration instead, or `karts up --from-scratch` if the user agrees | | `is numbered at or below the base's newest migration` (warning) | a timestamped migration created before one on the default branch | usually fine; mention it in the report | | `the migrations may not build an empty database` | base tables in no migration | `schema:` (step 4) | | `--reseed` fails on duplicate rows | the seed is not idempotent | `karts up --from-scratch` | | upload refused for size or count | the limits in step 3 | git-ignore build output and large files the app does not need | **Attempts.** Change one thing per attempt and note it. Count two kinds of failed attempt: your own configuration mistakes (a wrong command, path, variable or health path), at most 5; and platform limits fixed with a workaround this prompt gives, at most 5 more (host failures, above, are neither). Stop at once and write the report when the blocker is a missing Karts feature with no workaround here (a host outside the registries, a system library, a runtime without an image, memory after the settings above), or when the fix needs a real secret, a paid service or a change to application code. When you stop, `karts down` every environment you created except the one in the report. ## 7L. Local: no sign-in, nothing uploaded Use this when the user asks for local mode, is not signed in or must not upload code. The same `karts.yml` runs each branch here as a process of this user (no VM), with its own port, URL and database copy. Docker must be running (Karts' own containers are named `karts-local-…`; it never touches the user's). ```sh karts check-config --local # plus what local mode refuses: redis:, storage: karts up --local # http://..localhost:7400 (no DNS setup needed) karts list --local; karts status --local; karts logs --local; karts down --local ``` - `flag provided but not defined: -local`: an older CLI; ask the user to upgrade (step 1). - A refused key: ask before removing it (hosted still uses it). - The machine's own node, npm and pnpm run, from each `karts up`'s PATH (`runtime:` only warns). They must be the versions the repository pins (`engines`, `.nvmrc`, `.node-version`, `packageManager`); pnpm refuses others. Switch with the user's version manager (`nvm use`, `fnm use`, `volta`) or the official nodejs.org tarball unpacked in a directory put first on PATH (not Homebrew's `node@N`); check `node -v`, `up` again; ask before installing. - Karts sets `PORT`, `HOST=127.0.0.1`, `HOSTNAME`, `DATABASE_URL`, `PG*`, `KARTS_URL` (http), `KARTS_LOCAL=1`, `KARTS_ENV_DIR`; with `mail:` `SMTP_HOST`, `SMTP_PORT`, `SMTP_URL` (inbox: the `mail →` URL; no password: all local listens on 127.0.0.1 only). An app on every interface is reachable from the network (`up` warns): bind `$HOST` (Node: `app.listen(port, process.env.HOST)`; Next.js: step 4; ask first: rule 3). - `install:` runs when lockfiles, manifests, toolchain or `.env` change, not for other edits (`--reinstall` forces it); `build:` on every `up`. A repeat `up` keeps the database (new migrations, no seed; `--fresh-db` rebuilds). `karts exec --local -- CMD` and `karts psql --local` work. Not local: `--reseed`, `--from-scratch`, the registry proxies. - Two branches at once: one git worktree per branch (`git worktree add`, then `karts up --local` in each). `karts up --local --new` is a second copy of the same branch. - `links:` works: the other project's URL for this branch, else its default branch (`--link api=` picks); `karts up --local` there first. CORS: its `allow_origins:` takes `http://*..localhost:7400`, and `KARTS_ALLOWED_ORIGINS` adds the exact origins it matched at that `up` (`up` again for new ones). - Step 7's checks: `curl` the printed URL; one real action (email: the local inbox); skip https (check 3). Check 4: `karts psql --local`. - Failures: `up` prints the failing step and its last lines; `karts logs --local` has the app's output. Host-only failure rows do not apply. `the local daemon's socket path … is N bytes, and this OS allows at most 103`: a shorter `KARTS_LOCAL_DIR`. `KARTS_LOCAL_PG_CONTAINER=…: Karts names its containers karts-local-…`: that prefix. - Report as step 8 with `Karts: (local)`; `karts down --local` the others you made. ## 8. Report Finish with exactly this shape: ``` Karts: What Karts runs every time install: (every build; no env:, no database) migrations: migrate: (every build, after install, before seed) seed: (when the template is built from the default branch; again with --reseed or --from-scratch) build: start: on $PORT health redis: (empty at every build) mail: database: Branch migrations: Default branch: <"karts.yml is on ", or "merge karts.yml into so previews start from a template"> Attempts: configuration, platform workarounds () Changed outside karts.yml: Keys generated: Constant development values (user agreed): Tracked .env* and key files uploaded: Checks after up: Unsupported or missing: Questions for you: ``` `karts check-config` prints this tree's steps; start from that and add what it cannot know. If you ran `karts init` and the app is unsupported, add under questions that `karts project delete --down-all` removes the project; the user runs it, not you.