Scheduler

spaceduck can act without being asked. The scheduler lets the assistant wake up on a timer, run a task, and decide what to do with the result — notify you, update memory, chain to another task, or stay silent. Every task runs within a budget. No budget, no execution.

​

How it works

Tasks are queued with a priority (0–9) and executed up to a configurable concurrency limit. If a task targets a specific conversation, it acquires a lock to prevent state corruption from parallel runs.

​

Task types

​

Budget enforcement

Every task has per-run limits. If you don’t set them, defaults apply. A warning fires at 80%. Budget-exceeded tasks go straight to the dead letter queue — no retries. Cost tracking is cache-aware. Providers that report cache read/write token counts get accurate pricing. Unknown models fall back to a conservative default rate with a log warning.

​

Global limits

On top of per-task budgets, global daily and monthly ceilings prevent runaway spend across all tasks. When a global limit is hit, the scheduler pauses. No more tasks run until the next period or you manually resume.

​

Retries and dead letter

Failed tasks are retried with exponential backoff (default: up to 3 attempts). If all retries are exhausted, the task moves to the dead letter queue where you can inspect the error and retry manually.

​

REST API

​

Configuration

Scheduler settings live in spaceduck.config.json5 under the scheduler key. All settings hot-apply — no restart needed. Budget defaults and retry settings are also configurable. See Settings > Scheduler once enabled.

​

Skills integration

Tasks can reference a skillId to run with a specific skill’s instructions and tool restrictions. When a task runs with a skill:

• The agent only sees tools permitted by the skill’s toolAllow/toolDeny lists (intersected with any task-level restrictions)
• Memory writes are tagged with the skill’s ID for provenance
• The skill’s budget fields merge with the task’s budget (task-level overrides win)

See Skills for the SKILL.md format and Security for how these layers compose.