9.7. 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¶

Via Settings UI¶

1. Go to Settings > Container > Schedules.

2. Click New Schedule.

3. Fill in the schedule configuration:

   Field	Description
   Name	Human-readable label
   Group	Container group namespace to run in
   Prompt	The task description/instructions for the agent
   Schedule Type	Cron, Interval, or Once
   Schedule Value	Cron expression, interval in ms, or ISO timestamp
   Image	Container image (default: aigo-agent-runner:latest)
   Timeout	Maximum execution time in seconds (0 = no limit, default: 300)
   Context Mode	group (reuse session) or isolated (fresh session each time)
   Enabled	Toggle to pause/resume the schedule

4. Click Create.

Via Management API¶

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

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:55765/api/v1/container/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Health Monitor",
    "group": "monitoring",
    "prompt": "Check system health and append a status line to /workspace/health.log",
    "schedule": {
      "type": "interval",
      "value": 300000
    },
    "enabled": true
  }'

One-Time Schedules¶

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

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

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:55765/api/v1/container/schedules

Get a Schedule¶

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

Update a Schedule¶

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

Delete a Schedule¶

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

Pause a Schedule¶

Set enabled: false to pause a schedule without deleting it:

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

Viewing Run Logs¶

Every schedule execution creates a run log entry.

Via Settings UI¶

1. Go to Settings > Container > Schedules.

2. Click on a schedule name.

3. Click Run Logs to see execution history.

Via Management API¶

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

Response:

[
  {
    "id": "run-abc123",
    "scheduleId": "sched-xyz789",
    "startedAt": "2026-03-15T09:00:00Z",
    "finishedAt": "2026-03-15T09:02:15Z",
    "status": "completed",
    "exitCode": 0,
    "output": "Report written to /workspace/reports/daily.md"
  }
]

Run Status Values¶

Container Configuration for Schedules¶

Each schedule 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 schedule
• 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 for the exit code and output
• Verify the container image exists: Settings > Container > Image Status
• Review the audit log for mount or permission errors

Cron schedule fires at wrong time¶

• Verify your system timezone is set correctly
• Use an online cron expression tester to validate your expression
• Remember: cron uses local system time, and the TZ env var is passed through

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