> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Background jobs

Durable work through the JobRunner contract and Trigger.dev.

## Setup and configuration

Before any step, read [Before you start](https://supastack.dev/docs/web/before-you-start.md) and [Terminal basics](https://supastack.dev/docs/web/terminal-basics.md). These instructions assume you opened the full supastack monorepo in VS Code; its root package.json marks the repository root. In pnpm commands, a workspace package is an app or shared-code folder; in the product, a workspace is a team's data container and security boundary. corepack pnpm --filter ... selects one package from the monorepo while commands run from its root. If you opened only a synced mobile or desktop folder, it does not contain the Web backend, Docker setup, or root scripts: run the backend from this monorepo or a reachable hosted server, and use the platform folder's own scripts. An environment variable is a named setting stored in a local .env file or your hosting dashboard; restart the relevant app after changing it, and keep server secrets out of NEXT_PUBLIC_ and EXPO_PUBLIC_ values.

1. Open apps/web/src/job-handlers.ts and apps/web/src/scheduler-runtime.ts in VS Code. A job is background work; the scheduler decides when to enqueue it.

2. For a local tick, set the same SCHEDULER_TICK_SECRET in apps/web/.env.local and the repository-root .env; the tick script reads the root .env, while the Web endpoint reads its app settings.

3. Start Web with corepack pnpm --filter @supastack/web dev, then run corepack pnpm jobs:tick from the root. Expected: the terminal shows a POST result from localhost:3000. Trigger.dev is a separate provider and needs its own account and server keys.

Set JOB_PROVIDER=trigger with server-only TRIGGER_SECRET_KEY and TRIGGER_PROJECT_REF for production task submission. Review apps/web/trigger.config.ts and the ai.generate task in apps/web/trigger before configuring the target project.

```
JOB_PROVIDER=trigger
TRIGGER_PROJECT_REF=your-project-reference
# Provide TRIGGER_SECRET_KEY through the server secret store.
# Local/self-hosted scheduler tick:
# SCHEDULER_TICK_SECRET=…
# SCHEDULER_TICK_URL=http://localhost:3000
```


## Commands to copy

Follow the comments to see which folder a command runs in. If two terminals are labeled, open two terminal windows and keep the first command running while you use the second.

```
# Terminal 1 — start the Web app from the monorepo root:
corepack pnpm --filter @supastack/web dev

# Terminal 2 — run one scheduler tick from the monorepo root:
corepack pnpm jobs:tick
```


## Implementation workflow

The shared JobRunner contract promises enqueue, status, and cancel. Trigger.dev owns workflow-specific semantics; do not infer scheduling, retries, or durability guarantees from the generic interface.

The durable application task ID connects dispatch, worker execution, usage records, and results. A failed provider-run metadata attachment after confirmed enqueue must not cause another enqueue or invalidate accepted work.


## Verification and troubleshooting

If the tick returns 404, confirm the secret exists in both settings files and matches exactly, then restart Web. If the terminal says connection refused, start Web first. If no job ran, check that a schedule is enabled and due; one tick does not make a future schedule run immediately.

Verify the deployed task identifier and project match the configured environment. Separate enqueue acceptance from workflow completion and from email delivery. Read docs/production-ai-runtime.md for recovery and safe diagnostics before manually retrying work.


## Next

[Email and mailing](https://supastack.dev/docs/web/email.md)