Task Scheduling¶

Task Scheduling lets you run container agents automatically on a schedule, using cron expressions, fixed intervals, or single one-time executions. Scheduled tasks are independent of the Squad UI and run in the background even when the app is minimized to the system tray.

Schedule Types¶

Creating a Scheduled Task¶

In the App¶

1. Go to Automations > Container Tasks.

2. Click New Container Task.

3. Fill in the container task form:

   Field	Description
   Name	Human-readable label
   Prompt	The task description/instructions for the agent
   Schedule Type	Cron, Interval, or Once
   Cron Expression, Interval (milliseconds), or Run At	Cron expression, interval in ms, or ISO timestamp, depending on the schedule type
   Group Folder	Container group namespace to run in
   Context Mode	Reuse the group session context (group) or Start fresh for each execution (isolated, the default)
   Timezone	IANA timezone for the schedule, prefilled with your system's
   Catch up missed executions on startup	When the app starts, run the executions it missed while it was closed

4. Click Create.

The form has no image, timeout, or on/off fields. A new container task starts enabled: pause or resume it with Disable task or Enable task on its card. The task runs aigo-agent-runner:latest with a 300-second timeout unless you set containerConfig through the Management API, as below.

Via Management API¶

curl -X POST http://localhost:8001/api/v1/container/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Summary",
    "groupFolder": "reporting",
    "prompt": "Summarize the key events from today and write a report to /workspace/reports/daily.md",
    "scheduleType": {
      "type": "cron",
      "value": "0 9 * * 1-5"
    },
    "containerConfig": {
      "timeoutSecs": 600
    },
    "contextMode": "isolated"
  }'

Cron Expressions¶

Backend.AI GO uses standard 5-field cron expressions:

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

Common Examples¶

Interval Schedules¶

Interval schedules run every N milliseconds. The interval must be at least 10,000 ms (10 seconds).

# Run every 5 minutes (300,000 ms)
curl -X POST http://localhost:8001/api/v1/container/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Health Monitor",
    "groupFolder": "monitoring",
    "prompt": "Check system health and append a status line to /workspace/health.log",
    "scheduleType": {
      "type": "interval",
      "value": 300000
    }
  }'

One-Time Schedules¶

One-time schedules run once at a specific UTC timestamp and are automatically marked as completed:

curl -X POST http://localhost:8001/api/v1/container/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Database Migration",
    "groupFolder": "maintenance",
    "prompt": "Run the database migration script in /workspace/scripts/migrate.sh",
    "scheduleType": {
      "type": "once",
      "value": "2026-04-01T02:00:00Z"
    },
    "containerConfig": {
      "timeoutSecs": 3600
    }
  }'

Context Modes¶

The context mode determines how the container session is managed between runs:

In isolated mode, each run starts with a clean .claude/ session directory. In group mode, the session persists between runs, so the agent retains conversation history and memory.

Managing Schedules¶

List Schedules¶

curl http://localhost:8001/api/v1/container/schedules

Get a Schedule¶

curl http://localhost:8001/api/v1/container/schedules/{id}

Update a Schedule¶

curl -X PUT http://localhost:8001/api/v1/container/schedules/{id} \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Delete a Schedule¶

curl -X DELETE http://localhost:8001/api/v1/container/schedules/{id}

Pause a Schedule¶

Click Disable task on the task's card in Automations > Container Tasks, or set enabled: false to pause a container task without deleting it:

curl -X PUT http://localhost:8001/api/v1/container/schedules/{id} \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Viewing Run Logs¶

Every container task run creates a run log entry.

In the App¶

1. Go to Automations > Container Tasks.

2. Click a container task's card to open its Run History.

Via Management API¶

curl "http://localhost:8001/api/v1/container/schedules/{id}/logs?limit=20"

Response:

[
  {
    "id": "run-abc123",
    "taskId": "sched-xyz789",
    "runAt": "2026-03-15T09:00:00Z",
    "durationMs": 135000,
    "status": "success",
    "result": "Report written to /workspace/reports/daily.md"
  }
]

Run Status Values¶

Container Configuration for Schedules¶

Each container task can specify container-specific settings:

{
  "containerConfig": {
    "image": "aigo-agent-runner:latest",
    "timeoutSecs": 300,
    "env": ["MY_CUSTOM_VAR=value"]
  }
}

Troubleshooting¶

Schedule does not run¶

• Verify enabled is true on the container task (its card shows Active)
• Check the scheduler tick interval — the scheduler checks every 15 seconds
• Ensure the container runtime is available

Schedule runs but fails immediately¶

• Check the run log's error and result
• Verify the container image exists: Settings > Squad > Agent Runner Image
• Review the audit log for mount or permission errors

Cron schedule fires at wrong time¶

• Check the task's Timezone (the API default is UTC)
• Use an online cron expression tester to validate your expression
• Remember: cron runs in the task's timezone, and the host's TZ env var is passed into the container

Interval schedule drifts¶

• The scheduler uses drift-prevention logic (next run = scheduled time, not actual execution time)
• If drift is still observed, check for system clock changes or heavy system load