[GH-ISSUE #238] Scheduled Jobs Documentation #201

New Issue

2026-06-05T15:22:11-04:00

yindo commented

2026-06-05 15:22:11 -04:00

Originally created by @angelplusultra on GitHub (Apr 16, 2026).
Original GitHub issue: https://github.com/Mintplex-Labs/anythingllm-docs/issues/238

Full usage documentation for the new Scheduled Jobs feature (feature branch: feat-background-jobs).

Scheduled Jobs lets users automate AI-powered tasks on a cron schedule. A job runs in a dedicated background worker as an autonomous agent with auto-approved tool calls, and each run captures a full execution trace (thoughts, tool calls, generated files, final response, metrics) viewable from the UI. Runs can also be continued in a workspace thread.

Suggested placement on Sidebar: Guides > Scheduled Jobs (new top-level guide), laid out roughly like below with each section filled out. Please add screenshots/GIFs especially of the Cron Builder, Tools Selector, and Run Detail page.

# Overview
- What Scheduled Jobs is and why it's useful (hands-off automation of agent tasks — reports, digests, data pulls, reminders, etc.)
- Supported on Docker & Desktop
- Note: **only available in single-user mode** — all `/scheduled-jobs` endpoints are gated by single-user mode middleware. Multi-user instances will not see the Scheduled Jobs settings page.

# Setup
- Where to find it in the UI: Settings > Scheduled Jobs
- Environment variables (optional, both have sensible defaults):
  - `SCHEDULED_JOB_MAX_CONCURRENT` — max number of jobs that can run in parallel. Default: `1`. Increase for cloud LLM providers with higher rate limits.
  - `SCHEDULED_JOB_TIMEOUT_MS` — per-run timeout in milliseconds. Default: `300000` (5 minutes). Jobs exceeding this are terminated and marked `timed_out`.
- A "Scheduled Jobs" workspace is auto-created the first time a job runs; it archives job results and backs the "Continue in Thread" flow.

# Creating a Job
Fields in the New Job modal:
- **Name** (required)
- **Prompt** (required) — the task instruction sent to the agent
- **Schedule** (required) — standard 5-field cron. Two input modes:
  - **Cron Builder**: dropdowns for frequency (minute / hour / day / week / month), interval, time picker, weekday pills, etc. Human-readable description updates live (via `cronstrue`).
  - **Custom cron**: raw expression input with validation.
- **Tools** (optional) — multi-select popover grouped by plugin/parent skill. Covers built-in agent skills, imported plugins, agent flows, and MCP servers. Leaving it empty passes **no** tools to the agent (intentional — see commit `bf346e5a`).
- **Enabled** toggle — jobs only register with the scheduler when enabled.

# Managing Jobs
From the Scheduled Jobs page users can:
- List all jobs with name, schedule, enabled status, last run, next run
- Create, edit, delete jobs
- Toggle enable/disable
- **Run Now** — manually trigger a job immediately (bypasses the cron schedule, still respects per-job concurrency)
- Open **Run History** for any job

# Viewing Runs
- **Run History** page — 50 most recent runs for a job, with status, start time, duration, and error (if any). Polls every 5s.
- **Run Detail** page — live-polling (3s) view of a single run showing:
  - Prompt, status, timestamps
  - Agent thoughts (step-by-step reasoning)
  - Tool calls with arguments and results
  - Generated files (downloadable)
  - Final markdown-rendered response
  - Usage metrics (tokens)
  - **Continue in Thread** button on completed runs — opens a workspace thread pre-populated with the job's prompt and response for follow-up conversation.
- Run statuses: `queued` → `running` → (`completed` | `failed` | `timed_out`).

# Capabilities
- Recurring agent execution on any cron schedule
- Access to the full agent toolset (built-in skills, imported plugins, agent flows, MCP servers)
- Full execution trace with thoughts, tool calls, and generated artifacts
- Manual trigger ("Run Now") in addition to scheduled runs
- Continue a completed run as a workspace thread
- Web push notification on job completion (if push notifications are enabled) — includes job name and a preview of the response
- `recomputeNextRunAt` on server boot keeps `nextRunAt` timestamps accurate after restarts

# Limitations
- **Single-user mode only.** Not available on multi-user instances.
- **One run per job at a time.** If a scheduled trigger fires while a prior run is still `queued`/`running`, the new trigger is dropped.
- **Global concurrency cap** across all jobs controlled by `SCHEDULED_JOB_MAX_CONCURRENT`.
- **Timeout cap** via `SCHEDULED_JOB_TIMEOUT_MS` — long-running jobs will be killed.
- Optional `ScheduledJob.MAX_ACTIVE` limit on the total number of enabled jobs (default: unlimited). When set, creating/enabling beyond the cap returns a clear API error.
- If the host machine is off/sleeping, jobs will not fire until it's back online (same caveat as any local scheduler).
- File retrieval from scheduled job runs is explicitly blocked in multi-user mode (defense-in-depth, even though the feature itself is single-user only).

Useful pointers for the docs writer

Backend entrypoint: server/endpoints/scheduledJobs.js
Background worker + queue (p-queue + @breejs/later): server/utils/BackgroundWorkers/index.js
Job runner: server/jobs/run-scheduled-job.js
Prisma models: ScheduledJob and ScheduledJobRun in server/prisma/schema.prisma
Frontend page root: frontend/src/pages/GeneralSettings/ScheduledJobs/
Env var reference: server/.env.example (search for SCHEDULED_JOB_)

Originally created by @angelplusultra on GitHub (Apr 16, 2026). Original GitHub issue: https://github.com/Mintplex-Labs/anythingllm-docs/issues/238 Full usage documentation for the new **Scheduled Jobs** feature (feature branch: `feat-background-jobs`). Scheduled Jobs lets users automate AI-powered tasks on a cron schedule. A job runs in a dedicated background worker as an autonomous agent with auto-approved tool calls, and each run captures a full execution trace (thoughts, tool calls, generated files, final response, metrics) viewable from the UI. Runs can also be continued in a workspace thread. Suggested placement on Sidebar: **Guides > Scheduled Jobs** (new top-level guide), laid out roughly like below with each section filled out. **Please add screenshots/GIFs especially of the Cron Builder, Tools Selector, and Run Detail page.** ```md # Overview - What Scheduled Jobs is and why it's useful (hands-off automation of agent tasks — reports, digests, data pulls, reminders, etc.) - Supported on Docker & Desktop - Note: **only available in single-user mode** — all `/scheduled-jobs` endpoints are gated by single-user mode middleware. Multi-user instances will not see the Scheduled Jobs settings page. # Setup - Where to find it in the UI: Settings > Scheduled Jobs - Environment variables (optional, both have sensible defaults): - `SCHEDULED_JOB_MAX_CONCURRENT` — max number of jobs that can run in parallel. Default: `1`. Increase for cloud LLM providers with higher rate limits. - `SCHEDULED_JOB_TIMEOUT_MS` — per-run timeout in milliseconds. Default: `300000` (5 minutes). Jobs exceeding this are terminated and marked `timed_out`. - A "Scheduled Jobs" workspace is auto-created the first time a job runs; it archives job results and backs the "Continue in Thread" flow. # Creating a Job Fields in the New Job modal: - **Name** (required) - **Prompt** (required) — the task instruction sent to the agent - **Schedule** (required) — standard 5-field cron. Two input modes: - **Cron Builder**: dropdowns for frequency (minute / hour / day / week / month), interval, time picker, weekday pills, etc. Human-readable description updates live (via `cronstrue`). - **Custom cron**: raw expression input with validation. - **Tools** (optional) — multi-select popover grouped by plugin/parent skill. Covers built-in agent skills, imported plugins, agent flows, and MCP servers. Leaving it empty passes **no** tools to the agent (intentional — see commit `bf346e5a`). - **Enabled** toggle — jobs only register with the scheduler when enabled. # Managing Jobs From the Scheduled Jobs page users can: - List all jobs with name, schedule, enabled status, last run, next run - Create, edit, delete jobs - Toggle enable/disable - **Run Now** — manually trigger a job immediately (bypasses the cron schedule, still respects per-job concurrency) - Open **Run History** for any job # Viewing Runs - **Run History** page — 50 most recent runs for a job, with status, start time, duration, and error (if any). Polls every 5s. - **Run Detail** page — live-polling (3s) view of a single run showing: - Prompt, status, timestamps - Agent thoughts (step-by-step reasoning) - Tool calls with arguments and results - Generated files (downloadable) - Final markdown-rendered response - Usage metrics (tokens) - **Continue in Thread** button on completed runs — opens a workspace thread pre-populated with the job's prompt and response for follow-up conversation. - Run statuses: `queued` → `running` → (`completed` | `failed` | `timed_out`). # Capabilities - Recurring agent execution on any cron schedule - Access to the full agent toolset (built-in skills, imported plugins, agent flows, MCP servers) - Full execution trace with thoughts, tool calls, and generated artifacts - Manual trigger ("Run Now") in addition to scheduled runs - Continue a completed run as a workspace thread - Web push notification on job completion (if push notifications are enabled) — includes job name and a preview of the response - `recomputeNextRunAt` on server boot keeps `nextRunAt` timestamps accurate after restarts # Limitations - **Single-user mode only.** Not available on multi-user instances. - **One run per job at a time.** If a scheduled trigger fires while a prior run is still `queued`/`running`, the new trigger is dropped. - **Global concurrency cap** across all jobs controlled by `SCHEDULED_JOB_MAX_CONCURRENT`. - **Timeout cap** via `SCHEDULED_JOB_TIMEOUT_MS` — long-running jobs will be killed. - Optional `ScheduledJob.MAX_ACTIVE` limit on the total number of enabled jobs (default: unlimited). When set, creating/enabling beyond the cap returns a clear API error. - If the host machine is off/sleeping, jobs will not fire until it's back online (same caveat as any local scheduler). - File retrieval from scheduled job runs is explicitly blocked in multi-user mode (defense-in-depth, even though the feature itself is single-user only). ``` ## Useful pointers for the docs writer - Backend entrypoint: `server/endpoints/scheduledJobs.js` - Background worker + queue (`p-queue` + `@breejs/later`): `server/utils/BackgroundWorkers/index.js` - Job runner: `server/jobs/run-scheduled-job.js` - Prisma models: `ScheduledJob` and `ScheduledJobRun` in `server/prisma/schema.prisma` - Frontend page root: `frontend/src/pages/GeneralSettings/ScheduledJobs/` - Env var reference: `server/.env.example` (search for `SCHEDULED_JOB_`)

yindo closed this issue

2026-06-05 15:22:11 -04:00

yindo referenced this issue

2026-06-05 15:22:40 -04:00

[PR #202] [MERGED] Add docs for disabling swagger docs endpoint #186

yindo referenced this issue

2026-06-07 16:45:55 -04:00

[GH-ISSUE #201] Docs for disabling swagger documentation endpoint #69

Sign in to join this conversation.