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.
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
localhostor 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.
pgvectorused 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
| id | What it catches | Fix |
|---|---|---|
native-packages | Packages that compile native code (node-gyp, Python wheels) | Build tools (python3, make, g++) in the install step |
platform-amd64 | FROM --platform=linux/amd64 or x86-only images on ARM servers | Ignore the platform pin |
no-lockfile, lockfile-out-of-date | Installs that won't be repeatable, or npm ci failing | Explains the command to run locally |
node-version | engines.node or .nvmrc the builder wouldn't pick | Pin the Node version |
dockerignore | No .dockerignore, so node_modules and .git go into the build | CLI's default ignore list |
monorepo | The app lives in a subfolder | Set the root directory |
build-variables, build-variables-missing | NEXT_PUBLIC_*, VITE_* and similar that must exist at build time | Pass those variables to the build |
port, localhost, expose-port | Listening on another port, on localhost, or a Dockerfile EXPOSE that disagrees | Set the port |
background-worker | A bot or worker with no HTTP server | Run in the background |
memory-jvm | Gradle, Maven or big Node builds on a small plan | More build memory |
pgvector | vector(…) or a pgvector client without the extension | Turn on vector search for the project's Postgres |
headless-chrome | Puppeteer or Playwright without Chromium's libraries | The packages to install |
smtp, smtp-port | Sending mail over SMTP ports 25, 465 or 587, which are blocked | An email API, or Email for your apps |
supabase-ipv6 | A Supabase direct (db.*.supabase.co) URL, IPv6 only | Use the pooler URL |
Build settings
| Setting | Meaning |
|---|---|
builder | auto (the Dockerfile if there is one, else Railpack), dockerfile or railpack |
dockerfile | Path to the Dockerfile, if it isn't ./Dockerfile |
installCommand, buildCommand | Override what Railpack runs |
nodeVersion | For example 22 or 20.11 |
memoryMb | Memory for the build (1024 to 16384) |
buildVariables | Variable names the build also gets: build args for Dockerfiles, build variables for Railpack |
buildTools | Add python3, make and g++ to the install step |
ignorePlatform | Ignore --platform in FROM lines |
defaultIgnore | Use CLI's .dockerignore when the repo has none |
noCacheOnce | Build once without the cache, then go back to normal |
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 cacheAgents 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.
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
healthcheckPathset, 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.