Docs menu

Deploy and run

Build checks and build settings

How CLI spots what would break a build before it runs, the one-click fixes, build settings, background workers, health checks, and copying or downloading logs.

Explain it

Before CLI builds your app, it reads the code and looks for the things that usually make a build or a start fail: a package that needs compiling, the wrong port, too little memory, a database extension that isn't on. Anything it finds shows up with a plain explanation and a Fix button. Fixes are saved for that app, so they apply to every build after.

Where to find it: open the app, then Settings → Build check and build settings. Press Check now any time. Warnings from the last check also show on each deploy.

Things it catches:

  • Packages that need compiling (for example bcrypt, sharp, better-sqlite3). The fix adds the build tools.
  • An app pinned to Intel (x86) machines. CLI's servers are ARM, so the fix ignores the pin or suggests an ARM image.
  • An app listening on localhost or on a different port from the one set. These apps never answer.
  • A bot or queue worker with no web server. Switch it to a background worker (Settings → Web app or background worker) so it doesn't need a web address.
  • Large Java or Node builds that run out of memory. The fix gives the build more.
  • pgvector used in the code but not turned on in the database. The fix turns it on.
  • Headless Chrome (Puppeteer, Playwright) without the system libraries it needs.
  • Email on ports that are blocked. Use your email provider's API, or CLI's email for apps.
  • A Supabase direct connection string. It only works over IPv6; use Supabase's pooler address instead.
  • No lockfile, an out-of-date lockfile, a missing .dockerignore, and the wrong Node version.

Logs: a deploy's build and app logs, and an app's live logs, have Copy and Download .txt, so you can paste a log to your agent or save it.

Deploys take turns. If you press Deploy twice, or an agent and a push deploy at the same time, the deploys of one app run one after another. A deploy that's still waiting is skipped when a newer one is queued behind it. Different apps still build side by side.

When the checks run

The build check reads the repository at the commit being deployed (the files that matter: manifests, lockfiles, the Dockerfile, .dockerignore, entry points) plus the service's variables, port, plan and settings. It runs:

  • before every build (its findings are attached to the deploy and shown with it),
  • when you press Check now or call the API,
  • when an agent calls cli_check_build.

Each finding has an id, a severity (error would fail the build, warn might, info is a tip), a plain title and detail, and usually a fix. Press Fix on one, or apply several at once; dismissed findings stay dismissed for that service.

The checks

idWhat it catchesFix
native-packagesPackages that compile native code (node-gyp, Python wheels)Build tools (python3, make, g++) in the install step
platform-amd64FROM --platform=linux/amd64 or x86-only images on ARM serversIgnore the platform pin
no-lockfile, lockfile-out-of-dateInstalls that won't be repeatable, or npm ci failingExplains the command to run locally
node-versionengines.node or .nvmrc the builder wouldn't pickPin the Node version
dockerignoreNo .dockerignore, so node_modules and .git go into the buildCLI's default ignore list
monorepoThe app lives in a subfolderSet the root directory
build-variables, build-variables-missingNEXT_PUBLIC_*, VITE_* and similar that must exist at build timePass those variables to the build
port, localhost, expose-portListening on another port, on localhost, or a Dockerfile EXPOSE that disagreesSet the port
background-workerA bot or worker with no HTTP serverRun in the background
memory-jvmGradle, Maven or big Node builds on a small planMore build memory
pgvectorvector(…) or a pgvector client without the extensionTurn on vector search for the project's Postgres
headless-chromePuppeteer or Playwright without Chromium's librariesThe packages to install
smtp, smtp-portSending mail over SMTP ports 25, 465 or 587, which are blockedAn email API, or Email for your apps
supabase-ipv6A Supabase direct (db.*.supabase.co) URL, IPv6 onlyUse the pooler URL

Build settings

SettingMeaning
builderauto (the Dockerfile if there is one, else Railpack), dockerfile or railpack
dockerfilePath to the Dockerfile, if it isn't ./Dockerfile
installCommand, buildCommandOverride what Railpack runs
nodeVersionFor example 22 or 20.11
memoryMbMemory for the build (1024 to 16384)
buildVariablesVariable names the build also gets: build args for Dockerfiles, build variables for Railpack
buildToolsAdd python3, make and g++ to the install step
ignorePlatformIgnore --platform in FROM lines
defaultIgnoreUse CLI's .dockerignore when the repo has none
noCacheOnceBuild once without the cache, then go back to normal
API
GET    /v1/services/:id/build                 # settings and the last check
PUT    /v1/services/:id/build                 # change settings
POST   /v1/services/:id/build/check           # run the check now
POST   /v1/services/:id/build/fixes {"ids": ["native-packages"], "values": {}}
POST   /v1/services/:id/build/dismiss {"id": "dockerignore"}
POST   /v1/services/:id/build/no-cache        # next build without the cache
DELETE /v1/services/:id/build/cache           # clear this app's build cache

Agents use cli_check_build, cli_apply_build_fixes and cli_build_settings. The build log shows how long each step took.

Background workers

A background service has no web address and no HTTP health check: bots, queue consumers, schedulers.

API
PUT /v1/services/:id/background {"enabled": true}

It counts as healthy once it has stayed up for 10 seconds; if it exits, the deploy fails with its logs. Its signal reads Running in the background. Switching takes effect on the next deploy.

Health checks

An app is healthy when it answers its health check:

  • With a healthcheckPath set, that path must return a 2xx status.
  • Without one, any answer below 500 on / counts (a 404 or a redirect at the root is fine).

When an app doesn't become healthy, the deploy shows What CLI's health check saw: the exact URL probed (the container's address, port and path), the worker it ran from and on which network, how many times it tried, and the last answer, either an HTTP status or the network error (connection refused, timed out, reset). It says what that points at: refused means nothing listened on that port; an HTTP status means the app answered with an error or the health path is wrong; no address means CLI's side. The same trace is in the deploy's error.detail.probe and at the end of its logs.

An app that listens but can't be reached, or a container that disappears, is reported as PLATFORM_ERROR (not your code). A running app that stops answering shows Not answering until it recovers; a sleeping app isn't counted as down. Its page says why (for example, no container is running) and, when on call has proposed a fix such as a restart, offers it as one button. In the API, a service's health has state (up, down, starting, asleep, stopped), the reason, containerRunning, and recovery with the request that applies the fix (POST /v1/proposals/:id/apply).

Deploys take turns

Deploys of one service run one at a time (across control-plane replicas, using a lease). A queued deploy is cancelled, with a log line naming the newer one, when a newer deploy of the same service is waiting; rollbacks are never skipped. Waiting for a turn doesn't take a build slot, and different services build in parallel up to the server's limit.

Copy and download logs

A deploy's build and app logs, the failing step of a deploy, and an app's live logs (what matches the current filter) each have Copy and Download .txt. Secret values are already masked. From the API, GET /v1/deploys/:id/logs and GET /v1/services/:id/logs return the same text.