Docs menu

Deploy and run

Deploying

Deploy from git, GitHub, a Docker image or your own folder, and understand what a failed deploy is telling you.

Explain it

A deploy builds a new version of your app and switches visitors to it once it's working. If a deploy fails, the version that was already running keeps running, so trying again is always safe.

How to do it: paste a GitHub link into Put something online, or open an app and press Deploy now. Apps linked to GitHub deploy by themselves on every push. If one fails, open it to see the error in plain words and press Fix it for me, or roll back to an earlier version in one click.

"Deploy my app and fix whatever fails."

Coming from another host? CLI can move your apps across for you.

A deploy builds one version of a service and switches traffic to it once it's healthy. This page covers where your code can come from, what happens during a deploy, and what to do when one fails. A failed deploy never touches the version that's already running, so trying again is always safe.

Choose a source

Every app service has a source. You pick it when you create the service.

SourceWhat it is
GitHub repoA repo with the CLI GitHub App installed. Pushes to the tracked branch deploy, each commit gets a cli/<service> status, and PR previews are available
Public git URLAny public https:// repository, cloned at the commit. No usernames or passwords in the URL, and no ssh://, git:// or file://; for a private repo, connect it through GitHub. Redirects aren't followed, so a renamed repo needs its new URL
Docker imageAn image from any registry, public or private
UploadA folder from your machine, sent with cli up
EmptyNo source yet. Deploy later with cli up

In the dashboard: choose New service, then GitHub repo, Docker image, Public git URL or Empty service. App services deploy as soon as they're created.

From your terminal:

Terminal
cli up
cli add --image ghcr.io/acme/api:2 --port 3000 --start "node server.js"

Ask your agent:

"Deploy acme/shop from GitHub as a service called web, with push-to-deploy."

With the API:

API
POST /v1/projects/:id/services
JSON
{ "name": "web", "source": { "type": "github", "repo": "acme/shop" }, "port": 8080 }

GitHub and push to deploy

To deploy a private repo, link your GitHub account and install the CLI GitHub App on the repo. Then every push to the tracked branch deploys. If an agent hits GITHUB_NOT_LINKED or GITHUB_REPO_NOT_ACCESSIBLE, it will give you a link to approve in your browser: only you can do that step.

Docker images

Images are pulled on every deploy and pinned to their digest, so :latest picks up new versions while rollbacks get the exact image you ran. For a private registry, add credentials:

JSON
{ "type": "image", "image": "ghcr.io/acme/api:2", "registry": { "server": "ghcr.io", "username": "acme-bot", "password": "<token>" } }

With cli add --image, set CLI_REGISTRY_USER and CLI_REGISTRY_PASSWORD. GHCR tokens need read:packages.

Uploading a folder

cli up packs the current folder, respecting .gitignore and .cliignore, uploads it and watches the deploy. Uploads are scanned for secrets first. If it finds an .env file, a private key or a live API key, the deploy stops with SECRETS_IN_UPLOAD and lists the files and lines (never the values). Move the values into variables (see /docs/configuration) and remove the files.

CLI reads your repo first

When you pick a GitHub repo, CLI reads its manifests and fills in the setup before anything is created. It looks at package.json, requirements.txt, go.mod, the Dockerfile, prisma/schema.prisma and .env.example:

  • What it is: Next.js, Remix, Nuxt, SvelteKit, Astro, Vite, Create React App, NestJS, Express, Fastify, Hono, Django, FastAPI, Flask, Rails, Go, Rust, a Dockerfile, or plain HTML.
  • How to run it: a static site with its output folder (Vite → dist, a Next export → out), or an app with its start command and port. A monorepo's app folder becomes the root directory.
  • What it needs: Postgres, MySQL, Redis or MongoDB, from the libraries it uses. Adding the database sets its variable.
  • What to fill in: the variables in .env.example, with secret-looking ones marked.
  • What to watch for: a committed .env file, a missing start script, migrations to run before release.

Choose Use these settings to apply them. Agents and scripts call POST /v1/detect with {"github": "owner/name"}, or with {"files": {path: contents}} for code on their machine (cli_detect).

What your app needs

  • Listen on $PORT on host 0.0.0.0. CLI sets PORT to the service's port.
  • Answer the health check: GET / must return a 2xx status, or set a healthcheckPath such as /healthz that does.
  • Start command (optional): startCommand replaces the image's command, for example node dist/server.js. It runs with /bin/sh -c.

If there's a Dockerfile, CLI builds with it. Otherwise it detects your language from files like package.json, requirements.txt, pyproject.toml, go.mod or Cargo.toml.

What happens during a deploy

A deploy moves through these states:

  1. Queued. CLI checks your balance covers an hour of every copy, your spending limits, your project's rules (an agent may need approval) and your budget.
  2. Building. CLI clones the commit and builds the image, reusing the cache from the last good build.
  3. Deploying. If you set a release command (usually migrations), it runs once in the new image. The new version starts and CLI waits for it to answer the health check. Smoke tests, if you set them, run now.
  4. Healthy. Traffic switches to the new copies once all of them are healthy. Old containers are removed.

A deploy can also end as failed or cancelled. A healthy deploy becomes superseded when the next one goes live. Running deploys show an estimated finish time from your recent deploys.

From your terminal:

Terminal
cli deploy
cli status
cli logs --deploy dep_abc123

With the API:

API
POST /v1/services/:id/deploys
GET /v1/deploys/:id

When a deploy fails

CLI reads the logs and gives you one error code, the line from the logs that shows the problem, and steps to fix it. The dashboard also has a button that copies a prompt with all of this for your agent.

PhaseCodes
SourceSOURCE_ACCESS_DENIED, IMAGE_PULL_FAILED
BuildBUILD_NO_BUILDER, BUILD_DEP_INSTALL, BUILD_COMPILE, BUILD_TIMEOUT, BUILD_OOM, CONFIG_INVALID, VARIABLE_REFERENCE_MISSING
RuntimeMISSING_ENV, PORT_MISMATCH, HEALTHCHECK_TIMEOUT, RUNTIME_CRASH, RUNTIME_OOM
ReleaseRELEASE_COMMAND_FAILED, SMOKE_TEST_FAILED, CANARY_FAILED
OtherPLATFORM_ERROR (not your fault; retry), UNKNOWN

The most common are PORT_MISMATCH (not listening on $PORT, or only on localhost) and MISSING_ENV (a variable such as DATABASE_URL isn't set). See Error codes for every code and its fix.

See what changed

Every deploy can show what changed since the previous live one: the code (with a GitHub compare link), settings, which variables were added, removed or changed (never their values), and cli.json. Read it before rolling back, or when something that worked breaks.

With the API:

API
GET /v1/deploys/:id/diff

Roll back

A rollback redeploys an earlier healthy image, exactly as it ran before.

In the dashboard: the Roll back button on the project map shows what it will undo before you confirm.

Ask your agent:

"Roll web back to the last version that worked."

With the API:

API
POST /v1/deploys/:id/rollback

Fix-it pull requests

For a failed deploy of a GitHub service, CLI can open a pull request with the smallest fix it can find. It reads the error and the files it points at, and never touches CI files, lockfiles or files it didn't read.

With the API:

API
GET /v1/deploys/:id/fix-pr
POST /v1/deploys/:id/fix-pr

CLI's on-call agent may also propose a fix for you to apply. See Incidents and on-call.

Move in from another platform

CLI can read your existing setup and recreate it: railway.json, Procfile with app.json, render.yaml, fly.toml, vercel.json or docker-compose.yml. With a Railway or Heroku token it reads the whole project through their API instead, which also brings variables and extra services. It shows you the plan first, then creates the services, databases, links, secrets and cron jobs.

In the dashboard: the New service page has an import option.

From your terminal:

Terminal
cli import
cli import --apply
cli import railway --from <railway project> --apply

Ask your agent:

"Move this docker-compose setup to CLI. Show me the plan first."

With the API:

API
POST /v1/projects/:id/import

Start from a template

Starters are working apps you can deploy with one click and then make your own: Next.js with Postgres, FastAPI with Postgres, a Discord bot and an hourly cron worker. They sit at the top of the template gallery; see Starters.

Templates are one-click stacks: a web app with Postgres (with or without Redis), n8n, Umami, Ghost, Uptime Kuma, Metabase, Directus and Gitea. CLI creates every service, wires them together with variable references, and starts each app once its databases are up. Community templates, published by other users, can be free or charge per deploy.

From your terminal:

Terminal
cli templates
cli template umami

With the API:

API
GET /v1/templates
POST /v1/projects/:id/templates/:template

Add --dry-run (or ?dryRun=true) to see the services and hourly cost before anything is created.