Skip to main content
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:
FlagShortDescription
--name—Name for the scheduled agent (required)
--cron—Cron expression defining the schedule (required)
--prompt-pPrompt 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-eCloud 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.
ExpressionMeaning
0 9 * * 19:00 AM every Monday
0 2 * * *2:00 AM every day
0 0 * * 0Midnight 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:
FlagDescription
--nameNew name for the scheduled agent
--cronNew cron expression
--promptNew prompt
--skillNew skill spec (skill_name, repo:skill_name, or org/repo:skill_name)
--remove-skillRemove the skill from this schedule
--environmentNew cloud environment ID
--remove-environmentRemove the environment from this schedule
--modelOverride the AI model
--mcpMCP server configuration to add or update. Repeatable
--remove-mcpMCP server name to remove. Repeatable
--hostWorker 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us