> For the complete documentation index, see [llms.txt](/llms.txt). > Markdown versions of each page are available by appending .md to any URL. # Scheduled Agents Run cloud agents on a cron schedule for automated maintenance and recurring tasks. Warp’s Scheduled Agents let you run cloud agents automatically on a **recurring schedule**. They are designed for routine, repeatable tasks that should happen without manual intervention, such as dead code cleanup, dependency maintenance, issue triage, or periodic refactors. ![Scheduled agents overview video](https://i.ytimg.com/vi/wX9cDbsRXHs/sddefault.jpg) Scheduled Agents run in the background on Warp’s infrastructure. Each run starts from a clean session, executes a fixed prompt, and produces its own task and session history that can be inspected after the fact. For a guided, no-CLI walkthrough that creates a recurring agent from the Oz web app, see the [Scheduled Agents quickstart](/agent-platform/cloud-agents/triggers/scheduled-agents-quickstart/). This page is the full reference for managing schedules with the Oz CLI. If you’re deciding whether to use a schedule, Slack or Linear trigger, GitHub Actions, the Oz CLI, or the API, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). * * * ### What are Scheduled Agents? A Scheduled Agent is a [cloud agent](/agent-platform/cloud-agents/overview/) that runs on a cron-based schedule. **Key characteristics:** - Runs automatically based on a cron expression. - Uses a fixed prompt defined at schedule creation time. - Starts a fresh agent session for every run. - Executes in a specific Warp Environment, if provided. - Consumes credits when it runs. - Can be paused, updated, or deleted at any time. Scheduled Agents are ideal for work that should happen regularly and predictably, without needing a human to trigger the agent manually. ### Common use cases Scheduled Agents are best suited for maintenance-style workflows, including skills that automate recurring tasks. For more on running skill-based agents on schedules, see [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/). Common use cases include: - Dead code or unused feature flag cleanup. - Dependency updates or security scans. - Issue or PR triage on a recurring cadence. - Periodic documentation refreshes. - Repository hygiene tasks like formatting or lint checks. - Scheduled reporting or audits. Because each run is isolated, Scheduled Agents are safe to use for tasks that benefit from a clean, repeatable execution environment. * * * ### Scheduling agents with the Oz CLI Oz scheduled agents are managed through the Oz `schedule` family of CLI commands. All scheduling operations require the Oz CLI and an authenticated session. #### Creating a schedule Use `oz schedule create` (with required flags) to define a new Scheduled Agent. **Each schedule requires:** - A name, for identification. - A cron schedule. - A prompt or skill that the agent will execute. - An optional environment in which the agent will run. - An optional [model selection](/reference/cli/#using-agent-profiles). - [Optional MCP server configuration](/agent-platform/cloud-agents/mcp/). ``` oz schedule create \ --name=NAME \ --cron=SCHEDULE \ --prompt=PROMPT \ [--environment=ENVIRONMENT_ID] \ [--skill=SPEC] \ [--host=WORKER_ID] \ [--mcp=SPEC] \ [--model=MODEL_ID] \ [--file=PATH] ``` **Optional flags:** - `--skill ` — use a skill as the base prompt (format: `repo:skill_name` or `org/repo:skill_name`). See [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/). - `--host ` — run on a specific self-hosted worker instead of Warp-hosted infrastructure. - `--mcp ` — attach MCP servers (inline JSON, file path, or UUID). Can be repeated. - `--model ` — override the default model. - `--file ` — load schedule configuration from a YAML or JSON file. Note Environments are optional — if you don’t specify one, the scheduled agent runs in a barebones sandbox. Without an environment, the agent won’t have access to your code repositories, pre-installed tools, or setup commands, so this is only suited for tasks that don’t need your codebase. **Example** The following command schedules an agent to clean up old feature flags every four days: ``` oz schedule create \ --name "Feature Flag Cleanup" \ --cron "0 10 */4 * *" \ --prompt "Scan the repository for stale feature flags and remove any that are no longer referenced. Open a PR with the changes and include a summary." \ --environment "KB1ndNMQAs5kjPdX2jatA8" ``` Once created, the agent will automatically run at the specified times without further action. Scheduled Agents support the same [model selection](/reference/cli/) and [MCP server configuration](/agent-platform/cloud-agents/mcp/) as other cloud agent triggers. #### Cron schedule format Warp uses standard cron syntax to define schedules. A cron expression consists of five fields: ``` minute hour day-of-month month day-of-week ``` For example: - `0 10 * * *` runs every day at 10:00 AM. - `0 10 */4 * *` runs every four days at 10:00 AM. - `0 8 1 * *` runs at 8:00 AM on the first day of every month. Make sure your cron expression reflects the cadence you want, as Scheduled Agents will run exactly according to this schedule. ### Listing Scheduled Agents To view all Scheduled Agents for your team, use: ``` oz schedule list ``` This command prints a table with details about each schedule, including: - Schedule ID - Name - Cron schedule - Paused - Last run time - Next scheduled run - Scope | ID | Name | Schedule | Paused | Last Ran | Next Run | Scope | | --- | --- | --- | --- | --- | --- | --- | | abc123 | Feature Flag Cleanup | `0 10 */4 * *` | No | `2025-11-24 10:00 AM` | `2025-11-28 10:00 AM` | Team | | def456 | Issue Triage | `0 8 1 * *` | Yes | `2025-11-24 08:00 AM` | Paused | \- | Each completed run also includes links to: - The task created by the agent. - The full agent session, including logs and outputs. This makes it easy to review what ran, when it ran, and what the agent did. You can also monitor scheduled runs alongside your other agents in the [Agent Management Panel](/agent-platform/cloud-agents/managing-cloud-agents/) in the Warp app, where you can filter by the **Scheduled** source to isolate them. #### Viewing a specific Scheduled Agent Use `oz schedule get` to view detailed information about a single Scheduled Agent. ``` oz schedule get SCHEDULE_ID ``` This command returns additional details not shown in the list view, including: - Full schedule configuration - Prompt and model configuration - Environment and MCP settings - Recent runs and execution metadata - Links to related tasks and agent sessions This is useful when reviewing behavior, debugging failures, or inspecting how a Scheduled Agent is configured. ### Pausing and unpausing schedules Scheduled Agents can be temporarily disabled without deleting them. ``` oz schedule pause SCHEDULE_ID ``` When paused, the agent will not run at its scheduled times. **Example** ``` oz schedule pause abc123 ``` #### Unpausing a schedule ``` oz schedule unpause SCHEDULE_ID ``` Once unpaused, the agent resumes running according to its original cron schedule. ### Editing Scheduled Agents You can modify an existing schedule using `oz schedule update`. You may update one or more properties at a time, including: - The schedule name. - The cron schedule. - The prompt used for future runs. - The skill used as the base prompt. - The environment used for execution. - The model, MCP, and host configuration used for future runs. #### Command ``` oz schedule update SCHEDULE_ID \ [--name=NAME] \ [--cron=SCHEDULE] \ [--prompt=PROMPT] \ [--environment=ENVIRONMENT_ID] \ [--skill=SPEC] \ [--remove-skill] \ [--host=WORKER_ID] \ [--mcp=SPEC] \ [--remove-mcp=SERVER_NAME] \ [--model=MODEL_ID] ``` **Additional update flags:** - `--skill ` — update the skill used as the base prompt. - `--remove-skill` — remove the skill from this scheduled agent. - `--host ` — update the execution host. - `--mcp ` — add MCP servers to this schedule. - `--remove-mcp ` — remove an MCP server by name. - `--remove-environment` — remove the environment from this schedule. #### Examples Change when a scheduled agent runs, leaving everything else unchanged: ``` oz schedule update abc123 --cron "0 9 */4 * *" ``` Update the environment used for future runs: ``` oz schedule update abc123 --environment=jkl789 ``` Changes apply only to future runs. Past runs and their session history remain unchanged. ### Deleting a Scheduled Agent To permanently remove a schedule, use: ``` oz schedule delete SCHEDULE_ID ``` **Example** ``` oz schedule delete abc123 ``` Deleting a schedule immediately stops all future runs. Previous runs and their session history remain accessible for inspection and review. * * * ### Execution model and behavior Each scheduled run behaves like a standard cloud agent run, with a few important guarantees: - Every run starts a fresh session. - No state is carried over between runs unless your environment explicitly persists data. - Runs execute automatically without human intervention. - All usage is billed to the team’s shared credit balance. If a scheduled run fails, it does not block future runs. Each execution is independent. Use the [API error reference](/reference/api-and-sdk/troubleshooting/errors/) to interpret any returned error code. ### Permissions and responsibility Scheduled Agents are created and managed by authorized users on a Warp team. By creating a Scheduled Agent, you are responsible for: - The cron schedule and how often the agent runs. - The instructions provided in the prompt. - The environment and integrations the agent has access to. - The credits consumed by scheduled executions. Carefully review prompts and schedules before deploying them broadly, especially for agents that can modify production code or infrastructure. ### When to use Scheduled Agents vs triggers Scheduled Agents are best when work should happen on a predictable cadence. If you want an agent to run in response to an event, such as a Slack mention, PR update, or issue change, use [integrations](/agent-platform/cloud-agents/integrations/) to trigger cloud agents instead. Many teams use both together: [triggers](/agent-platform/cloud-agents/triggers/) for reactive workflows, and Scheduled Agents for proactive maintenance.