Skip to main content
Some work should happen without anyone asking: a nightly health check, an hourly summary, a weekly report. A schedule is a task a person runs on its own, at an interval or on a UTC cron expression, with no console open. Each fire is a fresh durable run under the person’s standing policy and on the person’s own model. The schedule worker fires them. There are two ways to create a schedule: you from a shell, or the person itself from a conversation.

A place to write

A scheduled fire never holds full access, whatever full_access says. It writes only inside the [tools] write_paths roots, so give the person one place to write first:
A fire with no workspace runs no command at all. See Limits and the configuration reference for the rest of [tools].

Creating a schedule from a shell

The task text goes in a file you own, with mode 0600, outside the roots the model can read:
The text is read once, stored encrypted, and passed to each fire on stdin, so you can remove the file after the schedule is created. stampede person schedule create PERSON NAME takes: Give either --every or --cron.

Managing schedules

The same commands work in the console as /person schedule ....

Creating a schedule from a conversation

In the console, a person can schedule its own tasks with the schedule_task tool:
The tool exists only in the console (stampede, stampede chat, stampede tui) for the active person. It sets a name, a cadence and the exact task text, and nothing else. The model cannot choose a model, provider, authority, workspace root or another person; asking for one gets a reply saying so, and the schedule uses the person’s own profile. Task text from chat is limited to 1,024 bytes; longer tasks use --task-file. Creating or resuming a schedule asks you to confirm, in every mode including full access, because a schedule is authority to run later while nobody is watching. The confirmation shows the person, the schedule name, the cadence, the first fire time, how many runs a day it allows, what one run and one day of runs may spend, and the whole task text. When no write_paths entry is configured it adds a line saying the person can write nowhere. Declining creates nothing. Pausing and removing ask like any other persistent change. The tool is not offered to a scheduled run, a remote request, a mailbox run, a resumed run, a stampede agent run or a sub-agent, so a schedule never holds more authority than the person who created it at the keyboard. A schedule made this way is the same object as one made from the shell.

The schedule worker

stampede person schedule serve is the loop that fires due schedules. The installer sets it up as the schedule service:
Run the worker outside the console. With the service running and the console closed, a two-minute schedule created at time t fires at t+2, t+4 and t+6, so after seven minutes notes/ticks.log has three lines. Each fire claims the schedule with a lease so two workers cannot fire it twice, starts a fresh durable run for the person with the task on stdin, and records the run against the schedule. Each occurrence has a deterministic run id, so after a crash the same run is resumed. When the run process exits, the worker reads the run’s record and completes the claim on any terminal status, so the next fire lands on the next boundary. The log line reads scheduled run RUN_ID for PERSON/NAME finished: STATUS. Only a run whose record cannot be found keeps its lease, for fifteen minutes. stampede doctor lists every schedule with its next fire. stampede person runs PERSON shows one run per fire. Service management is covered in Services and doctor.

What a fire may do

A fire runs unattended, so the person’s standing policy is its only bound (see Presets). A research person’s fire cannot write; a builder’s can write inside the configured roots and run the builder command list. full_access authorizes run_command and start_command in an unattended run and nothing else. A fire may hand work to sub-agents. Each child decides its calls through the person’s policy, and any path a task declares must lie inside the person’s own access. The run’s record names every tool call with its outcome, and a refused call with its gate:
A fire that stopped before it finished, for example because the model endpoint was down, can be resumed with stampede runs resume RUN_ID. It resumes with the same roots, workspace and tools it was recorded with. If the configuration has been narrowed since, the resume is refused and the message names the field that is no longer granted.

Schedules on another machine

A schedule belongs to the installation that holds the person. To schedule work for a person on a paired machine, create the schedule on that machine:
See Multiple machines.