Skip to main content
Scheduled tasks are project-level triggers that either enqueue work into room queues or start containers on a schedule. A scheduled task uses a ScheduledTaskSpec file. The spec chooses exactly one target: queue or container. The room is selected when the task is created, not inside the spec.

​
Create a scheduled task

cat > support-summary-task.yaml <<'YAML'
version: v1
kind: ScheduledTask
schedule: 30 17 * * *
queue:
  name: support-jobs
  payload:
    prompt: Generate the daily support summary.
YAML

meshagent scheduled-task add \
  --room support \
  --file support-summary-task.yaml
This creates a scheduled task in the active project that enqueues work into the support-jobs queue in the support room. The payload is a JSON object. For MeshAgent queue consumers, that can include the same structured prompt, content, and thread_id fields supported by meshagent room queue send. Example: 
cat > hourly-support-task.yaml <<'YAML'
version: v1
kind: ScheduledTask
schedule: 0 * * * *
queue:
  name: support-jobs
  payload:
    thread_id: dataset://threads/support/{YYYY}/{MM}/{DD}/{HH}/summary
    prompt:
      - type: file
        url: room:///prompts/hourly-summary.md
      - type: text
        text: Generate the hourly support summary.
YAML

meshagent scheduled-task add \
  --room support \
  --file hourly-support-task.yaml
To start a container instead of writing to a queue, use container: 
cat > container-task.yaml <<'YAML'
version: v1
kind: ScheduledTask
schedule: 0 * * * *
container:
  image: alpine:latest
  command: echo scheduled
YAML

meshagent scheduled-task add \
  --room support \
  --file container-task.yaml

​
Inspect and manage scheduled tasks

List tasks: 
meshagent scheduled-task list
meshagent scheduled-task list --room support
Update a task: 
meshagent scheduled-task update TASK_ID \
  --file support-summary-task.yaml
List runs for a task: 
meshagent scheduled-task runs TASK_ID
Delete a task: 
meshagent scheduled-task delete TASK_ID

​
Where to manage them

  • Use MeshAgent Studio when you want the main UI flow.
  • Use the CLI when you want quick setup or automation.
  • Use the REST API when you need programmatic provisioning.
Schedules must be at least 15 minutes apart. If you want a recurring turn owned by one agent inside a service manifest, use agents[].heartbeat instead of a separate scheduled task.