> For the complete documentation index, see [llms.txt](https://docs.talus.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talus.network/faq/07-scheduler.md). # Scheduling {% hint style="info" %} **Audience:** Nexus adopters and integrators. **Goal:** Answer when Tasks and Occurrences run, pause, settle, or fail so you can schedule durable work with the right controller and reserve. {% endhint %} ### Task, occurrence, and Execution #### What is the difference between a Task, an occurrence, and an Execution? A `Task` owns reusable operation/input metadata, reserve funding, controller authority, and one Schedule. An `Occurrence` is one permanent scheduling opportunity under that Task. Dispatch creates an `Execution`, which records runtime walks, results, failures, and payment locks. Return to the occurrence for settlement and refund accounting. **How do I run work immediately?** Immediate work is a Task occurrence whose start time is the current Sui Clock: ```bash nexus task schedule \ --dag-id \ --input-json '{ ... }' \ --prepay-amount-mist \ --occurrence-budget-mist \ --now ``` For a registered Agent skill, replace `--dag-id` with `--agent-id --skill-id `. Add `--agent-funded` when the Agent vault should fund and control the Task. **How do I schedule delayed or recurring work?** Use `nexus task schedule` for atomic creation plus a complete schedule, or create an empty Task and compose it with the nested commands: ```bash nexus task create --dag-id --input-json '{ ... }' --prepay-amount-mist --occurrence-budget-mist nexus task occurrence add --task-id --after-ms 30000 --deadline-after-ms 60000 --priority-fee-percentage 20 nexus task recurrence set --task-id --after-ms 3600000 --interval-ms 3600000 --occurrences 24 --priority-fee-percentage 20 ``` The retired `nexus scheduler` and `nexus tap schedule-task` command families do not exist in the pinned CLI. **What recurrence shapes exist?** A Schedule contains standalone occurrences and at most one recurrence. The recurrence has a first occurrence, interval, optional maximum count, optional dispatch deadline, priority-fee percentage, and no-overlap policy enforced by Task state. Clear future recurring work with `nexus task recurrence clear`. **How does priority work?** Each occurrence stores `priority_fee_percentage`. Eligible work is ordered using that percentage, and settlement calculates priority compensation from payable leader gas. The scheduler has no per-gas-unit field or default-zero mode. **Who can mutate a Task?** Address-controlled operations require the active signer to match the immutable controller. Agent-controlled operations supply and verify the controlling Agent. A `TaskPointer` is owned discovery metadata used by `nexus task list`; owning or transferring it does not grant mutation authority. **How do I observe and recover work?** ```bash nexus task inspect --task-id nexus task occurrence list --task-id nexus task occurrence inspect --task-id --occurrence-id --follow nexus execution inspect --task-id --occurrence-id nexus task occurrence cost --task-id --occurrence-id ``` > **Timeout boundary:** Check the installed command’s `--help` before using any timeout or abort action. The timeout/refund path must identify the exact `invocation_id`; a ToolCashier ID, FQN, or historical cashier-assisted flag is not a safe substitute. An Invocation refund or Execution abort does not necessarily settle its owning Occurrence. * Settle a finished runtime with `nexus task occurrence settle`. * Record an advertised occurrence as missed after its deadline with `nexus task occurrence expire`. * Abort runtime after its workflow timeout with `nexus task occurrence abort-expired` only when the selected build’s `--help` exposes the supported arguments and exact object identity. * Pause or resume future dispatch with `nexus task pause` and `nexus task resume`. * Refill reserve with `nexus task refill`, cancel future work with `nexus task cancel`, and close only after no advertised, pending, or in-flight occurrences remain. When timeout/refund leaves the Occurrence unsettled, use the selected build’s supported occurrence-settlement action, then re-read `Settled` and prove zero pending/in-flight work before closing. #### Where do I go next? * [Payments](/faq/04-payments.md) — reserve custody and refunds. * [Authorization](/faq/05-authorization.md) — Agent and vertex authorization. * [DAG and Execution](/concepts/05-workflow-dag-execution.md) — the Leader dispatch role and execution transitions. * [Schedule an asset-management flow](/guides/agent-usage/schedule-asset-management-flow.md) — the recurring-Task walkthrough. * [`nexus task`](/reference/cli/task.md) and [`nexus execution`](/reference/cli/execution.md) — exact flags and output. * [`scheduler`](/reference/move/nexus_scheduler/scheduler.md) and [`task`](/reference/move/nexus_scheduler/task.md) — Move lifecycle. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.talus.network/faq/07-scheduler.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.