Workers
A worker is an application built from your repository and kept running, with no public hostname. A scheduled worker is built the same way and run on a schedule, one run at a time, until the command exits. Both have deployments, logs and variables; neither has domains.
Use a worker for something that waits for work: a queue consumer, a listener, a process that polls. Use a scheduled worker for something that should happen at a time and then stop: a nightly report, an hourly sync, a cleanup.
Adding one
On an environment's Overview, choose Add resource, then Worker or Scheduled worker. Kuppit analyses the branch the environment deploys and proposes what to build, as it does for a web service. A worker can point at a different Root directory of the same repository, so an application and its background process can live side by side.
Then, for either kind:
| Field | What it is |
|---|---|
| Command | The executable and its arguments, separated by spaces. Leave it empty to run the image's own command. On an automatic build the command runs inside the detected runtime, so node and the installed packages are available exactly as they are to the start command. |
| Arguments | One per line, passed exactly as written. No shell expands them. |
A worker also asks for its Instances: how many copies are kept running, whether or not there is work. A scheduled worker asks for its Schedule and Time zone instead.
A worker can be added to Production or a named environment, never to a preview.
How a worker runs
A worker's deployment goes through the same steps a web service's does: a build, a revision, then the new revision takes over. What differs is the last step. A web service moves traffic; a worker moves its instances. Until the new revision is running, the previous one keeps working, so a failed deployment never stops a worker that was working.
A worker's instances are allocated for as long as it exists, and are billed for that time whether or not there is work to do — vCPU-hours and GB-hours at the published rates. That is what makes it a worker rather than a web service that scales to zero. A scheduled worker is billed the same way, only for the time each run executes.
PORT is not set, and nothing routes to a worker. A worker that starts an HTTP server is not wrong, but nothing will reach it.
Capacity
The worker's Overview shows how many instances it keeps. Pause sets that to zero: the deployment stays, nothing runs, and nothing is billed for compute until Resume. The Settings tab changes the number, from zero up to ten.
A change to capacity takes effect at once when a deployment is live. If nothing is live yet, it is saved and applied by the first deployment.
The same Pause and Resume are on the worker's card on the project's Overview: right-click it, open the ellipsis on it, or select it and use its panel. Resume brings one instance back; the Settings tab sets the number.
How a scheduled worker runs
A scheduled worker's deployment builds the image and prepares the job; when it goes live, the schedule is pointed at the new job. Each run starts the container with the command, waits for it to exit, and records the outcome. A run has one hour to finish.
Each run starts a fresh container, and Cloud Run takes time to start it: about a minute and a half on an image the size of a built Next.js application, seconds on a small one. The image is what decides it, so a scheduled worker that builds from its own root directory with only the packages the task needs, or from a Dockerfile on a slim base, starts far faster than one that carries the whole website. For something that must run every few minutes, a worker that stays up and keeps its own timer is the right shape; a scheduled worker is for work that happens hourly or daily and then stops.
The Schedule is a five-field cron expression, in the order minute, hour, day of month, month, day of week, with numbers, ranges, lists and steps: 0 * * * * runs hourly, 30 2 * * 1-5 at 02:30 on weekdays. The Time zone is an IANA name, such as UTC or Europe/Amsterdam.
Runs
The Overview lists the recent runs, each with its outcome:
| Run | Meaning |
|---|---|
| Pending | Waiting for the runtime to start it. |
| Running | The run is executing. |
| Succeeded | The run finished and exited cleanly. |
| Failed | The run exited with an error or ran out of time. |
| Cancelled | The run was stopped before it finished. |
Every run names the deployment it ran, so a failed run is one click from that deployment and its runtime logs. A run that fails is not repeated; the next one starts at the next scheduled time.
A run that the runtime did not accept — a transient refusal at the moment the schedule fired — is retried once. That means a run may, rarely, start twice. Write the task so that a repeat is harmless.
Pausing
Pause keeps the deployment and the schedule; nothing starts until Resume. A run already in progress finishes. Both are on the scheduled worker's front page and on its card on the project's Overview, on a right-click or behind its ellipsis. The Settings tab changes the expression and time zone. As with a worker's capacity, a change takes effect at once when a deployment is live, and with the first deployment otherwise.
Variables
A worker has its own variables and inherits every variable set on its environment, exactly as a web service does. Values can be literals or references to what another resource exposes, such as a database's DATABASE_URL. See Environment variables.
A worker does not expose any variables of its own for other resources to reference.
In a named environment
A worker is a component of its environment like any other. When a named environment is created from one that has a worker, the plan offers New worker, deployed from the new environment's branch with the source's configuration copied across, or Don't include. A worker copied forward keeps its command, its capacity or schedule, and its variables; a scheduled worker copied forward starts with its schedule paused as its source was.
Removing a worker
Deleting a worker stops it, destroys the workload and removes its deployment history and, for a scheduled worker, its runs. Deleting an environment removes its workers with it.