The short answer
Three executions, and they do not stand in for each other.
A worker is a process with no inbound HTTP. It stays up and consumes a durable queue. A scheduled job is a command on a cron expression: a name, a cron, a command, and a timezone, with each run under Executions. A one-off command runs once, with that service’s image and variables.
The queue is not the worker. A script that processes one item and exits is a scheduled job or a one-off command, not a worker. Worker services, one-off commands, and scheduled jobs require Pro. The landing is background workers. The rows are Plans.
Three ways to run work that is not an HTTP request
| Worker | Scheduled job | One-off command | |
|---|---|---|---|
| What it is | A long-running process with no inbound HTTP | A command on a cron expression | One command, once |
| When it fits | Email, uploads, indexing, a consumer that waits | A script that starts, does the work, and exits on a schedule | Maintenance you run once |
| What stays up | The process, while it waits for work | Nothing between runs | Nothing after the run |
| What starts it | The service start command | The schedule, or a manual run from Jobs | You, from the Jobs tab or the API |
| Plan | Pro. Not on Free | Pro. Not on Free | Pro. Not on Free |
The worker guide states the split: a start command such as node worker.mjs should stay alive while it waits. A script that processes one item and exits uses a scheduled or one-off flow. The guide is Deploy a background worker.
When you need a background worker
Choose a worker when the process consumes jobs and does not serve HTTP. Sending email, processing uploads, and indexing are the examples in that guide.
In Cloud, add a service and select the Worker category. Connect the repository, review the build command, and set the start command. Put queue credentials and database variables in runtime configuration. How those variables are scoped is Environment variables and secrets.
Do not create a public web service only so a process with no listener can pass an HTTP health check. That failure mode is Debug a failed deployment. How a Compose file maps onto a worker is Docker Compose in production.
For a container build, choose Dockerfile under Build & deploy and enter a path relative to the root directory. ENTRYPOINT or CMD launches the worker. Leave the root directory empty when the Dockerfile needs the whole repository as its build context. Dockerfile workers still run without a public URL, an inbound service, or an HTTP readiness probe.
Deploy and read the runtime log. Enqueue a test job that is not production and follow it to a durable result. A running process does not prove it could authenticate to the queue or finish the work.
On shutdown, stop taking new jobs, finish or release the in-flight job, and close queue and database connections. Use an idempotency key where a second run would charge, send, or write twice. Route repeated failures to the queue’s dead-letter path, or to another durable failure record. Log job IDs and error categories, not payloads that contain private data.
Track queue age, backlog, and completed jobs next to CPU and memory. A quiet CPU can mean there is no work, or that the worker lost the queue connection. Workers run one replica, so concurrency is inside the consumer, within its memory budget and the limits of the systems it calls. Platform logs and resource charts are Logs, metrics and alerts.
The HTTP API that enqueues the work can sit in the same project. That shape is API with PostgreSQL. Work that has to survive a restart does not belong in the web process. For a FastAPI app, the split between BackgroundTasks and a worker is FastAPI in production.
The queue is not the worker
Unbroker runs the consumer. Acknowledgement, retry, and visibility timeout belong to the queue library you run. A loop over an in-memory array is not durable delivery.
The guide’s local check is specific. Enqueue a job with an application-level ID. Acknowledge it only after success. Interrupt processing and confirm the queue can redeliver work that was not acknowledged. Replay the same job and confirm it does not duplicate a payment, an email, or another sensitive effect.
Redis can be that queue. Cache, sessions, and queues are a separate decision: Managed Redis.
Beacon is realtime messaging. It delivers at most once. Messages published while a client is disconnected are not replayed. For work that must run exactly once, use a durable queue. Beacon can tell a client after that result is stored. The note is Beacon reliability.
When a cron job is the better fit
Use a scheduled job when the program starts, does the work, and exits. A nightly rebuild, a report, or a cleanup that is not waiting on a queue fits here. The schedule does not replace a durable queue, and the worker does not replace the schedule.
Every service has a Jobs tab. A scheduled job has a name, a cron expression, a command, and a timezone. Each run’s output is under Executions. The tab can start a saved job. The release note is the August 1 changelog.
Commands require the service to be running. The Jobs tab says to start the service before executing commands. The Heroku migration page states the same rule for scheduled jobs, and it says Scheduler entries are not imported. How a Procfile worker line, the release process, and a Scheduler entry become separate services is a Heroku Procfile, line by line.
The documented HTTP API, on Infrastructure API:
GETandPOST /apps/services/:id/jobslist or create jobs.PUTandDELETE /apps/services/:id/jobs/:jobIdupdate or delete one.POST /apps/services/:id/jobs/:jobId/runruns a job now.
The published ubctl pages do not document a jobs command. ubctl apps backups schedule accepts --cron for a volume backup. That schedule is not the Jobs tab. The reference is Storage commands.
The docs do not state how long a scheduled run may last, or what happens if two runs would overlap. This page does not add either rule.
One-off commands for maintenance
A one-off command runs once, with the service’s image and variables. On the Jobs tab the panel is One-off command, with a command field and a Run button. The API is POST /apps/services/:id/commands. The same running-service rule applies.
On October 8, 2026 the interactive browser terminal was removed. One-off commands and scheduled jobs stayed. A manual run creates an activity event that names the person who launched it and the service. The command text stays on the execution record. It is not copied into the organization-wide activity feed. The note is audited commands.
Use a one-off command for maintenance you want once. Use a scheduled job when that command should recur. Use the pre-deploy command when a migration has to finish before the new version is live. That release step is Database migrations on deploy.
What not to confuse with these
A pre-deploy command runs once from the new image before that version goes live. Rollbacks do not run it again. The changelog example is npm run db:migrate. Migration commands require Pro. The docs do not say what a failed pre-deploy command does to the version that is already live.
A post-deploy command is a different hook. It runs after the deployment is live, in a one-off copy of the new image, with that service’s environment variables, for at most 10 minutes. The output is appended to the deployment log. If the command fails, the deployment stays live and nothing is rolled back. The command does not run when the deploy itself fails. It does not mount a persistent volume. Put secrets in variables, not in the command string. The October 26 changelog says post-deploy commands require a paid plan and are not available for image services.
That 10 minute limit is the post-deploy command. The docs do not state it for a scheduled job or for a one-off command on the Jobs tab. The sources are Deployments and the October 26 changelog.
Beacon is not the queue. Serverless is not a way to run a worker. Serverless scales an idle HTTP container to zero and wakes it on the next request. It supports public repository and static-upload HTTP services with one fixed replica. Images, workers, Dockerfile builds, persistent volumes, private networking, and autoscaling are not supported. The section is Service types.
How this works on Unbroker
Service types describes a worker as a process without inbound HTTP traffic, useful for queues, scheduled processing, indexing, and asynchronous jobs. The worker guide still draws the line: a script that processes one item and exits is a scheduled or one-off job, not that long-running process. A worker already has no Service and no public URL, so it cannot be marked private.
Image services, workers, and any service with a persistent volume always run one replica. Repository and upload services are the ones that can run several replicas, including autoscaling. That control is Replica autoscaling. It does not add a second replica to a worker.
Pro is $25 per month with $25 of usage credit. The credit resets each billing cycle, does not roll over, and has no cash value. If eligible usage stays under the credit, the monthly charge is still the plan price. Worker runtime, and the queue or database, each contribute to usage. The plans page does not publish a separate worker price. On Pro, CPU and memory limits are configurable. Current rows are on pricing and in Plans. The same capability rows are Contract on Enterprise, which is a separate agreement.
There is no documented ubctl command for these jobs. The HTTP routes above are the documented automation. API token creation requires Pro. What a token is allowed to do starts at Coding agents.
Checklist
- Use a worker when the process must stay up and consume a durable queue.
- Use a scheduled job when the script starts, does the work, and exits.
- Use a one-off command for a single maintenance run, on the service’s image and variables.
- Keep the queue outside the worker. Use that library’s acknowledgement, retry, and dead-letter path.
- Put queue credentials in runtime variables, not in the command string.
- Do not add a public web service only so a worker can pass an HTTP health check.
- On shutdown, stop taking jobs, finish or release the in-flight job, and close connections.
- Log job IDs and error categories. Leave private payloads out of the log.
- Use Pro for workers, one-off commands, and scheduled jobs. Leave Serverless off the worker.
FAQ
How do I run background workers on a PaaS?
On Unbroker, add a service and select the Worker category. Connect the repository, review the build command, and set a start command that stays alive, such as `node worker.mjs`. Put queue credentials in runtime configuration. Deploy and follow a test job in the runtime log. A worker is a process with no inbound HTTP; it stays up and consumes a durable queue. Worker services require Pro, and they run one replica. A script that processes one item and exits is a scheduled job or a one-off command, not a worker. The source is the worker guide.
What is the difference between a background worker and a cron job?
A worker is a long-running process with no inbound HTTP. The start command stays up and consumes a queue, for example node worker.mjs. A scheduled job is a named command, a cron expression, and a timezone on the Jobs tab. Each run's output is under Executions. A script that processes one item and exits is a scheduled job or a one-off command, not a worker. The source is the worker guide.
Does Unbroker have a Heroku Scheduler equivalent?
The Heroku migration page calls scheduled jobs the closest equivalent to Heroku Scheduler: a named command, a cron expression, and a timezone, on a service that is running. Scheduler entries are not imported. One-off commands are separate, and they are not a schedule. This page does not compare prices.
Do worker services require Pro?
Yes. The plans table lists worker services as not available on Free and available on Pro. Pro is $25 per month with $25 of usage credit. The credit resets each billing cycle and does not roll over. If eligible usage stays under the credit, the monthly charge is still the plan price.
How many replicas can a worker run?
One. Service types says image services, workers, and any service with a persistent volume always run one replica. Concurrency belongs inside the consumer, within its memory budget and the limits of whatever it calls.
Can I give a worker a public URL or an HTTP health check?
No. A worker cannot be marked private, because it already has no Service and no public URL. Dockerfile workers run without a public URL, an inbound service, or an HTTP readiness probe. Do not create a public web service only so a process with no listener can pass an HTTP health check.
Where do I put the queue, in the worker process?
No. The worker and the durable queue are separate. Acknowledgement, retry, visibility timeout, and a dead-letter path belong to the queue library you run. A loop over an in-memory array is not durable delivery. Redis can be the queue. Beacon cannot.
How do I run a scheduled job on Unbroker?
Open the Jobs tab on the service. A scheduled job has a name, a cron expression, a command, and a timezone. Output is under Executions. The tab can start a saved job while the service is running. The HTTP API lists and creates jobs at GET and POST /apps/services/:id/jobs, updates or deletes one at PUT and DELETE /apps/services/:id/jobs/:jobId, and runs one now at POST /apps/services/:id/jobs/:jobId/run. The published ubctl pages do not document a jobs command.
What happened to the interactive browser terminal?
It was removed on October 8, 2026. One-off commands and scheduled jobs remain. A manual run creates an activity event that names the person who launched it and the service. The command text stays on the execution record. It is not copied into the organization-wide activity feed.
Are one-off commands and scheduled jobs available on Free?
No. The plans table lists one-off commands and scheduled jobs as not available on Free and available on Pro. The same table lists worker services as not available on Free.
Is Beacon a job queue?
No. Beacon delivers realtime messages at most once. Messages published while a client is disconnected are not replayed. For work that must run exactly once, use a durable queue. Beacon can notify a client after that durable result is stored.
Should I run cron inside my web process?
Put a command that starts, does the work, and exits on the Jobs tab, as a scheduled job or a one-off command. Put a process that stays up and consumes a queue in a worker. A timer inside the HTTP process is not one of those documented executions. The docs do not say what happens if two scheduled runs overlap, so this page does not either.