Agent Scheduling

Crewship includes a built-in scheduler that triggers agent runs on a cron schedule. Scheduled runs are fully autonomous — the agent receives a prompt, executes inside its crew container, and the result is recorded as a run with the SCHEDULED trigger type.

How It Works

The scheduler is a background goroutine that manages a pool of cron jobs, one per enabled agent schedule. On startup it loads all agents with schedule_enabled = 1 from the database and registers their cron expressions. Each tick of a cron job triggers a full agent run cycle.

Scheduler goroutine
    |
    v
cron library fires at scheduled time
    |
    v
triggerAgent(agent)
    |
    +--> Create chat session (deterministic ID)
    +--> Resolve chat (credentials, system prompt, skills)
    +--> Ensure crew container is running
    +--> Create run record (trigger: SCHEDULED)
    +--> Execute agent via orchestrator.RunAgent
    +--> Update run record (COMPLETED or FAILED)
    +--> Update schedule_last_run and schedule_next_run

Enabling a Schedule

Schedules attach to a saved routine (pipeline) and fire it on a cron expression. Manage them via crewship routine schedules:

Subcommand	Purpose
`list [--slug <routine>]`	List schedules in this workspace, optionally filtered by target routine. Shows a MISSED column when a schedule’s most recent tick dropped or collapsed overdue occurrences (see `--catchup` below).
`create --slug <routine> (--cron '<expr>' \| --when '<phrase>') [--name ...] [--timezone <IANA>] [--inputs <json>] [--enabled=false] [--catchup skip\|once\|all]`	Create a schedule. `--slug` and one of `--cron`/`--when` are required; defaults to UTC, enabled, `--catchup once`. `--when` accepts a small set of natural-language phrases (`"every weekday at 9"`, `"every day at 9am"`, `"every monday at 14:00"`, `"every hour"`, `"every 15 minutes"`) — it’s parsed to a cron expression, previewed with its next 3 fire times, and confirmed before saving (`--yes` skips the prompt).
`update <id> [--cron ...] [--timezone ...] [--name ...] [--enabled / --enabled=false] [--inputs <json>] [--catchup skip\|once\|all]`	Patch one or more fields.
`enable <id>`	Enable a paused schedule (fires on next 30 s tick).
`disable <id>`	Pause a schedule without deleting it.
`now <id>`	Force-fire out of cycle (useful for smoke tests).
`delete <id> [--yes]`	Permanently delete; prompts for confirmation unless `--yes`.

crewship routine schedules create --slug summarize-text \
  --name "daily-summary" --cron "0 9 * * *" --inputs '{"text":"..."}'
crewship routine schedules list --slug summarize-text
crewship routine schedules now <schedule_id>

The same operations are also available on the REST API under /api/v1/workspaces/{ws}/pipeline-schedules — the CLI is a thin wrapper around those endpoints, so server-side behavior (cron parsing, 30 s tick resolution, timezone handling) is identical.

Pinning a schedule to a routine version

By default a schedule fires the routine’s head (latest) version — an edit to the routine immediately changes what the next tick runs. For production schedules that must not drift when an agent (or teammate) edits the routine, pin the schedule to an immutable version:

crewship routine versions daily-digest          # see the version history
crewship routine schedules create --slug daily-digest \
  --cron "0 8 * * *" --pin-version 3            # every fire executes v3
crewship routine schedules update <schedule_id> --pin-version 4   # re-pin
crewship routine schedules update <schedule_id> --unpin           # track head again

Pinning semantics:

A pinned schedule executes exactly the pinned version’s definition on every fire, no matter how far head has moved. The run record stores the executed version (pipeline_version) and that version’s definition_hash, so the Runs view always shows what actually ran.
The pin survives unrelated updates: patching the cron, timezone, name, inputs, or enabled state keeps the existing pin. Only an explicit --pin-version N / --unpin (API: target_pipeline_version: N / : null) changes it.
If the pinned version no longer exists, the fire fails with a legible error and raises the standard scheduled-run-failed inbox alert (MANAGER-targeted). It deliberately does not fall back to head — silently running an unexpected definition is the exact hazard pinning exists to prevent. Fix by re-pinning to an existing version or unpinning.
Governance still reads the live routine: a disabled or proposed routine refuses to fire even when pinned, and per-step operator overrides apply on top of the pinned definition just as they do on head.
A pinned run that parks on an approval gate resumes against the same pinned version, even if head moved while it waited.
Webhooks support the identical pin (target_pipeline_version on the webhook; crewship routine webhooks create --pin-version N). A webhook whose pinned version is missing answers 409 instead of dispatching.

The schedules list shows the pin in the ROUTINE column as slug@vN.

Fire outcomes (`last_status`)

Each fire records one of:

Status	Meaning
`COMPLETED`	The run finished successfully.
`FAILED`	The run errored (or the pinned version was missing). A `failed_run` inbox alert is raised for MANAGERs.
`SKIPPED`	The target routine is not active (`proposed` / `disabled`); the tick advanced quietly.
`WAITING`	The run parked on a human approval gate (`wait` step). This is a healthy, non-terminal outcome — the run resumes when the approval lands. No failure alert is raised; the waitpoint itself creates the approval inbox card.

Per-agent schedule_cron fields described elsewhere in this guide are a separate legacy path. New work should go through crewship routine schedules against a saved routine.For a quick single-agent cron, the per-agent path is now settable straight from the CLI (previously API-only):

crewship agent update <agent> --schedule-cron '*/5 * * * *' \
  --schedule-prompt "check the queue" --schedule-enabled

Read it back with crewship agent get <agent> — when a cron is set the detail view surfaces a Schedule row (cron (enabled|disabled)), the Schedule Prompt, and the resolved Next Run / Last Run, so you can confirm the cron is live without hitting the raw API. Clear it with --schedule-cron '' (or pause with --schedule-enabled=false).Runs that the scheduler dispatches this way get the tighter routine turn cap automatically — the internal orchestrator.RoutineMaxTurns (20), applied to scheduled dispatches (not a CLI flag you pass).

Cron Expression Format

The scheduler uses standard 5-field cron expressions:

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

Examples:

Expression	Schedule
`0 9 * * 1-5`	Every weekday at 9:00 AM
`/15 * * *`	Every 15 minutes
`0 0 * * *`	Daily at midnight
`30 8 1 * *`	8:30 AM on the 1st of every month
`0 /2 * *`	Every 2 hours

Invalid cron expressions are rejected at registration time. The API call will return an error if the expression cannot be parsed.

Execution Flow

Each scheduled trigger follows this sequence:

Chat Session Creation

A new chat session is created with a deterministic ID (format: sched_{unixnano}_{random_hex}). The chat title is set to "Scheduled: {agent_name}".

Chat Resolution

The ResolveChat call loads the full agent context: credentials, system prompt, skills, MCP servers, network policy, and crew membership. This ensures the scheduled run has the same capabilities as an interactive run.

Container Management

If a container provider is configured, the scheduler ensures the crew container is running before execution. Default resource limits:

Resource	Default
Memory	4096 MB
CPUs	2.0

Run Record

A run record is created with trigger type SCHEDULED before execution begins. Metadata includes the CLI adapter, crew info, and a scheduled tag.

Agent Execution

The agent runs through orchestrator.RunAgent with the same pipeline as interactive runs: sidecar proxy, credential injection, memory, and conversation history.

Result Recording

After execution completes, the run record is updated with:

Status: COMPLETED or FAILED
Duration in milliseconds
Cost and usage metadata (if available from the LLM provider)

The assistant response is persisted to the conversation store and the message count is incremented.

At-most-once firing

Each scheduled occurrence fires at most once. Before any side effect (chat, container, run record), the scheduler reserves the occurrence in a shared idempotency table using a deterministic key derived from the agent id and the occurrence’s minute bucket. A duplicate tick within the same minute — or a process restart that happens after a run started but before the schedule’s next_run was advanced — resolves to the existing reservation and is skipped rather than run a second time. The next occurrence falls in a distinct minute bucket, gets a fresh key, and fires normally. This is at-most-once, not exactly-once: the key is reserved before the run executes, so a crash between the reservation and execution drops that occurrence (it is not retried) rather than running it twice. If the idempotency store is unreachable the fire fails closed — the occurrence is skipped, never double-run. Duplicate protection is the guarantee; delivery is best-effort. The agent scheduler, the routine (pipeline) scheduler, its wake-check probe, and deferred (pending) runs all share one dedup discipline — the same pipeline_run_idempotency table and the ScheduledFireIdempotencyKey helper — so every firing path is at-most-once.

This is single-instance protection. Running multiple replicas would still double-fire (each replica runs its own in-memory cron); true multi-replica exactly-once needs leader election, tracked separately.

Missed-run catch-up (routine schedules)

At-most-once firing says a re-fire of the SAME occurrence never runs twice. It doesn’t say what happens when a routine (pipeline) schedule fell behind by more than one occurrence — downtime, a long disable/re-enable gap, etc. That is catchup_policy on crewship routine schedules create/update --catchup: skip drops the whole backlog, once (default, unchanged pre-existing behaviour) fires exactly once for it, all fires once per missed occurrence (capped at 20 fires/tick). See Missed-run catch-up in the Routines guide for the full semantics and the inbox notice it raises.

Timeout

Each scheduled run has a 45-minute timeout. If the agent does not complete within this window, the context is cancelled and the run is marked as failed.

ctx, cancel := context.WithTimeout(s.ctx, 45*time.Minute)

This is separate from the per-agent timeout_secs setting, which controls the LLM execution timeout within the container. The 45-minute limit is the outer boundary for the entire scheduled run cycle including container startup and chat resolution.

Monitoring

Timestamp Fields

The scheduler maintains two fields on each agent:

Field	Updated	Description
`schedule_last_run`	After each run	ISO 8601 timestamp of the last completed run
`schedule_next_run`	After each run and on schedule update	ISO 8601 timestamp of the next scheduled run

These fields are updated even on error — schedule_next_run always reflects the next trigger time so monitoring dashboards stay accurate.

Run Records

Scheduled runs appear in the standard agent runs list with trigger = "SCHEDULED":

# List scheduled runs for an agent
curl http://localhost:8080/api/v1/agents/{id}/runs?trigger=SCHEDULED

Each run record contains:

trigger: "SCHEDULED"
tags: ["scheduled", "{cli_adapter}"]
duration_ms: execution time
total_cost_usd: LLM cost (if reported)
num_turns: conversation turns
status: COMPLETED or FAILED

Dynamic Updates

When an agent’s schedule is modified via the API, the scheduler hot-reloads the cron entry without restart. The UpdateSchedule method:

Removes the old cron entry (if any)
Registers the new cron expression
Immediately calculates and persists the next run time

Disabling a schedule (schedule_enabled: false) removes the cron entry and stops future triggers. The schedule_last_run timestamp is preserved for audit purposes.

Error Handling

If any step in the trigger pipeline fails (chat creation, resolution, container startup), the scheduler:

Logs the error
Updates schedule_next_run to the next trigger time
Does not update schedule_last_run (only updated on successful execution start)

The next scheduled trigger will attempt the full pipeline again. There is no exponential backoff — the cron schedule determines retry timing.

Running multiple replicas (leader election)

Crewship runs three scheduling loops in each server process: the agent cron scheduler (this guide), the pipeline/routine cron scheduler, and the recurring-issue dispatcher. If you run more than one crewship replica against the same database, every replica would tick — and without coordination they would all fire the same due job, double-running scheduled agents and double-stamping recurring issues. To make a multi-replica deploy safe, the schedulers use a small database-backed leader election lease. A single row in the scheduler_leader table records the current leader and an expiry; each replica renews it on an interval and only fires while it holds a non-expired lease. Exactly one replica is leader at a time, so each due occurrence fires once. (Per-occurrence idempotency remains as a second line of defence.)

Enabled by default. A lone replica wins the lease immediately, so single-instance behaviour is unchanged — nothing to configure for a single server.
No extra infrastructure. The lease lives in the same database the schedulers already use (SQLite or Postgres) — no etcd/consul/redis.
Failover. The lease TTL is 60 seconds and the leader renews every 20 seconds. If the leader crashes or loses the database, a standby steals the expired lease within one TTL and takes over. A clean shutdown releases the lease immediately, so failover is near-instant.

Configuration

Env var	Default	Purpose
`CREWSHIP_SCHEDULER_LEADER_ELECTION`	`1` (on)	Set to `0`/`false`/`off` to disable leader election and leave every scheduling loop always-fire (the pre-election behaviour). Only safe with exactly one replica.
`CREWSHIP_REPLICA_ID`	random per process	A stable identity for this replica in the lease row. Handy for logs/debugging; optional.

Until you enable leader election (or while it is disabled), run exactly one scheduler-bearing replica. Two replicas with election disabled will double-fire every schedule and recurring issue.

What’s Next

Orchestration — multi-agent missions with task dependencies
Agent memory — persistent agent memory across runs

Get Started

Guides

Security

Configuration

Manifest Reference

Scheduling

Agent Scheduling

How It Works

Enabling a Schedule

Pinning a schedule to a routine version

Fire outcomes (`last_status`)

Cron Expression Format

Execution Flow

At-most-once firing

Missed-run catch-up (routine schedules)

Timeout

Monitoring

Timestamp Fields

Run Records

Dynamic Updates

Error Handling

Running multiple replicas (leader election)

Configuration

What’s Next

​Agent Scheduling

​How It Works

​Enabling a Schedule

​Pinning a schedule to a routine version

​Fire outcomes (last_status)

​Cron Expression Format

​Execution Flow

​At-most-once firing

​Missed-run catch-up (routine schedules)

​Timeout

​Monitoring

​Timestamp Fields

​Run Records

​Dynamic Updates

​Error Handling

​Running multiple replicas (leader election)

​Configuration

​What’s Next

Agent Scheduling

How It Works

Enabling a Schedule

Pinning a schedule to a routine version

Fire outcomes (`last_status`)

Cron Expression Format

Execution Flow

At-most-once firing

Missed-run catch-up (routine schedules)

Timeout

Monitoring

Timestamp Fields

Run Records

Dynamic Updates

Error Handling

Running multiple replicas (leader election)

Configuration

What’s Next