Scheduling (Cron Jobs)

Moltis includes a built-in cron system that lets the agent schedule and manage recurring tasks. Jobs can fire agent turns, send system events, or trigger other actions on a flexible schedule.

Heartbeat

The heartbeat is a special system cron job (__heartbeat__) that runs periodically (default: every 30 minutes). It gives the agent an opportunity to check reminders, run deferred tasks, and react to events that occurred while the user was away.

The heartbeat prompt is assembled from HEARTBEAT.md in the workspace data directory. If the file is empty and no pending events exist, the heartbeat turn is skipped to save tokens.

Heartbeat replies can also be delivered to a configured channel destination via [heartbeat] deliver, channel, and to in moltis.toml, or from the web UI under Settings -> Heartbeat.

Event-Driven Heartbeat Wake

Normally the heartbeat fires on its regular schedule. The wake system lets other parts of Moltis trigger an immediate heartbeat when something noteworthy happens, so the agent can react in near real-time.

Wake Mode

Every cron job has a wakeMode field that controls whether it triggers an immediate heartbeat after execution:

Set wakeMode when creating or updating a job through the cron tool:

{
  "action": "add",
  "job": {
    "name": "check-deploy",
    "schedule": { "kind": "every", "every_ms": 300000 },
    "payload": { "kind": "agentTurn", "message": "Check deploy status" },
    "wakeMode": "now"
  }
}

Aliases are accepted: "immediate", "immediately" map to "now"; "next", "default", "next_heartbeat", "next-heartbeat" map to "nextHeartbeat".

System Events Queue

Moltis maintains an in-memory bounded queue of system events — short text summaries of things that happened (command completions, cron triggers, etc.). When the heartbeat fires, any pending events are drained from the queue and prepended to the heartbeat prompt so the agent sees what occurred.

The queue holds up to 20 events. Consecutive duplicate events are deduplicated. Events that arrive after the buffer is full are silently dropped (oldest events are preserved).

Exec Completion Events

When a background command finishes (via the exec tool), Moltis automatically enqueues a summary event with the command name, exit code, and a short preview of stdout/stderr. If the heartbeat is idle, it is woken immediately so the agent can react to the result.

Exec-triggered wakes have a cooldown guard so a heartbeat turn that runs exec does not immediately re-wake itself in a loop. Configure it with [heartbeat].wake_cooldown in moltis.toml:

[heartbeat]
wake_cooldown = "5m" # default; set "0" to disable

The value uses Moltis duration syntax such as "30s", "10m", or "1h". The cooldown applies only to exec-completion wakes. Cron jobs with wakeMode = "now" still wake the heartbeat immediately.

This means the agent learns about completed background tasks without polling — a long-running build or deployment that finishes while the user is away will surface in the next heartbeat turn.

Schedule Types

Jobs support several schedule kinds:

Prefer named weekdays such as MON-FRI in cron expressions. Numeric weekday values are not portable across cron implementations because some number Sunday as zero while others number it as one.

Cron Tool

The agent manages jobs through the built-in cron tool. Available actions:

• add — Create a new job
• list — List all jobs
• run — Trigger a job immediately
• update — Patch an existing job (name, schedule, enabled, wakeMode, etc.)
• remove — Delete a job
• runs — View recent execution history for a job

One-Shot Jobs

Set deleteAfterRun: true to automatically remove a job after its first execution. Combined with the at schedule, this is useful for deferred one-time tasks (reminders, follow-ups).

Channel Delivery

Background agent turns can deliver their final output to a configured channel account/chat after the run completes.

When asking the agent from WhatsApp, Telegram, or another messaging channel to send a scheduled result back to the same conversation, the agent can use the transient tool shortcut:

{
  "payload": {
    "message": "Prepare and send the daily summary.",
    "deliver_to_current_chat": true
  }
}

Moltis resolves the account and destination from trusted session context, converts the payload to an isolated agentTurn, and stores the normal deliver, channel, and to fields. The shortcut itself is not persisted. It returns an error outside a messaging-channel conversation.

For a different or explicitly selected destination, use all of the following:

• sessionTarget: "isolated"
• payload.kind: "agentTurn"
• payload.deliver: true
• payload.channel: "<account_id>"
• payload.to: "<chat_or_peer_id>"

Example:

{
  "action": "add",
  "job": {
    "name": "daily summary",
    "schedule": { "kind": "cron", "expr": "0 9 * * *", "tz": "Europe/Paris" },
    "sessionTarget": "isolated",
    "payload": {
      "kind": "agentTurn",
      "message": "Summarize yesterday's activity and send it to Telegram.",
      "deliver": true,
      "channel": "my-telegram-bot",
      "to": "123456789"
    }
  }
}

Channel delivery is separate from session targeting. The cron job still runs in an isolated cron session, then Moltis forwards the finished output to the requested channel destination. After a successful send, Moltis also adds the delivered text to that destination’s existing bound conversation. A follow-up in the same chat (and, where supported, the same topic) can therefore refer to the scheduled message naturally. No additional configuration is required.

Moltis only updates history when the channel account and exact destination map to an existing bound conversation. Delivery to a new or unbound destination still succeeds, but does not create a conversation implicitly. Delivery failures and empty non-heartbeat outputs are recorded as failed cron runs and are never added to conversation history. The run action returns that run record with the completed output, token usage, and session key intact so callers can distinguish agent execution from successful delivery.

Existing jobs with deliver: true but without both channel and to are recorded as failed runs. Earlier versions silently skipped delivery for these incomplete destinations.

Session Targeting

Each job specifies where its agent turn runs:

Security

See Cron Job Security for rate limiting, sandbox isolation, and job notification details.

Metrics