Schedulers overview

z4j has two complementary surfaces in this section:

1. Per-engine scheduler adapters (below) - surface an existing native scheduler (celery-beat, rq-scheduler, APScheduler, etc.) in the z4j dashboard so operators can see them and use only the controls that each adapter advertises, without migrating away from the native scheduler. Useful when you're already running the native scheduler and it fits.
2. z4j-scheduler - a separate companion process that fires schedules against any of the six engines z4j supports. Schedules live in z4j's database; edit from the dashboard, declarative config, or REST without a daemon restart. Useful when you have multiple engines in one shop, or want a single audit-logged surface for schedule edits across the org. If you're running one engine and one schedule list, the existing native scheduler is probably fine.

Per-engine scheduler adapters

Each engine has one or more native schedulers it pairs well with; z4j ships an adapter for each so the dashboard surfaces them.

Scheduler	Package	Read	Write	Pairs with
celery-beat	z4j-celerybeat	✓	✓ (requires django-celery-beat)	Celery
rq-scheduler	z4j-rqscheduler	✓	disable / delete / trigger	RQ
APScheduler	z4j-apscheduler	✓	enable / disable / delete / trigger	Dramatiq / standalone
huey-periodic	z4j-hueyperiodic	✓	read-only (decorators)	Huey
arq-cron	z4j-arqcron	✓	read-only (decorators)	arq
taskiq-scheduler	z4j-taskiqscheduler	✓	read-only (labels)	taskiq

Read vs. write

• Read-only - z4j can show the schedule in the dashboard but does not offer mutating controls. This is the surface for the Huey, arq, and TaskIQ code-defined adapters.
• Capability-aware controls - RQ and APScheduler expose selected controls, but not create or update. celery-beat offers the full control set only for django-celery-beat; static beat_schedule entries remain read-only.

Discovery

Schedules are discovered on agent boot through the scheduler-specific API. The agent repeats the snapshot on its configurable resync interval, which defaults to 15 minutes, and an operator can request a sync immediately. Changes made outside the dashboard are picked up on one of those snapshots.

CRUD operations

When the connected adapter advertises them, the UI can expose:

• Create - name, task, cron or interval, args/kwargs, enabled/disabled.
• Update - any of the above.
• Enable / Disable - toggle the native scheduler's enabled state where reversible control exists.
• Delete - remove the entry.

Every CRUD op writes an audit log entry.

Pitfalls

• Clock drift - if your brain and agent live in different timezones, use UTC crontabs. The dashboard renders in the viewer's local time.
• Duplicate schedules - one project can have duplicate names across agents (useful for active/standby). The dashboard shows all.
• Paused-at-broker vs paused-at-scheduler - some engines have both; z4j operates at the scheduler level. If you pause at the broker, the dashboard still shows "enabled" on the schedule.