Task Scheduler

Tasks lets you schedule an agent to run automatically, on a timer, instead of you kicking it off by hand every time. Set it up once ("check for outdated dependencies every Monday at 10am") and DorkOS handles the rest, even after you close your laptop.

Tasks is on by default. Open the Tasks tab in the sidebar and you're ready to create your first schedule.

Create your first schedule

Will it actually run?

Short answer: yes, once it's live in a real DorkOS install. Schedules always show up and you can always edit them, but a schedule only actually fires (starts an agent session) in a real production install of DorkOS, the one you get from the normal install, not a developer preview build. That's a deliberate safety rail: a scheduled job can edit files and run commands on its own, so DorkOS won't let a test or development build fire one by accident.

If you're following this guide in a normal DorkOS install, you're already in the environment where schedules fire. Nothing extra to do.

Get a message when a task finishes

DorkOS can message you the moment a scheduled task wraps up, so you do not have to sit and watch it. The message names the task, how long it took, and the first line of what it produced. This works on its own. The agent does not have to do anything.

To turn it on:

1. Open the agent, go to Channels, and connect a channel like Telegram.
2. Bind the channel and open its Advanced settings.
3. Turn on Message me when tasks finish.
4. Turn on Agent can start conversations. This is the real switch. Nothing gets sent until you allow the agent to reach you.

Failures always reach you. Successful runs reach you only while the switch is on, so you can mute the routine "all good" pings and still hear about breaks.

Cancelled runs never send a message, since you cancelled them yourself. Tasks that are not linked to an agent do not send a message yet.

Enabling or disabling Tasks

Tasks ships on by default, so most people never need to touch this. If someone turned it off, or you want to force it on or off for a specific run:

dorkos --tasks

dorkos --no-tasks

You can also set DORKOS_TASKS_ENABLED=true (or false) as an environment variable; it takes the same effect as the flag. Whichever you set last wins.

Reference

The rest of this page is for people who want the API, the exact data model, or the implementation details. If you just wanted to schedule an agent, you're done, go create something.

REST API

Create a schedule:

curl -X POST http://localhost:4242/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "name": "weekly-dependency-check",
    "description": "Check for outdated npm dependencies",
    "prompt": "Check for outdated npm dependencies and create a summary of what needs updating.",
    "target": "global",
    "cron": "0 9 * * 1",
    "timezone": "America/New_York"
  }'

target is either an agent id (the schedule runs in that agent's project directory) or the literal string "global" (runs in the server's default working directory). description and prompt are required; cron, timezone, maxRuntime, and permissionMode are optional.

Pause or resume a schedule:

curl -X PATCH http://localhost:4242/api/tasks/{id} \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Trigger a schedule outside its cron timing:

curl -X POST http://localhost:4242/api/tasks/{id}/trigger

Cancel an active run:

curl -X POST http://localhost:4242/api/tasks/runs/{runId}/cancel

List available templates:

curl http://localhost:4242/api/tasks/templates

MCP Tools

Agents can create schedules for themselves using the tasks_create MCP tool.

tasks_create({
  name: "nightly-test-suite",
  description: "Run the full test suite overnight",
  prompt: "Run the full test suite and report any failures.",
  target: "global",
  cron: "0 2 * * *"
})

Cron Syntax

Tasks uses standard five-field cron expressions:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *

Run States

Click any run in the history to open the full agent conversation, every tool call, response, and output the agent produced during that run.

Tasks enforces a configurable concurrency cap on simultaneous runs (1 by default, configurable up to 10 in Settings). If the cap is reached, new triggers are skipped with a warning log. Overrun protection (via croner's protect option) stops a schedule from starting a new run while its previous run is still active.

Schedule States

Tasks + Relay

When both Tasks and Relay are enabled, a scheduled run gets dispatched as a Relay message (relay.system.tasks.{scheduleId}) instead of calling the agent runtime directly. Multi-agent coordination through Relay is shipped but still working toward full end-to-end verification, so treat this integration as functional, not battle-tested. In practice it means:

• Each scheduled run gets a Relay trace ID, so you can follow the delivery path from trigger to agent execution.
• Scheduled runs share Relay's delivery machinery (retries, backpressure handling, a dead-letter queue for messages that can't be delivered) with every other message on the bus.

Storage

Schedule definitions and run history live in SQLite at ~/.dork/dork.db, using WAL mode so reads and writes don't block each other.

Two guarantees hold even if more than one DorkOS server points at the same ~/.dork:

• Single firer. Only one process fires schedules at a time; others display schedules but stay quiet. If the firing process exits, another takes over within seconds.
• Fire-once. A given scheduled occurrence dispatches at most once, even across processes, so a shared data directory can never double-run a job. Manual "trigger" calls are exempt and always run.

Next Steps