Background Jobs

Some apps need to do work on a schedule — send a daily report, sync data every hour, clean up old records every night. Vulcan supports this out of the box with background jobs.

You don't need to configure any infrastructure. Just describe what you want to the AI and it handles everything.

---

How to add a background job

Just ask the AI in plain English:

"Send a summary email every morning at 8am"

"Sync data from our API every hour"

"Clean up orders older than 30 days every night at midnight"

The AI will:

1. Write the job logic
2. Set up the schedule
3. Wire everything together automatically

---

How it works (under the hood)

When you ask for a scheduled job, Vulcan creates a src/jobs/cron.json file in your project that looks like this:

[
  {
    "id": "daily-report",
    "description": "Every day at 9am",
    "schedule": "0 9 * * *",
    "enabled": true
  }
]

You'll see a human-readable description like "Every day at 9am" — the technical schedule format is handled by the AI, not you.

When your app is deployed to production, the job is registered with the Vulcan scheduler. Every minute, Vulcan checks which jobs are due and queues them for execution. Jobs run asynchronously — if a job takes longer than expected or fails, it is automatically retried up to 3 times.

---

Multiple jobs

Your app can have as many scheduled jobs as you need. Just ask:

"Also send a weekly digest every Monday morning"

"Add a job that runs every 15 minutes to check for new orders"

Each job runs independently — if one fails, the others still run.

---

Enabling and disabling jobs

To pause a job without deleting it:

"Disable the daily report job for now"

To re-enable it later:

"Turn the daily report back on"

---

Viewing and editing jobs

Your job files appear in the file panel under src/jobs/. You can:

• View cron.json to see all your scheduled jobs and their descriptions
• View individual job files (e.g. src/jobs/daily-report.ts) to see the logic

To change what a job does or when it runs, just describe the change in chat — the AI will update the files.

---

Important notes

• Runs on production and preview — Background jobs run on your production deployment permanently. They also run on preview for up to 2 hours after a preview deploy, so you can test your job logic before shipping to production. After 2 hours, the preview job schedule pauses automatically — the app itself keeps running, only the cron scheduling stops. To reset the 2-hour window, redeploy preview (click "Deploy to Preview" or send a chat message).
• Deploy required — After adding or changing a job, deploy to activate the changes.
• 30-second limit — Each job run has a 30-second wall-clock limit to return a response. This is Cloudflare's subrequest timeout for Worker-to-Worker calls and cannot be extended. Separately, Cloudflare enforces a 30-second CPU time cap — time spent waiting on external APIs, AI inference, or database calls does not count against CPU time, so I/O-heavy jobs have significant headroom within that window.
• Automatic retries — If a job fails (network error, timeout, unhandled exception), Vulcan automatically retries it up to 3 times with a 60-second delay between attempts. Each attempt is logged separately in the job history. If all 3 retries fail, the job is dropped until its next scheduled run — no further retries happen for that tick.
• At most once per minute — The minimum schedule frequency is once per minute.
• Visible in Server Logs and job history — Each cron invocation appears in the Server Logs tab in real time. You can also see a full history of past runs — successes, failures, retry attempts, and durations — in the Admin → Background Jobs page.

---

Common schedule examples

What you say	When it runs
"Every hour"	At the top of every hour
"Every day at 9am"	Daily at 9:00 AM UTC
"Every Monday at 8am"	Weekly on Mondays at 8:00 AM UTC
"Every 15 minutes"	:00, :15, :30, :45 past each hour
"First day of every month"	Monthly on the 1st at midnight UTC

Note: All times are in UTC. If your team is in a different timezone, ask the AI to adjust — for example, "every day at 9am Eastern" and it will calculate the correct UTC time.

---

Troubleshooting

My job isn't running.

• Check that the job is marked "enabled": true in cron.json.
• Make sure you've deployed after your last change — jobs are registered at deploy time.
• Ask the AI: "Why isn't my daily report job running?"

My job ran but something went wrong.

• Open the Server Logs tab in the App Builder — every cron invocation streams there in real time.
• Check Admin → Background Jobs for a full history of past runs, including error messages and retry attempts.
• Describe the error to the AI and it will help you fix it.

My job keeps failing / all retries are exhausted.

• Vulcan retries a failed job up to 3 times (60-second delay between attempts). After that, the job is dropped and won't run again until its next scheduled tick.
• Check the error in Admin → Background Jobs or Server Logs to see what's going wrong.
• Common causes: the job is calling an external API that's down, an AI inference call is timing out, or there's an unhandled exception in the job logic.
• Ask the AI: "My [job name] job keeps failing with [error] — how do I fix it?"

I want to test my job before deploying to production.

• Deploy to preview — cron jobs run on preview for up to 2 hours, so you can verify the logic before promoting to production.