# Setting Up Recurring Background Jobs with Cron in Agent-Native

> Effortlessly set up recurring background jobs with cron in Agent-Native. Configure schedules in wrangler.toml and implement job logic to automate tasks.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: how-to-guide
- Published: 2026-06-27

---

**You configure recurring background jobs in Agent-Native by defining cron schedules in [`wrangler.toml`](https://github.com/BuilderIO/agent-native/blob/main/wrangler.toml) and implementing job logic in `server/plugins/` directories, with execution gated by the `RUN_BACKGROUND_JOBS` environment variable.**

Agent-Native (BuilderIO/agent-native) leverages Wrangler's built-in cron triggers to handle automated tasks like mail processing and automation workflows. This architecture allows agents to run background logic on a schedule without external scheduling services. Understanding how to implement and control these jobs is essential for customizing agent behavior and managing resource usage in development environments.

## How Cron Jobs Work in Agent-Native

Cron jobs in Agent-Native use Cloudflare Workers' cron trigger system, configured through the [`wrangler.toml`](https://github.com/BuilderIO/agent-native/blob/main/wrangler.toml) file in each template directory. The configuration defines when the job runs, while the implementation resides in TypeScript files under `server/plugins/`.

In [`templates/mail/wrangler.toml`](https://github.com/BuilderIO/agent-native/blob/main/templates/mail/wrangler.toml), the cron schedule is declared in the `[triggers]` section:

```toml
[triggers]
crons = ["*/5 * * * *"]

```

This configuration tells Wrangler to trigger the worker every five minutes. When the cron fires, the worker executes the scheduled job logic defined in the corresponding plugin file.

## Enabling Cron Jobs in Development

By default, cron jobs are **disabled in development** to prevent unnecessary resource consumption and accidental execution during local testing. You must explicitly enable them using the `RUN_BACKGROUND_JOBS` environment variable.

Set the variable before starting your development server:

```bash
export RUN_BACKGROUND_JOBS=1
wrangler dev --local

```

Alternatively, add it to your `.env` file in the template directory:

```env
RUN_BACKGROUND_JOBS=1

```

In production environments, background jobs run automatically without this flag. The implementation in [`templates/mail/server/plugins/mail-jobs.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/mail/server/plugins/mail-jobs.ts) checks this environment variable to gate execution:

```typescript
// Only run background jobs if explicitly enabled in dev
if (process.env.RUN_BACKGROUND_JOBS !== '1' && process.env.NODE_ENV !== 'production') {
  console.log('[mail-jobs] Background jobs disabled. Set RUN_BACKGROUND_JOBS=1 to enable.');
  return;
}

```

## The Mail Jobs Reference Implementation

The mail template provides a complete reference implementation for recurring background jobs in [`templates/mail/server/plugins/mail-jobs.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/mail/server/plugins/mail-jobs.ts). This file demonstrates the standard pattern for Agent-Native cron jobs.

The plugin initializes during worker startup and uses a `setInterval`-style execution pattern managed by Wrangler's cron system:

```typescript
export default {
  async cron(event: ScheduledEvent, env: Env, ctx: ExecutionContext) {
    console.log('[mail-jobs] Starting mail processing job');
    
    // Database interaction
    const db = getDatabase(env);
    
    // Process pending automations
    await processMailAutomations(db, env);
    
    console.log('[mail-jobs] Completed processing');
  }
};

```

The mail job interacts with the database via [`templates/mail/server/plugins/db.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/mail/server/plugins/db.ts) and triggers automation logic defined in [`templates/mail/server/lib/automation-engine.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/mail/server/lib/automation-engine.ts). It serves as the canonical example for implementing time-based background processing.

## Creating Custom Cron Jobs

To implement a new recurring background job for your agent, follow this three-step process:

### 1. Configure the Cron Schedule

Add a new entry to the `[triggers]` section in your template's [`wrangler.toml`](https://github.com/BuilderIO/agent-native/blob/main/wrangler.toml):

```toml
[triggers]
crons = ["*/5 * * * *", "0 */6 * * *"]

```

The second entry runs every six hours. Use standard cron syntax to define your schedule.

### 2. Create the Plugin File

Create a new file under `templates/<your-agent>/server/plugins/custom-jobs.ts`:

```typescript
import { getDatabase } from './db';

export default {
  async cron(event: ScheduledEvent, env: Env, ctx: ExecutionContext) {
    // Dev gate check
    if (process.env.RUN_BACKGROUND_JOBS !== '1' && process.env.NODE_ENV !== 'production') {
      console.log('[custom-jobs] Skipping execution in development');
      return;
    }

    console.log('[custom-jobs] Running custom background task');
    
    // Your background logic here
    await performCustomTask(env);
  }
};

```

### 3. Expose Actions for Cron Invocation

If your cron needs to trigger agent actions, ensure those actions are exposed to non-interactive callers. In [`templates/mail/.agents/skills/actions/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/templates/mail/.agents/skills/actions/SKILL.md), actions triggered by cron should set `agentTool: false` to indicate they can be called programmatically:

```typescript
export const customAction = {
  agentTool: false, // Accessible by cron, not just LLM
  async handler({ db, env }) {
    // Action logic
  }
};

```

Reference the [`templates/mail/actions/trigger-automations.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/mail/actions/trigger-automations.ts) file for an example of an action designed to be invoked by cron jobs.

## Testing and Debugging Cron Jobs

Test cron jobs locally using Wrangler's development environment:

```bash
export RUN_BACKGROUND_JOBS=1
wrangler dev --local

```

Monitor the console output for `[mail-jobs]` or your custom job prefix to verify execution. The cron simulation in local development respects your [`wrangler.toml`](https://github.com/BuilderIO/agent-native/blob/main/wrangler.toml) schedule, though you can manually trigger execution for testing:

```bash

# Trigger a specific cron handler manually via debug endpoint

curl http://localhost:8787/debug/trigger-cron

```

Check the [`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md) file in the repository root for template-specific background job documentation and troubleshooting steps.

## Summary

- **Configuration**: Define schedules in [`wrangler.toml`](https://github.com/BuilderIO/agent-native/blob/main/wrangler.toml) using the `[triggers]` section with standard cron syntax.
- **Implementation**: Create plugin files in `server/plugins/` that export a `cron` handler function.
- **Development Gate**: Set `RUN_BACKGROUND_JOBS=1` to enable execution in local development; production runs automatically.
- **Reference**: Study [`templates/mail/server/plugins/mail-jobs.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/mail/server/plugins/mail-jobs.ts) for the canonical implementation pattern.
- **Action Exposure**: Set `agentTool: false` for actions that cron jobs should invoke directly.

## Frequently Asked Questions

### What is the default cron schedule for the mail agent?

The mail agent in [`templates/mail/wrangler.toml`](https://github.com/BuilderIO/agent-native/blob/main/templates/mail/wrangler.toml) runs every five minutes (`*/5 * * * *`) by default. You can modify this schedule in the `[triggers]` section to run more or less frequently depending on your processing requirements.

### Why are my cron jobs not running in local development?

Cron jobs are disabled in development by default to conserve resources. You must set the environment variable `RUN_BACKGROUND_JOBS=1` before starting `wrangler dev`. Without this flag, the job logic exits early as implemented in the dev gate check within [`mail-jobs.ts`](https://github.com/BuilderIO/agent-native/blob/main/mail-jobs.ts).

### Can I create multiple cron schedules for a single agent?

Yes. Add multiple cron expressions to the `crons` array in [`wrangler.toml`](https://github.com/BuilderIO/agent-native/blob/main/wrangler.toml). For example, `crons = ["*/5 * * * *", "0 9 * * *"]` creates two triggers—one every five minutes and one daily at 9 AM. Handle different schedules within your plugin by checking `event.cron` to determine which schedule triggered the execution.

### How do cron jobs access the database?

Cron jobs access the database using the same pattern as HTTP handlers. Import your database utility from [`server/plugins/db.ts`](https://github.com/BuilderIO/agent-native/blob/main/server/plugins/db.ts) and call it with the `env` parameter passed to the cron handler. The [`templates/mail/server/plugins/mail-jobs.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/mail/server/plugins/mail-jobs.ts) file demonstrates this pattern by initializing the database connection at the start of each cron execution.