작업 스케줄링¶

작업 스케줄링을 사용하면 cron 표현식, 고정 인터벌, 단일 일회성 실행으로 컨테이너 에이전트를 자동 실행할 수 있습니다. 예약된 작업은 스쿼드 UI와 독립적으로 동작하고, 앱이 시스템 트레이로 최소화된 상태에서도 백그라운드에서 실행됩니다.

이 버전의 컨테이너 태스크 실행 안내

컨테이너 태스크 실행기가 연결될 때까지 이 버전에서는 자동화의 컨테이너 태스크 탭이 숨겨져 있습니다(CONTAINER_TASK_SCHEDULER_AVAILABLE). 기존 컨테이너 태스크는 실행 기록을 확인하거나 삭제할 수 있도록 자동화 탭에 읽기 전용 섹션으로 남아 있으며, 실행 시각이 도래한 태스크는 거짓 success 대신 skipped(not run: no container executor) 항목을 기록합니다.

일정 유형¶

유형	실행 시점	예시 사용 사례
Cron	cron 표현식으로 정의된 특정 시간	평일 오전 9시에 일일 보고서
간격	N 밀리초마다 반복	5분마다 모니터링 확인
1회	특정 ISO 타임스탬프에 한 번	예약된 유지 보수 시간에 마이그레이션 실행

예약 작업 생성¶

앱에서¶

컨테이너 태스크 탭은 지금 숨겨져 있습니다

컨테이너 태스크 실행기를 마무리하는 동안 자동화 페이지에 컨테이너 태스크 탭이 표시되지 않으므로, 아래 단계는 탭이 다시 나타난 뒤에 적용됩니다. 그 전에는 Management API로 컨테이너 태스크를 관리하세요.

자동화 > 컨테이너 태스크로 이동합니다.
새 컨테이너 태스크를 클릭합니다.

컨테이너 태스크 설정을 입력합니다:

필드	설명
이름	사람이 읽기 쉬운 레이블
프롬프트	에이전트에 전달할 작업 설명/지침
일정 유형	Cron, 간격, 또는 1회
Cron 표현식, 간격 (밀리초), 실행 시각	일정 유형에 따라 cron 표현식, ms 단위 간격, 또는 ISO 타임스탬프
그룹 폴더	실행할 컨테이너 그룹 네임스페이스
컨텍스트 모드	그룹 세션 컨텍스트를 재사용(`group`) 또는 실행할 때마다 새로 시작(`isolated`, 기본값)
시간대	일정에 사용할 IANA 시간대, 시스템 시간대로 미리 채워짐
시작 시 누락된 실행 따라잡기	앱이 시작될 때, 꺼져 있는 동안 놓친 실행을 실행

생성을 클릭합니다.

이 폼에는 이미지, 타임아웃, 켜기/끄기 필드가 없습니다. 새 컨테이너 태스크는 활성 상태로 시작하며, 카드의 태스크 비활성화 또는 태스크 활성화로 일시정지하거나 재개합니다. 아래처럼 Management API로 containerConfig를 지정하지 않으면 태스크는 aigo-agent-runner:latest 이미지와 300초 타임아웃으로 실행됩니다.

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 표현식¶

Backend.AI GO는 표준 5필드 cron 표현식을 사용합니다:

┌───────── 분 (0-59)
│ ┌───────── 시 (0-23)
│ │ ┌───────── 일 (1-31)
│ │ │ ┌───────── 월 (1-12)
│ │ │ │ ┌───────── 요일 (0-7, 일요일 = 0 또는 7)
│ │ │ │ │
* * * * *

일반적인 예시¶

표현식	일정
`0 9 * * 1-5`	평일 오전 9:00
`0 /4 * *`	4시간마다
`30 8 * * 0`	일요일 오전 8:30
`0 0 1 * *`	매월 1일 자정
`/15 * * *`	15분마다

시간대

Cron 일정은 태스크의 시간대(Asia/Seoul 같은 IANA 이름)를 기준으로 실행됩니다. 폼은 시스템 시간대로 미리 채우고, API로 만들 때의 기본값은 UTC입니다. 호스트의 TZ 환경 변수는 컨테이너에 전달됩니다.

인터벌 일정¶

인터벌 일정은 N 밀리초마다 실행됩니다. 인터벌은 최소 10,000ms(10초) 이상이어야 합니다.

# 5분마다 실행 (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
    }
  }'

드리프트 방지

스케줄러는 실제 실행 시각이 아니라 예약된 시각을 기준으로 next_run을 계산하므로 일정 드리프트가 생기지 않습니다. 작업이 30초 걸리더라도 다음 실행은 30초 밀리지 않고 예상 시각에 시작됩니다.

일회성 일정¶

일회성 일정은 특정 UTC 타임스탬프에 한 번 실행되고 자동으로 완료 처리됩니다:

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
    }
  }'

컨텍스트 모드¶

컨텍스트 모드는 실행과 실행 사이에 컨테이너 세션을 어떻게 관리할지 결정합니다:

모드	동작	적합한 용도
`isolated`	매 실행마다 새 세션 (기본값)	독립적인 작업, 보고서 생성
`group`	실행 간에 그룹 세션 재사용	상태 유지 워크플로우, 모니터링

isolated 모드에서는 매 실행이 깨끗한 .claude/ 세션 디렉토리로 시작합니다. group 모드에서는 세션이 실행 사이에도 유지되므로 에이전트가 대화 기록과 메모리를 그대로 갖고 갑니다.

컨테이너 태스크 관리¶

컨테이너 태스크 목록 조회¶

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

컨테이너 태스크 조회¶

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

컨테이너 태스크 수정¶

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

컨테이너 태스크 삭제¶

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

컨테이너 태스크 일시정지¶

컨테이너 태스크를 삭제하지 않고 일시정지하려면 자동화 > 컨테이너 태스크에서 태스크 카드의 태스크 비활성화를 클릭하거나 enabled: false로 설정합니다:

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

실행 로그 확인¶

컨테이너 태스크가 실행될 때마다 실행 로그 항목이 생성됩니다.

앱에서¶

자동화 > 컨테이너 태스크로 이동합니다.
컨테이너 태스크 카드를 클릭해 실행 기록을 엽니다.

Management API를 통해¶

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

응답:

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

실행 상태 값¶

상태	설명
`running`	현재 실행 중
`success`	완료됨. `result`에 출력 요약이 담깁니다
`failed`	실행이 실패했거나 타임아웃을 넘김. `error`에 이유가 담깁니다
`skipped`	컨테이너 실행기가 연결되지 않은 상태에서 실행 시각이 도래함. `result`에 `not run: no container executor`가 기록됩니다
`cancelled`	실행이 취소됨

컨테이너 태스크의 컨테이너 설정¶

컨테이너 태스크마다 컨테이너 관련 설정을 지정할 수 있습니다:

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

필드	기본값	설명
`image`	`aigo-agent-runner:latest`	사용할 컨테이너 이미지
`timeoutSecs`	`300`	최대 실행 시간 (초, 0 = 무제한)
`env`	`[]`	추가 환경 변수

환경 변수 보안

env에는 민감하지 않은 환경 변수만 전달해야 합니다. API 키와 자격 증명은 항상 자격 증명 프록시를 통해 전달하세요.

문제 해결¶

컨테이너 태스크가 실행되지 않음¶

컨테이너 태스크의 enabled가 true인지 확인 (카드에 활성이 표시됨)
스케줄러 틱 간격 확인 (스케줄러는 15초마다 검사합니다)
컨테이너 런타임이 사용 가능한지 확인

컨테이너 태스크가 실행되지만 즉시 실패함¶

실행 로그의 error와 result 확인
컨테이너 이미지가 존재하는지 확인: 설정 > 스쿼드 > 에이전트 러너 이미지
감사 로그에서 마운트 또는 권한 오류 검토

Cron 일정이 잘못된 시간에 실행됨¶

태스크의 시간대 확인 (API 기본값은 UTC)
온라인 cron 표현식 검사기로 표현식 검증
cron은 태스크의 시간대로 실행되고, 호스트의 TZ 환경 변수는 컨테이너에 전달된다는 점에 유의

인터벌 일정에 드리프트가 발생함¶

스케줄러는 드리프트 방지 로직을 사용합니다 (다음 실행 = 실제 실행 시각이 아닌 예약된 시각)
그래도 드리프트가 보이면 시스템 시계 변경이나 과도한 시스템 부하가 있는지 확인