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
{
"services": {
"web": { "type": "web" },
"sync": { "type": "cron", "command": "node sync.js", "schedule": "0 2 * * *" }
}
}
| Field | Description |
|---|---|
type | cron |
command | What to run, for example node sync.js or python report.py |
schedule | Five fields in UTC: minute, hour, day of month, month, day of week |
path | Optional 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).
| Schedule | Runs |
|---|---|
0 * * * * | Every hour, on the hour |
0 2 * * * | 02:00 UTC every day |
0 7 * * 1 | 07:00 UTC every Monday |
*/15 8-18 * * mon-fri | Every 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
commandruns your app's code. - A cron or worker with its own
pathis built from that folder. Give it apackage.json(orrequirements.txt) when the primary service is a static site, as thebudget-dashboardexample does with itssnapshotjob.
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.sqlconnect 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.Selectedgrant 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).
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
| Status | Meaning |
|---|---|
running | The container is running |
ok | Exited 0 |
pending_access | Exited 0 but logged ACCESS_PENDING or ACCESS_DENIED; re-run when access lands |
failed | Non-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.
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.