Docs menu

Deploy and run

Scaling and running

Size your services, run more copies, scale with traffic, add disks and GPUs, schedule jobs, and delete or restore services.

Explain it

Once your app is live you choose how big it is, how many copies run, and whether it sleeps when nobody's using it. You're only charged for what it actually uses, up to its size, and every change shows its price before you confirm.

How to do it: open an app's Settings: pick a size, the number of copies, autoscaling (more copies when it's busy), and sleep. For sleeping on a timetable or waking instantly, see Sleep, schedules and instant wake.

"Scale my API to three copies and make it sleep after 30 idle minutes."

Once your app is live, you decide how big it is, how many copies run, and when it sleeps. Every change that costs more shows its price before you confirm it, and anything you can change, you can preview first with a dry run (--dry-run in the terminal, ?dryRun=true on the API).

Size

Each service has a size: how much CPU and memory each copy gets. You're charged by the minute for what it uses, up to the size's hourly cost. CPU costs about $0.072 per vCPU-hour and memory about $0.037 per GB-hour, so a copy with 0.5 vCPU and 512 MB costs at most about $0.055 an hour.

In the dashboard: open the service's Settings and move the size slider. It shows the cost per hour and per month before you save.

Ask your agent:

"Is web oversized? If so, downsize it and tell me the saving."

With the API:

API
PATCH /v1/services/:id
JSON
{ "plan": { "cpu": 1, "memMb": 1024 } }

A new size applies on the next deploy. GET /v1/services/:id/usage (or cli usage) shows how much of its size a service really uses, with advice to downsize, upsize or keep it, and the saving. See Credit, pricing and billing.

Copies

Run up to 10 copies of an app behind one address. Each copy is billed as a full size. Deploys are all-or-nothing: the old copies keep serving until every new one is healthy.

In the dashboard: set Copies in the service's Settings.

From your terminal:

Terminal
cli scale 3

With the API:

JSON
{ "replicas": 3 }

The change applies on the next deploy.

Autoscaling

Let the number of copies follow traffic, between a minimum and a maximum, aiming for a number of requests per second per copy. CLI adds copies within about a minute of a rise, and removes them after 10 quiet minutes.

With the API:

JSON
{ "autoscale": { "min": 1, "max": 6, "targetRps": 50 } }

Send {"autoscale": null} to turn it off.

Sleep when idle

An app can stop after a number of minutes without traffic, which stops its billing. The next request wakes it; visitors see a "Starting…" page for a few seconds. This suits previews, staging and side projects. Leave production always on.

In the dashboard: set When nobody's using it in the service's Settings.

From your terminal:

Terminal
cli sleep 30
cli sleep off

With the API:

JSON
{ "sleepAfterMinutes": 30 }

The value can be 5 to 1440 minutes; null keeps it always on. While asleep, the service's status is sleeping. POST /v1/services/:id/wake wakes it.

Volumes

A volume gives an app a persistent disk that survives deploys, billed per GB stored. A service with a volume runs one copy, and restarts on deploy instead of overlapping old and new.

In the dashboard: set Volume path in the service's Settings.

From your terminal:

Terminal
cli volume add /data
cli volume rm

With the API:

JSON
{ "volume": { "mountPath": "/data" } }

GPUs

Apps can ask for GPUs by kind and count. CLI places the app on a server with free cards and bills each GPU by the second while it runs.

From your terminal:

Terminal
cli gpu
cli gpu L4 1
cli gpu off

cli gpu with no argument lists the kinds on offer, their prices and how many cards are free.

With the API:

API
GET /v1/projects/:id/gpus
PATCH /v1/services/:id
JSON
{ "gpu": { "kind": "L4", "count": 1 } }

{"gpu": null} removes them. If no server has enough free cards, you get GPU_UNAVAILABLE with every server's capacity: ask for fewer, try another kind, or join the waitlist.

The GPU waitlist

Add "waitForGpu": true to the same request to join a waitlist when no cards are free:

JSON
{ "gpu": { "kind": "L4", "count": 1 }, "waitForGpu": true }
  1. You still get GPU_UNAVAILABLE, but the message tells you your place in line, and details.waitlist holds the same.
  2. Projects that stake the CLI token at a tier with GPU priority go ahead of everyone else; otherwise it's first come, first served. See The CLI token.
  3. When cards free up, they're held for the next in line for 15 minutes, and a gpu_available event fires in your project.
  4. Send the same request again within those 15 minutes to take them. If you don't, the hold expires and you go back to waiting.

Regions and servers

Each service runs on one server. Your project can choose among the platform's regions, and admins can add their own machines.

In the dashboard: project Settings lists Servers and regions. A service's Settings has Runs on.

With the API:

API
GET /v1/projects/:id/servers
JSON
{ "serverId": "srv_eu1" }

Moving an app rebuilds it on the new server. A database that already has data can't move by itself: branch it onto the other server and point your apps at the copy (see /docs/databases).

To run services on machines in your own AWS, Google Cloud or other account, with no inbound port open for CLI, or to keep a whole project on its own servers, see Run in your own cloud.

Cron jobs

A cron job runs a command on a schedule in your service's live image, with its variables and databases. Schedules are 5-field cron in UTC, or @hourly, @daily and @weekly, at most every 5 minutes. Each run is billed by the second.

In the dashboard: the service has a Cron jobs panel with run history and output.

From your terminal:

Terminal
cli cron add cleanup "0 3 * * *" "node scripts/cleanup.js"
cli cron run cleanup
cli cron logs cleanup
cli cron pause cleanup
cli cron rm cleanup

With the API:

API
POST /v1/services/:id/cron
JSON
{ "name": "cleanup", "schedule": "0 3 * * *", "command": "node scripts/cleanup.js" }

A failed run raises a cron_failed event. You can also define cron jobs in cli.json (see /docs/configuration).

Run a command in a container

Run one-off commands, like migrations or checks, inside the live container. Commands time out after 60 seconds by default, 300 at most, so don't use this for long-running work.

In the dashboard: the service's Console tab.

From your terminal:

Terminal
cli exec "npx prisma migrate deploy"
cli shell

With the API:

API
POST /v1/services/:id/exec

Keys need the secrets scope, and people with a second factor are asked for it again.

Delete and restore

Deleting a service stops it and moves it to the trash for 7 days. Its domains stay reserved. A database keeps its data unless the owner asks to delete it, and even then the data is only removed once the 7 days are up.

In the dashboard: the service's Settings has a delete button; the project's trash lists deleted services with a restore button.

From your terminal:

Terminal
cli rm worker
cli rm postgres --delete-data

With the API:

API
DELETE /v1/services/:id
GET /v1/projects/:id/trash
POST /v1/services/:id/restore

Restoring brings the service back and redeploys the version that was live. ?permanent=true on the delete skips the trash.