Background workers

Some jobs are designed to start once and keep running for as long as the app needs them. Queue consumers, pollers, bots, and daemons fit that pattern. On Tokay, each one runs as a background worker Service that starts with a deploy, stays alive, and can use the same Project data as the rest of the app.

Last updated July 13, 2026

A worker stays available

The process keeps running without anyone having to start or watch it. Tokay starts the worker on deploy, restarts it after a crash, and brings it back after the virtual machine reboots.

A worker should wait when idle rather than exit. If the code runs, finishes, and should stop, use a scheduled job instead. See Scheduled jobs for how timed runs, manual tests, and run history work.

Failures leave evidence

You can tell when a worker stopped, why it stopped, and when it recovered. Standard output and error stream to the Logs tab while the process runs. If it crashes, Tokay preserves the crash output after the process is gone.

The Events tab records when the worker went down and came back. A worker that repeatedly crashes appears as needing attention on the dashboard. See Logs and debugging for how incident evidence and Copy for AI help you diagnose the failure.

Deploys replace the running process

Deploying an update replaces the current worker with the new version. If the worker handles shutdown signals, we give it a chance to finish its current work before stopping the process.

Each worker has its own deployment history and logs. You can diagnose and redeploy it without replacing the web app that shares its Project.

Workers belong with the app they support

A worker and web app often need the same data. Put them in the same Project so both Services can use the Project's databases and secrets.

Workers do not receive a public URL. If the code needs to accept HTTP requests, use a web app or webhook instead. See Which service type is my code? for how long running processes, scheduled scripts, and request handlers differ.

Pause a worker when it should stop temporarily

Pause gives you a clean temporary stop while keeping the Service ready to resume. The code, configuration, secrets, deployment history, and databases stay in place. See Pause and resume for how pausing affects a Service and the rest of its Project.