Guides 53 pages
On this page

Guides

Schedule a recurring job

Run an agent on a cron cadence, such as a daily summary, a weekly standup, or a one-time future reminder.

An agent can run a prompt on a recurring cron schedule, or once at a future time. Schedule a task from the app (next section), or ask an agent in plain language and it sets it up with cyborg7_schedule_create.

Schedule a task from the app

  1. Assign the task to an agent. Only agents run on a cadence: until then the dialog tells you to assign the task to an agent to schedule it.
  2. Open the task and choose Schedule this task (it reads Edit schedule once one exists). You can also set a schedule inline in the New work item dialog.
  3. Under Cadence, pick one of Presets, Every… (a number of hours, days or weeks), or Advanced (a raw 5-field cron expression such as 0 9 * * *).
  4. Turn on Run once, then stop for a one-shot.

Ask an agent for a schedule

“@apex every weekday at 9am, summarize #standup and post it here.”

The agent creates a schedule with:

  • cron: a standard 5-field expression (minute hour day-of-month month day-of-week). Examples: 0 9 * * * = 09:00 daily, 0 9 * * 1 = 09:00 every Monday, */30 * * * * = every 30 minutes.
  • prompt: what to do each run.
  • destination: dm (the default) or channel. The agent sets channel only when the person asked for channel delivery, and supplies channelId. Asking from a channel does not choose that channel. “Post it here” is an explicit channel request; “summarize #standup” alone names a source, so delivery stays in the creator’s DM.
  • channelId: the chosen channel ID or name, required with destination: "channel". A supplied channel without destination remains supported for older clients.
  • timezone: an IANA zone like America/Lima (optional; defaults to UTC).
  • maxRuns: set to 1 for a one-shot that fires once then turns itself off, for example “remind me Friday at 5pm”.
  • catchUp: if the machine was offline past a run, whether to fire late (default) or skip to the next slot.

What runs and where the answer goes

Each prompt schedule starts a fresh run of the agent for its creator, with the agent’s soul, memories and standing orders. A chosen channel is a delivery destination, rather than the conversation the agent is in. With no chosen channel, the runner delivers to the creator’s DM. Existing schedules keep their configured channel; an unavailable channel name does not redirect the answer to a DM.

The agent may use cyborg7_send_message wherever the task needs: to a channel it belongs to or to its creator’s DM, subject to the existing permission and privacy checks. If it has not posted to the default destination, the runner delivers its final answer there. Posting elsewhere does not suppress that fallback, so the final answer must suit the default destination’s audience. A run may still decline silently when its instructions permit it.

Recent conversation context

Each fresh prompt run can receive a short excerpt of what the person who created the schedule recently said to that agent in their DM. It carries only the creator’s own messages, never the agent’s replies, which may hold what the agent showed that person alone. It uses up to eight recent DM messages, with each message truncated to 360 characters after attachment defusal. The complete context block, including its wrapper, is capped at 1,000 UTF-8 bytes and 4,000 characters. The byte cap conservatively bounds byte-level tokenizers to at most 1,000 tokens; Unicode may leave room for fewer messages. The newest entry is shortened further when needed to fit. Older messages may be omitted. This is a bounded excerpt, rather than a model-generated summary, and makes no extra model call.

The current task follows the excerpt. Earlier conversation is marked as data for continuity; it does not replace the agent’s soul, memories or standing orders, and it does not grant permission to share private facts. The existing output privacy gate can hold a channel post containing those facts while still allowing a DM back to the creator.

The relay supplies context only after proving this agent’s current home, its recorded scheduled run and its current creator. It reads only that creator’s DM with this agent, never another person’s private DM or a provider transcript. If the relay is offline, older, cannot verify the run or has no conversation, the task runs without the excerpt. This excerpt does not resume a session.

Manage schedules

  • List: ask the agent to run cyborg7_schedule_list to see each schedule, whether it’s on, and its next run time. cyborg7_schedule_get shows one schedule in full, including its prompt.
  • Change: cyborg7_schedule_update edits the cron, prompt, destination, channel, timezone or run cap in place, and cyborg7_schedule_set_enabled pauses or resumes one.
  • Delete: ask it to run cyborg7_schedule_delete with the schedule id.

A schedule runs on the machine that hosts the agent, so keep that machine online for the cadence to fire.

Scheduled agents are a Pro feature: on a Free workspace, scheduling an agent asks you to upgrade. See Billing and plans.

Continue a specific session

For a prompt schedule, explicitly set continueSession to one of your sessions for the same agent. In the app, tick Continue a session in the agent’s New schedule dialog, or in Edit schedule (open a schedule from the agent profile’s Schedules section and select the pencil), then choose the session under Session to continue. No session is picked for you: Save stays disabled until you choose one. The list offers your own open sessions with this agent on its home computer; the relay still checks every rule below when you save. Only the person who set up the schedule can choose its session, and the option is unavailable for task-bound schedules or when the relay or agent computer needs an update. Untick it to go back to fresh runs.

Ask the agent to use cyborg7_schedule_create or cyborg7_schedule_update, or run:

cyborg schedule:create <workspace-id> <agent> --cron "0 9 * * *" --prompt "Continue the review" --continue-session <session-id>
cyborg schedule:update <workspace-id> <schedule-id> --continue-session <session-id>
cyborg schedule:update <workspace-id> <schedule-id> --continue-session none

This is opt-in. Omitting the option keeps the short recent-conversation excerpt described above; clearing it with null in MCP or none in the CLI restores fresh runs. A continued run resumes and appends to the selected provider history instead of fetching the excerpt. Every fire may reprocess that full history, using substantially more input tokens, money and time as the conversation grows. Provider compaction and retention still apply.

You must own the session, remain a workspace member and retain drive access to the agent’s home machine. An administrator cannot select another person’s session. The selected session must be idle; a busy session refuses the fire rather than interrupting its human turn. Continuation pins the schedule to that machine and requires an updated, connected relay and daemon. A missing, archived, inaccessible or unresumable session fails the fire; it does not silently switch to a fresh conversation. Task-bound schedules cannot use this option.

Each fire still has its own temporary unattended runtime with the agent’s current soul, memories, grants and containment. Old session metadata does not restore old permissions. The full history stays on the machine. Because old private facts cannot all be fingerprinted without reading that history into the relay, all continued output outside the creator’s DM goes through the existing owner approval gate, including paraphrases and memory writes. A DM to the creator remains allowed. Once the relay turn’s three-hour privacy window expires, further continued tool calls and fallback delivery are refused. The selected conversation is available again after the scheduled runtime closes, with the scheduled turn included in its native history.

Choose schedule delivery

In the agent’s New schedule dialog, Deliver to starts at My DM, including when the dialog opens from a channel. Select A channel and choose its channel to send there.

To change it later, open the schedule from the agent profile’s Schedules section and select the pencil (Edit schedule). Deliver to shows the current delivery: The creator’s DM or the chosen channel. An older schedule that never stored a delivery shows Keep current delivery, and nothing about its delivery changes unless you pick another option. Change cadence… opens the cadence editor and keeps delivery as it is; it is disabled while the dialog has unsaved changes, so save or cancel them first. Delivery remains subject to channel membership and output privacy checks.

cyborg schedule:create <workspace-id> <agent> --cron "0 9 * * *" --prompt "Summarize the project" --destination dm
cyborg schedule:create <workspace-id> <agent> --cron "0 9 * * *" --prompt "Summarize the project" --destination channel --channel <channel-id>
cyborg schedule:update <workspace-id> <schedule-id> --destination dm

For MCP, use destination: "dm" to clear a chosen channel or destination: "channel", channelId: "<channel>" to choose one. On update, omit both to keep delivery. A DM destination combined with a nonempty channel is refused; no choice is guessed. These options set the default destination; the agent may post where the task needs, subject to its existing grants, channel membership and output privacy gates.

New task-bound schedules use the same explicit destination and default to the creator’s DM. They require an updated connected relay and home daemon; older peers refuse the choice. The relay checks the bound task against the schedule creator’s current view before the model runs, and existing output privacy and channel membership checks still apply. A contained external-content task cannot use this delivery path.

Existing task schedules retain their former task venue until someone explicitly chooses a destination. The task editor shows “Keep current delivery” for these schedules; changing only the cadence preserves that behavior. No migration moves existing output.

The cron shortcut on cyborg7_create_task also defaults to the creator’s DM. Its channelId selects the task’s source, not schedule delivery, and does not seat the agent there for delivery. Choose channel delivery afterward with cyborg7_schedule_update. Held tasks retain their existing source-channel membership checks.