DIAL Scheduler
DIAL Scheduler runs chat completions, Responses API calls, REST requests, and Server-Sent Events (SSE) targets on recurring or one-time schedules. It stores schedules and run history in PostgreSQL and executes each run with its owner's delegated credentials. This reference is for platform engineers familiar with DIAL Core configuration.
For the user workflow, see Scheduled tasks. Service setup and Chat integration are described in Configuration; the HTTP and MCP interfaces are described in API.
Capabilities
| Capability | Behavior |
|---|---|
| Recurring and one-time triggers | UTC cron fields or a single date and time |
| Model targets | Chat Completions and Responses API requests, with optional streaming |
| HTTP targets | REST requests and SSE streams using GET, POST, or PUT |
| Schedule management | Create, replace, list, inspect, pause, resume, and delete owner-scoped schedules |
| Immediate execution | Run the saved definition without moving its next scheduled fire |
| Run history | Persist status, timestamps, results, and the executed configuration snapshot |
| Conversation storage | Optionally save successful chat-completion runs as conversations in the owner's DIAL storage |
| MCP tools | Expose schedule, run, and sign-in operations through the API process |
Target and trigger validation is defined in the schedule schemas. Immediate execution runs in the API process; timed execution runs in the worker.
How Scheduler fits together
DIAL Chat reaches Scheduler through a Core application route. Model targets normally point back to Core's model API.
- Authenticate and save. The API resolves the caller through Core, checks external-service sign-in status, and persists the schedule and job.
- Dispatch. The worker polls the shared job store and executes due jobs. The API's own scheduler stays paused.
- Delegate identity. Before dispatch, the executing process requests on-behalf-of (OBO) credentials for the schedule's owner and
service_id. - Record the result. The process applies the target's timeout and retry policy, stores the outcome, and optionally creates a DIAL conversation.
Timed runs execute in the worker; immediate runs execute the same run path in the API process, including credential lookup and conversation storage. Sources: API lifecycle, worker, and run execution.
Dependencies and deployment
| Dependency | Purpose |
|---|---|
| PostgreSQL | Shared persistent schedules, APScheduler jobs, and run history; the upstream Compose sample uses PostgreSQL 16 |
| DIAL Core | Caller identity, application routing, external-service consent, offline delegation, and optional conversation storage |
| Scheduler application and project key | An application identity authorized to request the owner's OBO credentials |
| Target service | A reachable model deployment or HTTP endpoint compatible with the selected target type |
| DIAL Chat | Optional user interface for scheduled tasks and offline sign-in |
One image provides three modes, selected by SERVICE: migrations applies Alembic migrations and exits; api serves HTTP and MCP; worker executes timed jobs. Apply migrations before starting the API and worker. The entrypoint also supports migrations on startup.
The Dockerfile targets linux/amd64, uses Python 3.14 on Alpine, and runs as UID 1001.
Warning
Run exactly one worker against a shared job store. Multiple workers can execute jobs more than once because there is no leader election. Avoid overlapping workers during upgrades; use a recreate deployment strategy.
This constraint is documented in the upstream deployment instructions. The configuration reference distinguishes worker defaults from the job defaults stored by the API.
Health and readiness
| Process | Probe | Meaning |
|---|---|---|
| API | GET /health | SDK-provided liveness endpoint |
| API | GET /ready | 200 with {"status":"ready","database":"ok"} when PostgreSQL is reachable; otherwise 503 |
| Worker | <WORKER_HEALTH_DIR>/started | Startup completed |
| Worker | <WORKER_HEALTH_DIR>/heartbeat | Its modification time must stay within the liveness probe's staleness threshold; the upstream probe uses 180 seconds |
| Worker | <WORKER_HEALTH_DIR>/ready | Present after startup while the latest database readiness check succeeds |
The API listens on 0.0.0.0:5000 by default. The worker serves no HTTP API; it opens a port only for the Prometheus metrics exporter, when OTEL_METRICS_EXPORTER=prometheus. See API startup, readiness, worker health markers, and the SDK metrics server.