Scheduling
Istota supports cron-based scheduling through CRON.md files and natural-language reminders.
CRON.md
Each user can define scheduled jobs in /Users/{user_id}/{bot_dir}/config/CRON.md. The file uses markdown with an embedded TOML block:
# Scheduled jobs
```toml
[[jobs]]
name = "daily-check"
cron = "0 9 * * *"
prompt = "Check my calendar for today and summarize what's coming up"
room = "room123"
[[jobs]]
name = "backup-reminder"
cron = "0 10 * * 1"
prompt = "Remind me to check the backup logs"
target = "talk"
silent_unless_action = true
[[jobs]]
name = "disk-check"
cron = "0 */6 * * *"
command = "df -h \"$NEXTCLOUD_MOUNT_PATH/Users/$ISTOTA_USER_ID\" | tail -1"
```
Shell semantics for command jobs. The command runs under bash -o pipefail -c, so a pipeline reports the first stage that failed rather than the last command — <runner> … | tail no longer comes back clean on a run that failed. Three consequences worth knowing when you write one:
- A non-final stage that exits non-zero to report something rather than to fail now fails the whole job.
grepfinding no match is the common one;diffandgit diff --quietbehave the same way. Put those on their own line, or append|| truewhere the status genuinely does not matter. - A pipeline ending in
headorgrep -qcloses the pipe early and reports status 141. That is SIGPIPE rather than a failure, the job'slast_errorsays so, and it is failed without retrying — the retry would re-run a command whose first stage already did its work. - The interpreter is bash, not
/bin/sh. If a job was written against dash, note thatechono longer expands backslash escapes such as\t.
Where a command job runs. In the same sandbox as a task's Bash call. CRON.md is a file the bot can edit, so a job has no more reach than the bot has. It sees your own workspace and its per-user temp directory, reaches the network through the task allowlist, and calls skills through istota-skill, which runs them outside the sandbox with their credentials. It does not see the host's files, another user's workspace or the databases, and neither a credential nor a database path is in its environment. Its working directory is your temp directory. A script it runs has to live in your workspace. / is the sandbox's own empty root, so df -h / reads near zero whatever the host's disk holds: name a path in your workspace instead. A nested bash script.sh runs with pipefail on as well. A job that needs the host, such as a backup of the machine, belongs in a system cron entry or a systemd timer, outside anything the bot can write.
CRON.md is the source of truth. cron_loader.py reads it and syncs job definitions to the scheduled_jobs DB table.
Deleting a job from the file deletes it. That includes the last one: a file whose TOML block is empty means you have no jobs, and the sync removes the rows to match. Two shapes are not that, and neither deletes anything:
- A file with no TOML block, or one holding only comments, has had no job list written into it. That is what a freshly seeded CRON.md looks like, so if the table holds jobs they are written into the file instead — which is how a workspace whose CRON.md went missing fills back in. Emptying the block by hand but leaving a comment in it lands here too; delete the comment as well if you meant the jobs to go.
- A file that lists jobs the loader cannot use — a typo in a required key, a
prompt_filethat is missing or unreadable — is left alone with a warning in the log, and so are the existing rows. Fix the file and the next tick picks it up. Aprompt_filethe path rule refuses (outside your own folder,.., a symlink, not a regular file) is not held this way: that job's row is removed, because the rule will refuse it on every tick.
Rewriting CRON.md replaces the first TOML block and nothing else. Notes you keep above or below the fence, a second fenced block, the header you rewrote — all of it survives !cron disable, the removal of a once job and the rest. Comments inside the block and any key the loader does not read do not survive, because the block is re-rendered. A file holding a job entry the loader skipped is not re-rendered at all. !cron enable and !cron disable then leave the file alone and warn you, and the next sync can undo the change until the file is fixed. Removing a job, including a finished once job, cuts out that job's entry and leaves the other entries and comments as they were. If the entry cannot be separated with certainty, for example because a job's text contains a [[jobs]] line, the file is not changed and a finished once job stays in it, where it can run again. The one case that still rewrites the whole file is the seeded-template restore above, which has no job list to splice into.
Job types
There is no type field. The loader infers the kind from which of prompt, prompt_file, or command a job sets, and a job that sets more than one is skipped with a warning rather than guessed at.
Prompt jobs (default): Run through the brain like any other task. The prompt is sent to the executor with full skill and context support.
Prompt file jobs: Like prompt jobs, but the prompt is loaded from an external file. The path is written from the workspace root and must name a file in the job owner's own folder, /Users/<owner>/.... The scheduler reads it outside any sandbox, so another user's folder, a room's Channels/ folder, a .. component and a symlink at any level are all refused, and the job is dropped from the schedule until the path is fixed. prompt_file cannot be combined with prompt or command.
A multiline prompt becomes one of these the first time anything rewrites the file — !cron enable / !cron disable, the removal of a once job, or a schedule migration (ISSUE-330). The text is written to {bot_dir}/scripts/prompts/<job-name>.txt and the job is left pointing at it. This is not tidiness: the rewriter used to re-serialize a multiline prompt as a TOML block, where a single stray backslash made every job in the file fail to load. A prompt_file you set yourself is never touched, and an existing file is only reused when its contents already match.
Command jobs: Run shell commands in a subprocess (via _run_capture, which kills the whole process group on timeout). No brain invocation. Output captured and optionally posted to Talk.
All job types go through the same task queue with retry logic, !stop support, failure tracking, and auto-disable.
Configuration options
| Field | Required | Description |
|---|---|---|
name | yes | Job identifier |
cron | yes | Cron expression (evaluated in user's timezone) |
prompt | for prompt jobs | The prompt to send to Claude |
prompt_file | for prompt_file jobs | Path to prompt file, /Users/<owner>/... |
command | for command jobs | Shell command to execute |
room | no | The room the job runs in, as its canonical token. A room made in web chat has a web-… token, not a Talk one — see "Delivering into a room" below |
target | no | talk, email, ntfy, both, all, or a surface:channel / comma-list descriptor. See "Delivering into a room" below |
enabled | no | false parks a job without deleting it (default true) |
once | no | Auto-delete after successful execution. If you edit the prompt, command or skill while a run is in flight, or turn once off, the job stays. An entry that no longer loads stays in the file for you to fix |
silent_unless_action | no | Suppress output unless response has ACTION: prefix |
skip_log_channel | no | Suppress log channel output for frequent jobs |
model | no | Model override for this job (e.g. "general" for the active brain's current general model) |
effort | no | Effort override: low, medium, high, xhigh, or max |
brain | no | Brain kind this job runs on: claude_code or native. Admin-only, and bounded by [brain] room_selectable. See below |
reach | no | limited (the default if left out), public or full. Says what the job runs as, and asks you for what your operator's setting does not cover. See "Network access" below |
egress | no | The hosts and skills the job needs, such as ["news.example.com", "skill:browse"]. Asks you ahead of the first run and grants nothing. See "Network access" below |
publish_shared_kv | no | On success, publish the result text to the shared KV store as "<namespace>/<key>" (a bare key means the briefing_shared_blocks namespace) |
publish_shared_kv_trusted | no | Mark the published value trusted, so consuming briefings splice it without the untrusted-content wrapper |
The five flags — enabled, once, silent_unless_action, skip_log_channel and publish_shared_kv_trusted — take a bare TOML boolean, true or false. A quoted "false" is a string and a bare 1 is an integer; either one logs a warning and the field takes its default rather than being read for truthiness. enabled = "false" used to leave the job running, and once = "false" used to delete it after one run.
Delivering into a room
A room is one conversation bound to several surfaces, not a Talk conversation. A room made in web chat has a web-… token and may never have been opened in Talk at all, so target = "talk" with that token posts nowhere: the Talk API is handed a token naming no conversation, the job records success, and nobody sees anything. Before ISSUE-509 nothing said so, and the room a web-chat user was sitting in appeared in no listing a task could reach — so a task asked to schedule something "in this room" created a Talk conversation of the same name instead, bound to no room and watched by nobody.
The descriptor comes from the room rather than being written by hand. istota-skill rooms list names every room a user is in, and the model's task prompt already names the one it is in; both hand back a ready-made target:
| The room | target |
|---|---|
| Made in Talk | talk:<talk_token> |
| Made in web chat | web:<token> |
| Web chat, also open in Talk | web:<token>,talk:<talk_token> |
The last one is two legs because the web leg writes the room's own transcript and pushes nothing to Talk, so naming only the web half leaves the room's Talk members with nothing.
Set room to the room's canonical token, never its Talk token. target decides where the result goes; room decides which conversation the job runs in, and it is what makes the result render as a reply in the room rather than as a standalone system note.
[[jobs]]
name = "weekly-digest"
cron = "0 9 * * 1"
prompt = "Summarise this week's activity"
target = "web:web-alice-3f21c4d90ab7"
room = "web-alice-3f21c4d90ab7"
One spelling that does not do what it looks like: bare web is the user's default general room, not the job's room field.
When a web: or room: target names a different room from the job's room field, the loader logs a warning and loads the job anyway. A talk: target is not compared, since a Talk descriptor can be a binding reference rather than the canonical token.
room:<token> is the third form, and it means "this room, whichever surfaces it is on when the job runs" — the bindings are re-read at every delivery rather than baked into the descriptor. The token must be the room's canonical one — the value istota-skill rooms list reports as token, and the same string you put in the job's room field — rather than a per-surface reference such as a promoted room's Talk conversation id. That is what the form is for: a web-only room later opened in Talk starts reaching the room's Talk members with no edit to the job, where web:<token> written months earlier goes on reaching the web leg alone. The surface-qualified forms in the table are still the better default, because they say which surfaces the job was written for, so a room that loses a binding is legible instead of quietly narrowing.
Until ISSUE-511 this form delivered nothing at all from a scheduled job. The expansion assumed the task had originated on one of the room's own surfaces and skipped both of its bindings as legs that origin had already covered; a scheduled task originates on none, so the plan came out empty, the job reported success and the only trace was one line in the daemon log. A deployment running an older release should keep to the surface-qualified forms.
Choosing a brain per job
brain pins one job to one brain kind — a nightly summary on native, a repo-touching job on claude_code — without moving the instance default. It is the same mechanism a chat room's !brain uses, bounded by the same operator allowlist, [brain] room_selectable. That list is empty by default, so nothing here works until an operator names kinds.
Writing the field is admin-only. CRON.md is a file on the mount and is also written by the model through the schedules skill, and a brain kind decides which process holds the agent loop, which credentials it carries and which sandbox profile is built — so it should not be the one enforcement-shaped setting a task can choose for its own next run. A non-admin's brain is dropped at each sync, with a warning, and the rest of the job is kept and runs the configured brain. That gate is the multi-user deployment's, as the one on command jobs already is: an empty admins file makes the sole user an admin, so on the single-user install nothing is dropped and a task writing CRON.md can pin a brain.
The sync answers who may write the field, not what they may write. !cron shows the stored value, so the listing never shows a pin the author was not allowed to write — but an admin's pin is stored whatever it names, and a kind the operator has not allowlisted is refused later, at dispatch. A kind that is not a real brain kind is warned about when the file is read; an unlisted one is warned about when the job fires. Neither fails the job, and neither is visible in the listing: it falls through to whatever the deployment would have run anyway.
A pinned job does not fail over. If the pinned brain is unavailable — a usage limit, a missing binary — the run fails with that brain's own reason instead of being answered by the deployment's backup brain, which for unattended work is the safer of the two. The failure is not silent: the task's retries run out, at 1, 4 and 16 minutes or immediately for an error that cannot be retried, consecutive_failures climbs, the job auto-disables at five and raises a notice in the inbox. !cron enable <name> restarts it once the brain is back.
model is resolved by whichever brain the job will actually run. A portable name like smart therefore lands on that brain's own model rather than on the deployment default's, which is what makes a per-job brain and a per-job model usable together. The loader checks the name in that brain's namespace and logs a warning for one that cannot resolve (usually a typo); the job still loads. An admin's brain pin selects the namespace checked; for anyone else it is the scheduled default brain's.
provider picks which of the native brain's listed providers a native job runs on, [brain.native] providers bounding it as room_selectable bounds brain. It is admin-only for the same reason as brain, and because it decides whose key the job is billed to: a non-admin's is dropped at sync with a warning. An admin's model = "local/qwen3-32b" names the provider too, and is stored as the provider and the model's own id. Unset, the job runs on native's default provider. A provider the operator later drops from the list falls back to the default, with a warning when the job fires. See Models and providers.
Publishing to shared content
publish_shared_kv lets an admin's job write its result where every user's briefings can read it — the escape hatch for shared content the built-in shared-block generator can't produce (it runs tool-less, while a scheduled prompt job gets the full sandbox and tools). Shared-KV writes are admin-only: the job's user must pass the writer check, and an unauthorized or failed publish fails loudly (error log, operator alert, and a job-failure increment that the success path withholds). An empty result is a clean skip, leaving the last-known-good value in place.
Consume the published value with a shared_block source on a briefing block. See briefings.
Network access
A job runs with nobody watching, and a page it reads can tell it to send your data somewhere. So a new job can fetch only hosts you approved, plus services your operator configured. The same holds for an assignment wake. Each job's page under Settings, Scheduled jobs has a Network access card, and that is where you decide.
Two kinds of unattended work have nothing to decide. A personal briefing's model has no tools, because Istota gathers its sources before the model starts. A TASKS.md line always runs limited, with no hosts or skills, because a limited task can write a line into that file. Nothing can be approved for a line, so one that needs the web fails with a refusal in its result.
When a job is refused a host, the bell shows one row for that job. It names no host, and it opens the job's page, whose card lists what was refused with Add and Dismiss. A page the job reads can make it ask for a host, so add one only if you expect the job to use it. Hosts are exact: news.example.com does not cover www.news.example.com.
A job is in one of three states:
- Limited: the hosts and skills you listed, and nothing else. A new job starts here.
- Public: open web and nothing private: no memory, no files, no credentials and no notes in its room. For research that only reads the web. Choose it on the page or set
reach = "public". It needs no approval on a default install. A job that needs to keep state should stay limited and use hosts. - Full access: it runs with your browser profile and every skill, and can reach any public host. Choose it on the page, or set
reach = "full"to ask for it and approve its text there. Every job that existed when this feature arrived starts here. Choose Limited on the page to narrow it, and expect the next run to be refused the hosts it needs.
The card has an Access control with these three states. It writes your choice to the job's reach in CRON.md, because the file is what the job is read from, and CRON.md is rewritten inside its TOML block when it does, so comments in the block go. Choosing Public or Full access shows you the job's text first. If the file cannot be written, or holds an entry that does not load, a wider choice changes nothing and you are told. Limited still takes any approval off, so a job cannot stay on Full access because of a bad file. A task can edit CRON.md too, so this page does not stop a later edit changing reach: what that edit can reach is still bound by the table below.
Where they need approval, Public and Full access are approved against the exact text of the job, which the page shows you. Editing prompt, a prompt_file, command, skill, skill_args, publish_shared_kv or publish_shared_kv_trusted drops the approval, and the job runs limited until you approve the new text. The job's page says what was approved and when, shows what has changed since, names the next run if it would run with less, and has one button to approve the new text at the same level. Changing the schedule, model or delivery does not drop an approval. Host and skill entries stay through an edit.
A job can ask ahead of its first run. egress = ["news.example.com", "skill:browse"] lists what it needs, and the job's page and the bell show the request as soon as the job is written. Nothing is granted until you add it, and a recurring job runs with what it has until then. A once job with an unmet egress, or a reach your operator's setting does not cover, does not fire until you approve, however long that takes, because it would otherwise run limited and delete itself along with the request. Running it by hand is refused for the same reason. Dismissing a request does not release the job: add the entry or remove the job from CRON.md. A once job that asks for nothing still fires limited and is gone afterwards.
A skill: entry names a skill that reaches the network itself, such as browse. A skill that runs on Istota's side, such as feeds or calendar, needs no entry, and naming one is reported as an error and asks for nothing. After Istota edits CRON.md it runs istota-skill schedules check, which reads the file the way the scheduler does and lists every problem, including the skills a skill: entry may name.
A job that needs an internal service can name it as host:port, such as 192.168.1.10:8080, on its page or in egress. It takes effect only if your deployment already allows that endpoint: your operator lists it with "192.168.1.10" = ["egress"] in [private_hosts] or in extra_hosts, or you are an admin and it is the address of a credential you added, where a name must also resolve to a public address. Otherwise the page says the address is not one this deployment allows, and CRON.md reports it as an error and does not ask. An endpoint is for the job's shell commands, not WebFetch. A service on plain HTTP also needs a credential bound to it with HTTP allowed.
Your operator sets how far a job gets with no approval, with [security] scheduled_job_max_unapproved. Past that it runs limited and asks you, and a once job waits.
| Setting | With no approval | Needs your approval |
|---|---|---|
limited | Limited | Public and Full access |
public (default) | Limited, and Public for a job with reach = "public" | Full access |
full | Everything; a job with no reach runs on Full access | Nothing |
Under public, read a public job you did not write. It holds nothing private, but a task can write a job into CRON.md and put what it knows in the job's text. Under full, a task can write a job that then has your browser profile, every skill, any public host and mail that is not held as a draft. A job with reach = "limited" stays limited under every setting.
Renaming a job counts as removing it and adding a new one: the new name starts with nothing.
Disabling a job does not remove what you approved. The page keeps disabled jobs under a closed Disabled jobs group at the bottom, which opens by itself when one of them has a request to answer. A job Istota suspended after repeated failures stays in the main list with a Suspended badge, since a refused host can be what made it fail.
While limited, a job cannot add a feed or a bookmark, change a briefing's sources, a shared block or a group briefing, or push to another ntfy topic. Its mail to anyone but you waits as a draft. An operator can use istota egress list|grant|revoke. What stays open is in Where a task may send bytes.
Failure handling
Jobs auto-disable after 5 consecutive failures (scheduled_job_max_consecutive_failures). Failures reset on success.
A job stopped that way is suspended, which is a different thing from the enabled = false you write in CRON.md. Suspension is recorded in scheduled_jobs.auto_disabled_at, a column the file cannot express and the sync never writes; enabled stays whatever the file says, because the user never asked for the job to stop. A job runs only when it is enabled and not suspended. !cron and the admin dashboard render the two apart — DISABLED for the first, SUSPENDED for the second.
Until this split the sync wrote enabled back from CRON.md on every tick, roughly once a minute, so auto-disable did nothing at all for a job defined in a file and a job that failed every run kept running every run.
Three things lift a suspension:
- a successful run;
!cron enable <name>in Talk, which lifts the suspension, clears the failure count and writesenabled = trueback into CRON.md;- an edit in CRON.md to what the job dispatches —
cron,prompt,command,skillorskill_args. Fixing the thing that was failing is how most people will expect to restart a job, so it counts. Changingtarget,room,model,effort,brainor a flag does not.
brain is outside that set for the same reason model and effort are: the set is what the job dispatches, and a rule a reader can hold is worth more than covering one more plausible repair. A job suspended because its pinned brain was down is restarted by !cron enable after the brain comes back, not by editing the field.
Catch-up suppression after outages
When the daemon returns from a long outage, it does not fire every missed cron instance at once. If a job or briefing's computed next fire time is more than cron_max_staleness_minutes (default 60) behind the current time, the fire is skipped and last_run_at is bumped so the schedule resumes from the next future fire. This prevents a thundering herd of stale tasks from flooding the queue after a restart. A once job that has not run yet is exempt and fires late, since skipping its slot could leave it waiting a year.
Set cron_max_staleness_minutes = 0 in [scheduler] to restore the prior behavior (unconditional catch-up of all missed fires).
Context isolation
Scheduled job results are excluded from interactive conversation context. This prevents cron output from cluttering a user's chat history.
Reminders
Natural-language reminders are implemented as one-shot cron entries (once = true). When a user asks "remind me to do X tomorrow at 9am", the bot creates a CRON.md entry that fires once and auto-deletes.
Managing jobs
Settings, Scheduled jobs lists your jobs with each one's schedule, state, access, last run and failures in a row. New job adds one, and opening a job shows its form, its last error and its Network access card. Saving writes CRON.md, and the job shows as waiting for the next sync until the daemon reads it, within about a minute. From the list or the job's page you can run a job now, disable or enable it, and delete it, which takes it out of CRON.md too. Enabling a job Istota suspended after repeated failures starts it again.
The form covers what CRON.md authors, for whoever may set it. Model and run holds the model and effort, with a brain and provider for an admin. Publish holds the shared target and trust, for someone who may publish. Asks ahead of its first run holds the egress entries. A model or brain you may no longer pick stays as the file has it until you change or remove it, and the form says the job does not use it.
If you change what a job dispatches or where it publishes and it holds an approval, the page asks whether to keep that access for the new text or save and run limited. Renaming a job starts its network access over, since a new name is a new job, and the page says so first. While CRON.md has a job that does not load, every job is read only, because a rewrite would drop the one that failed.
Some rows have fewer actions:
- A job you just added to CRON.md reads "Waiting for the next sync" until the daemon has read the file, about a minute.
- If CRON.md holds an entry that does not load, the page says so and links to the file. Jobs are read only until it is fixed, because a rewrite would drop the entry that did not load. Delete is refused for the same reason. Enable and Disable change only the running job, and warn you that the next sync will undo them.
- A
commandjob you are not allowed to run is dropped by the sync, so it stays in the file and never gets a row. The page shows why and links to CRON.md, which is where to fix it. - A module's own job appears only when it was refused something, and can only be opened.
In Talk, use !cron to list, enable, or disable scheduled jobs:
!cron # List all jobs with status
!cron enable NAME # Re-enable a disabled job, or lift a suspension
!cron disable NAME # Disable a job