Skip to main content
A schedule launches a finished experiment again on a cron cadence, so you can track agents over time. Each launch uses the project as it is then: the latest tasks, treatments, files, and machines. Who a schedule runs as and when Obss pauses it are on Schedules.

Rules for every change

These rules hold in the CLI and the plugin.
  • Launch check. A create, a resume, or a change to the experiment, --cron, or --time-zone first checks the launch as you. If anything blocks it, the command refuses with schedule_launch_blocked and lists every blocker with its fix link, the same ones obss schedules preview shows. When the check passes, the schedule runs as you.
  • Paused schedules stay paused. A passing check clears the reason Obss paused a schedule, but it stays paused until you resume it. obss schedules update prints the resume command.
  • One launch at a time. obss schedules launch refuses with experiment_schedule_run_active while the schedule’s last experiment still runs.
  • 50 active schedules. A create or resume past that returns schedule_limit_reached.
  • Lock versions. Every change after create takes the --lock-version from obss schedules get, so two people can’t overwrite each other’s edits; a stale value fails with schedule_changed.
  • Attempt IDs. Create and update take an --attempt-id, so a retry after a lost response is the same change. Reusing an ID for a different change fails with schedule_attempt_reused.

Time zones

The cron has five fields (minute, hour, day of month, month, day of week) and always reads in the schedule’s time zone. For example, 0 9 * * 1-5 is 9:00 AM on weekdays. The minute must be 0, 15, 30, or 45, so a schedule launches at most once an hour, on the quarter hour. --time-zone (with a hyphen) takes an IANA name, such as America/New_York, or UTC. It’s required on create because AI assistants and CI machines often run in UTC, and the error suggests your machine’s time zone.

obss schedules preview

Preview when a new or changed schedule launches, the runs it uses, and what would stop it.
Plugin (MCP) tool: preview_schedule Arguments Flags Also takes the global flags. Examples Preview a new weekday schedule:
Preview moving a schedule one hour later:
Result fields Notes The preview changes nothing and checks the launch as you. A paused schedule’s preview shows the launches it would have once you resume it.

obss schedules create

Schedule a finished experiment to launch again on a cadence.
Plugin (MCP) tool: manage_schedule Each scheduled launch spends runs from your organization’s balance. In Ask Obss, you approve each call. Arguments Flags Also takes the global flags. Examples Launch the experiment again at 9:00 AM Pacific every weekday:
Result fields Notes The schedule runs as you.

obss schedules list

List the project’s schedules.
Plugin (MCP) tool: list_schedules Flags Also takes the global flags. Examples Find the schedule that launched an experiment:
Result fields Notes Text output shows needs attention for a schedule that Obss paused. To list the experiments a schedule launched, run obss experiments list --schedule-id. obss experiments get also names the schedule that launched an experiment, in lineage.schedule.

obss schedules get

Read one schedule.
Plugin (MCP) tool: get_schedule Arguments Takes only the global flags. Examples Read the lockVersion before a change:
Result fields Notes Text output shows the status, the cadence, the next launch in the schedule’s time zone, the runs it uses, who it runs as, the last experiment, and the lock version.

obss schedules update

Change a schedule’s name, cadence, time zone, or experiment.
Plugin (MCP) tool: manage_schedule Each scheduled launch spends runs from your organization’s balance. In Ask Obss, you approve each call. Arguments Flags Pass at least one of --name, --cron, --time-zone, or --experiment-id. Also takes the global flags. Examples Move a schedule to 10:00 AM:
Result fields Notes The command changes only the flags you pass, and renaming alone doesn’t change who the schedule runs as. A change to the experiment, --cron, or --time-zone gets the launch check; preview it first with obss schedules preview --schedule-id.

obss schedules pause

Pause a schedule. It does not launch until you resume it.
Plugin (MCP) tool: manage_schedule In Ask Obss, you approve each call. Arguments Flags Also takes the global flags. Examples
Result fields Notes Pausing a paused schedule changes nothing.

obss schedules resume

Resume a paused schedule. It runs as you from its next launch time.
Plugin (MCP) tool: manage_schedule Each scheduled launch spends runs from your organization’s balance. In Ask Obss, you approve each call. Arguments Flags Also takes the global flags. Examples
Result fields Notes Resume runs the launch check. If something blocks it, the schedule stays paused and details.blockers lists every blocker, with the same fields as the preview’s blockers; fix them and run the same command again. Resuming never starts a launch right away, and resuming an active schedule changes nothing.

obss schedules launch

Launch the schedule’s experiment now, as you.
Plugin (MCP) tool: rerun_experiment with schedule_id This command spends runs from your organization’s balance. In Ask Obss, you approve each call. Arguments Flags Also takes the global flags. Examples
Result fields The same fields as obss experiments launch: launchId, experimentId, status, runCount, and dashboardUrl. Follow the launch with obss experiments watch. Notes The launch uses the latest tasks, under the schedule’s name, and doesn’t move the next scheduled launch. It refuses with experiment_schedule_run_active while the schedule’s last experiment still runs (see Rules for every change).

obss schedules delete

Delete a schedule. The experiments it launched stay.
Plugin (MCP) tool: delete_schedule
The schedule stops launching and is deleted. You can’t undo it.
Arguments Flags Also takes the global flags. Examples
Result fields Notes Deleting a schedule that is already deleted returns schedule_not_found.

Schedule fields

obss schedules get, list, create, update, pause, and resume return these fields. obss schedules preview returns the cadence, run, and shortfall fields. In obss notifications list, a schedule’s paused, skipping, and short-of-runs notifications, and the problem notifications of the experiments it launched, carry its scheduleId. To read the runs or frictions of everything a schedule launched, pass --schedule-id to obss runs list or obss frictions list.

Next steps