Skip to main content

Cron and worker services

Next to its primary service, a project can run any number of cron services (started on a schedule) and worker services (long-running, no inbound traffic). Declare them in tc.json.

Declare a cron job​

tc.json
{
"services": {
"web": { "type": "web" },
"sync": { "type": "cron", "command": "node sync.js", "schedule": "0 2 * * *" }
}
}
FieldDescription
typecron
commandWhat to run, for example node sync.js or python report.py
scheduleFive fields in UTC: minute, hour, day of month, month, day of week
pathOptional subfolder with its own source; built from that folder

Schedules​

Schedules support *, lists (1,15), ranges (1-5), steps (*/15, 1-5/2), names (mon, jan) and the aliases @hourly, @daily (or @midnight), @weekly, @monthly and @yearly (or @annually). When both day-of-month and day-of-week are restricted, either may match (classic cron behaviour).

ScheduleRuns
0 * * * *Every hour, on the hour
0 2 * * *02:00 UTC every day
0 7 * * 107:00 UTC every Monday
*/15 8-18 * * mon-friEvery 15 minutes, 08:00–18:59 UTC, weekdays

If the scheduler misses several runs (for example while the platform restarts), they collapse into one run.

Images​

  • A cron or worker in the primary service's folder reuses the primary service's image, so command runs your app's code.
  • A cron or worker with its own path is built from that folder. Give it a package.json (or requirements.txt) when the primary service is a static site, as the budget-dashboard example does with its snapshot job.

Jobs act as the app​

A scheduled run has no signed-in user. Each run gets the platform environment, your environment variables, and a short-lived project identity token in TC_PROJECT_TOKEN (valid for one hour per run). The SDK picks it up automatically, so jobs act as the app:

  • Database: DATABASE_URL / tc.db.sql connect as the project's service role.
  • Storage: jobs manage every file in the project's buckets.
  • Integrations: calls use the project's own grants, for example a Sites.Selected grant to one SharePoint site, or a read-only ERP grant. Mail sent as the app goes to and from the project owner (TC_PROJECT_OWNER_EMAIL).
sync.js
import { tc } from '@tenantcloud/sdk'

const vendors = await tc.m365.list('https://contoso.sharepoint.com/sites/Procurement', 'Vendors').items()
for (const v of vendors) {
await tc.db.sql`insert into vendors (id, name) values (${v.id}, ${v.Title})
on conflict (id) do update set name = excluded.name`
}

When access isn't granted yet​

A job that hits ACCESS_PENDING should log the message and exit 0. The run is recorded as pending_access, and vastframe re-runs the job as soon as the grant is approved, so a nightly sync doesn't wait a day after approval.

Run status​

StatusMeaning
runningThe container is running
okExited 0
pending_accessExited 0 but logged ACCESS_PENDING or ACCESS_DENIED; re-run when access lands
failedNon-zero exit, timeout, or the container couldn't start

Runs time out after 15 minutes by default.

See runs and run now​

Open the project's Logs page and scroll to Scheduled jobs. It lists each cron and worker service with its schedule (times are UTC), the next and last run, Recent runs with their logs, and a Run now button. From the API:

curl -H "Authorization: Bearer $TOKEN" https://console.apps.contoso.com/api/projects/vendors/jobs
curl -X POST -H "Authorization: Bearer $TOKEN" https://console.apps.contoso.com/api/projects/vendors/jobs/sync/run

Worker services​

{ "services": { "web": { "type": "web" }, "queue": { "type": "worker", "command": "node worker.js" } } }

Workers start with each deployment and keep running. They get the same environment and a project identity token.

Availability

Worker services are started but not yet health-checked. Make sure your worker logs clearly when it fails to start.

On the local stack the scheduler starts each run as a fresh container. On Azure, cron services become Container Apps scheduled jobs; that driver is coming soon.

Was this page helpful?