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

# Schedule Oz agents on a cron schedule

> Create ScheduledAmbientAgents that run Oz cloud agents automatically on a cron schedule — for nightly checks, weekly triage, and other recurring automation.

Scheduled agents — called `ScheduledAmbientAgent`s internally — let you configure an Oz agent to run automatically on a cron schedule. Instead of manually triggering a run each time, you define a prompt, an environment, and a cron expression, and Oz takes care of the rest. Every scheduled execution produces a normal run that you can inspect with `oz task list`.

## Creating a schedule

Use `oz schedule create` to define a new scheduled agent. The two required pieces are `--name`, `--cron`, and either `--prompt` or `--skill` (at least one is required).

```bash theme={null}
oz schedule create \
  --name "nightly-type-check" \
  --cron "0 2 * * *" \
  --prompt "Run the TypeScript compiler in strict mode and open a PR fixing any type errors" \
  --environment <environment_id>
```

`oz schedule` alone is a shorthand for `oz schedule create`, so the following is equivalent:

```bash theme={null}
oz schedule \
  --name "nightly-type-check" \
  --cron "0 2 * * *" \
  --prompt "Run the TypeScript compiler in strict mode and open a PR fixing any type errors" \
  --environment <environment_id>
```

**`oz schedule create` flags:**

| Flag               | Short | Description                                                                              |
| ------------------ | ----- | ---------------------------------------------------------------------------------------- |
| `--name`           | —     | Name for the scheduled agent (required)                                                  |
| `--cron`           | —     | Cron expression defining the schedule (required)                                         |
| `--prompt`         | `-p`  | Prompt for what the agent should do each run                                             |
| `--skill`          | —     | Skill spec to use as the base prompt. Format: `repo:skill_name` or `org/repo:skill_name` |
| `--environment`    | `-e`  | Cloud environment ID to run the agent in                                                 |
| `--no-environment` | —     | Run without a cloud environment (not recommended)                                        |
| `--model`          | —     | Override the AI model used by the agent                                                  |
| `--mcp`            | —     | MCP server configuration (path to JSON file or inline JSON). Repeatable                  |
| `--host`           | —     | Worker ID for self-hosted execution. Omit to use Warp's infrastructure                   |

<Note>
  You must provide at least one of `--prompt` or `--skill`. You can provide both: the skill supplies the
  base context and the prompt provides the specific task for each run.
</Note>

## Cron syntax

Oz uses standard five-field cron syntax: `minute hour day-of-month month day-of-week`.

| Expression    | Meaning                             |
| ------------- | ----------------------------------- |
| `0 9 * * 1`   | 9:00 AM every Monday                |
| `0 2 * * *`   | 2:00 AM every day                   |
| `0 0 * * 0`   | Midnight every Sunday               |
| `30 8 1 * *`  | 8:30 AM on the first of every month |
| `0 */6 * * *` | Every 6 hours                       |

All times are evaluated in UTC.

## Use cases

<CardGroup cols={2}>
  <Card title="Nightly code health checks" icon="heart-pulse">
    Run the test suite, type checker, or linter every night and open a PR with any fixes found.
  </Card>

  <Card title="Automated dependency updates" icon="arrow-up-circle">
    Check for outdated packages on a weekly schedule and open PRs to update them.
  </Card>

  <Card title="Scheduled PR triage" icon="git-pull-request">
    Every Monday morning, review open PRs and post a summary comment with next steps.
  </Card>

  <Card title="Recurring report generation" icon="chart-bar">
    Generate a code quality or test coverage report and post it to a Slack channel or file.
  </Card>
</CardGroup>

## Listing schedules

```bash theme={null}
oz schedule list
```

## Getting a schedule's configuration

```bash theme={null}
oz schedule get <schedule_id>
```

## Updating a schedule

You can change a schedule's name, cron expression, prompt, environment, model, or MCP servers without deleting and recreating it.

```bash theme={null}
# Change the cron expression
oz schedule update <schedule_id> --cron "0 3 * * *"

# Update the prompt
oz schedule update <schedule_id> \
  --prompt "Run the linter and fix all auto-fixable errors, then open a PR"

# Swap the environment
oz schedule update <schedule_id> --environment <new_environment_id>

# Remove the environment
oz schedule update <schedule_id> --remove-environment

# Add or update an MCP server
oz schedule update <schedule_id> --mcp ./mcp-config.json

# Remove an MCP server by name
oz schedule update <schedule_id> --remove-mcp my-server-name

# Assign a skill
oz schedule update <schedule_id> --skill owner/repo:skills/weekly-review

# Remove the skill
oz schedule update <schedule_id> --remove-skill
```

**`oz schedule update` flags:**

| Flag                   | Description                                                                |
| ---------------------- | -------------------------------------------------------------------------- |
| `--name`               | New name for the scheduled agent                                           |
| `--cron`               | New cron expression                                                        |
| `--prompt`             | New prompt                                                                 |
| `--skill`              | New skill spec (`skill_name`, `repo:skill_name`, or `org/repo:skill_name`) |
| `--remove-skill`       | Remove the skill from this schedule                                        |
| `--environment`        | New cloud environment ID                                                   |
| `--remove-environment` | Remove the environment from this schedule                                  |
| `--model`              | Override the AI model                                                      |
| `--mcp`                | MCP server configuration to add or update. Repeatable                      |
| `--remove-mcp`         | MCP server name to remove. Repeatable                                      |
| `--host`               | Worker ID for self-hosted execution                                        |

## Pausing and unpausing schedules

A paused schedule still exists and retains its configuration, but does not fire. Unpause it to resume normal execution.

```bash theme={null}
# Pause a schedule
oz schedule pause <schedule_id>

# Resume a paused schedule (alias: oz schedule resume)
oz schedule unpause <schedule_id>
```

## Deleting a schedule

```bash theme={null}
oz schedule delete <schedule_id>
```

Deleting a schedule prevents any future runs. Runs that have already completed are not affected and remain accessible via `oz task list`.

## Viewing scheduled run history

Each time a scheduled agent fires, it creates a normal run. Use `oz task list` with the `--schedule` filter to see only runs from a particular schedule:

```bash theme={null}
oz task list --schedule <schedule_id>
```

You can also filter by state to find failures quickly:

```bash theme={null}
oz task list --schedule <schedule_id> --state failed
```

## Using skills with scheduled agents

Skills are reusable agent prompts stored in your repository (in `.agents/skills/`, `.warp/skills/`, `.claude/skills/`, or `.codex/skills/`). Referencing a skill rather than a hard-coded prompt means the agent's instructions live in version control and can evolve alongside your codebase.

```bash theme={null}
oz schedule create \
  --name "weekly-dependency-update" \
  --cron "0 9 * * 1" \
  --skill owner/my-app:dependency-update \
  --environment <environment_id>
```

The skill is resolved at runtime inside the agent's cloud environment, so it always reflects the latest version in the repo.