> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scheduled Tasks

> Create project-level scheduled tasks that enqueue work into room queues or start containers.

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

```bash theme={null}
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:

```bash theme={null}
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`:

```bash theme={null}
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:

```bash theme={null}
meshagent scheduled-task list
meshagent scheduled-task list --room support
```

Update a task:

```bash theme={null}
meshagent scheduled-task update TASK_ID \
  --file support-summary-task.yaml
```

List runs for a task:

```bash theme={null}
meshagent scheduled-task runs TASK_ID
```

Delete a task:

```bash theme={null}
meshagent scheduled-task delete TASK_ID
```

## Where to manage them

* Use [MeshAgent Studio](../interfaces/meshagent_studio) when you want the main UI flow.
* Use the CLI when you want quick setup or automation.
* Use the [REST API](../rest_api/overview) 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.

## Related docs

* [Queues and Scheduled Tasks](../agents/queues_and_scheduled_tasks)
* [Queue API](../room_api/queue)
* [Projects](./projects)