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 ScheduledAmbientAgents 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).

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:

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

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.

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

Nightly code health checks

Run the test suite, type checker, or linter every night and open a PR with any fixes found.

Automated dependency updates

Check for outdated packages on a weekly schedule and open PRs to update them.

Scheduled PR triage

Every Monday morning, review open PRs and post a summary comment with next steps.

Recurring report generation

Generate a code quality or test coverage report and post it to a Slack channel or file.

Listing schedules

oz schedule list

Getting a schedule’s configuration

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.

# 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.

# Pause a schedule
oz schedule pause <schedule_id>

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

Deleting a schedule

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:

oz task list --schedule <schedule_id>

You can also filter by state to find failures quickly:

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.

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.