크론 개요 및 표현식
스케줄링 개념, 세 가지 스케줄 유형, 크론 작업 유형, 타임존 지원을 포함한 크론탭 표현식 문법을 설명합니다.
Revka의 크론 서브시스템은 크론 표현식으로 반복 실행하거나, 고정 간격으로 반복하거나, 지정된 미래 시점에 한 번 실행하는 등 작업을 자동으로 수행합니다. 각 예약 작업은 셸 명령, 에이전트 프롬프트, 또는 워크플로 트리거 형태로 실행됩니다. 작업은 SQLite 데이터베이스에 저장되며, 데몬 내부의 스케줄러 루프에 의해 실행됩니다.
이 페이지는 개념적 진입점입니다. 세 가지 스케줄 유형, 세 가지 작업 유형, cron.enabled로 서브시스템 전체를 켜고 끄는 방법, 작업이 저장되는 위치, 그리고 정규화·요일 재번호 매기기·IANA 타임존 지원을 포함한 크론탭 표현식 전체 문법을 설명합니다. CLI 워크플로는 revka cron을, 에이전트 전용 동작은 에이전트 작업 및 전달을, 설정 파일 기반 작업 및 스케줄러 튜닝은 선언적 작업 및 스케줄러 설정을 참고하세요.
작업을 예약해야 하는 경우
섹션 제목: “작업을 예약해야 하는 경우”야간 보고서, 매시간 상태 점검, 일회성 알림, 반복 워크플로 실행 등 시간이나 타이머에 따라 작업이 자동으로 실행되어야 할 때 크론을 사용하세요. 지금 직접 실행할 일회성 작업이라면 명령이나 프롬프트를 직접 실행하는 것이 낫습니다. 서브시스템 전체는 동일한 데이터베이스를 공유하는 네 가지 인터페이스로 접근할 수 있습니다.
revka cronCLI- 에이전트 도구
cron_add,cron_list,cron_remove,cron_update,cron_run,cron_runs(및 레거시schedule도구) /api/cron게이트웨이 REST API- 대시보드 크론 페이지
스케줄 유형
섹션 제목: “스케줄 유형”모든 작업은 kind 판별자로 선택되는 세 가지 상호 배타적인 스케줄 형태 중 하나를 사용합니다. 도구 및 설정 화면에서 스케줄은 JSON/TOML 객체이며, CLI와 게이트웨이 API는 각 형태를 전용 서브커맨드나 필드로 제공합니다.
kind | 동작 | 반복 여부 | 타임존 지원 | 필수 필드 |
|---|---|---|---|---|
cron | 크론탭 표현식으로 실행 | 예 | 예 (tz) | expr |
every | N밀리초마다 실행 | 예 | 아니요 | every_ms |
at | 절대 UTC 시각에 한 번 실행 | 아니요 | 아니요 (항상 UTC) | at |
// Cron: weekdays at 09:00 New York time{"kind": "cron", "expr": "0 9 * * 1-5", "tz": "America/New_York"}
// Every: once an hour{"kind": "every", "every_ms": 3600000}
// At: once, then auto-removed{"kind": "at", "at": "2026-12-31T23:59:00Z"}필드 참조:
| 필드 | 적용 대상 | 타입 / 규칙 |
|---|---|---|
expr | cron (필수) | 5-, 6-, 또는 7-필드 크론탭 표현식 |
tz | cron (선택) | IANA 타임존 이름; 기본값은 UTC |
every_ms | every (필수) | 양의 정수 밀리초 (> 0이어야 함) |
at | at (필수) | RFC 3339 UTC 날짜시각; 생성 시점에 미래여야 함 |
일회성 작업과 자동 삭제
섹션 제목: “일회성 작업과 자동 삭제”at 스케줄은 일회성입니다. 성공적으로 실행되면 데이터베이스에서 삭제됩니다(at 작업의 경우 delete_after_run은 기본값이 true). 일회성 작업이 실패하면 출력을 디버깅을 위해 보존하기 위해 삭제되지 않고 비활성화됩니다 — 확인 후 수동으로 삭제하세요. at 작업에 delete_after_run = false를 설정하면, 과거 실행 시각으로 재실행되지 않도록 실행 후 삭제 대신 비활성화되며 비활성 상태 처리는 직접 해야 합니다.
작업 유형
섹션 제목: “작업 유형”스케줄과 무관하게 모든 작업은 세 가지 실행 백엔드 중 하나를 가집니다.
job_type | 실행 내용 | 비고 |
|---|---|---|
shell | 워크스페이스 디렉토리에서 sh -c <command>로 셸 명령 실행 | 120초 타임아웃; 보안 정책에 따라 유효성 검사 |
agent | 프롬프트와 함께 Revka 에이전트 실행 | 메모리 컨텍스트 주입; 읽기 전용 모드에서는 차단됨; 세션 대상, 모델 오버라이드, 도구 허용 목록 지원 |
workflow | POST /api/workflows/run/:name으로 이름이 지정된 Kumiho 워크플로 실행 | 워크플로 YAML 트리거에 의해 자동 관리됨 — cron_add로 생성 불가 |
# Shell jobrevka cron add '*/15 * * * *' 'echo ok'
# Agent job (trailing argument is a prompt)revka cron add '*/15 * * * *' --agent 'Check server health'workflow 작업은 워크플로 YAML에서 크론 트리거를 선언했기 때문에 생성됩니다. 크론 저장소에 자동으로 동기화되며 __wf_cron_<slug>_<index> 형식의 ID를 가집니다. 작성 방법에 대한 자세한 내용은 변수, 표현식 및 트리거를 참고하세요. 세션 대상, 모델 오버라이드, 도구 허용 목록, 채팅 채널로의 출력 전달에 대해서는 에이전트 작업 및 전달을 참고하세요.
크론 표현식 문법
섹션 제목: “크론 표현식 문법”표준 5-필드 크론탭 표현식을 사용합니다.
┌───────────── minute (0–59)│ ┌─────────── hour (0–23)│ │ ┌───────── day of month (1–31)│ │ │ ┌─────── month (1–12 or JAN–DEC)│ │ │ │ ┌───── day of week (0–6, 0 = Sunday — see below)│ │ │ │ │* * * * *모든 일반적인 필드 문법을 지원합니다.
| 문법 | 의미 | 예시 |
|---|---|---|
* / ? | 모든 값 | * * * * * (매 분) |
a-b | 범위 | 1-5 (요일 필드에서 월–금) |
a,b,c | 목록 | 0,6 (일요일과 토요일) |
*/n | 전체 범위에서 간격 | */5 (5번째마다) |
a-b/n | 범위 내 간격 | 1-5/2 |
| 이름 값 | 월과 요일을 이름으로 지정 | MON-FRI, JAN |
정규화
섹션 제목: “정규화”Revka는 내부적으로 크론 스케줄을 6-필드 형식(sec min hour day month weekday)으로 저장하므로, 5-필드 표현식은 저장 전에 정규화됩니다. revka cron add에서 출력되거나 revka cron list에서 표시되는 표현식이 입력한 것과 다른 이유가 이 때문입니다. 5-필드 입력에 두 가지 변환이 적용됩니다.
- 초 필드가 앞에 추가됩니다.
0 9 * * *는0 0 9 * * *가 됩니다 — 0초에 실행됩니다. - 요일 열이 재번호 매겨집니다 (아래 참고).
You write: 0 9 * * 1-5 (weekdays at 09:00)Stored as: 0 0 9 * * 2-6초를 포함하는 6-필드 표현식과 연도를 포함하는 선택적 7-필드 표현식은 이미 내부 형식인 것으로 간주하여 변환 없이 그대로 저장됩니다 — 재번호 매기기가 적용되지 않습니다.
요일 재번호 매기기
섹션 제목: “요일 재번호 매기기”표준 vixie-cron에서는 일요일이 0 또는 7, 월요일이 1, … 토요일이 6입니다. Revka의 내부 크론 엔진은 다른 규칙을 사용합니다: 1 = 일요일, 2 = 월요일, … 7 = 토요일. 정규화기는 5-필드 요일 값을 그에 맞게 변환하므로, 1-5(월–금)는 2-6으로 저장됩니다.
| 입력 | 의미 |
|---|---|
*/5 * * * * | 매 5분마다 |
0 9 * * * | 매일 09:00 |
0 9 * * 1-5 | 평일 09:00 |
0 9 * * MON-FRI | 평일 09:00 (이름 요일) |
0 0,12 * * * | 매일 자정과 정오 |
0 */2 * * * | 매 2시간마다 정각 |
0 2 * * 0 | 일요일 02:00 |
30 8 1 * * | 매월 1일 08:30 |
타임존 지원
섹션 제목: “타임존 지원”tz 필드(CLI: --tz)를 추가하면 크론 표현식을 IANA 타임존으로 현지화할 수 있습니다. 스케줄러는 해당 타임존에서 다음 실행 시각을 계산하며 — 일광절약시간 전환도 올바르게 처리됩니다 — UTC로 변환하여 저장합니다. 따라서 tz = "America/Los_Angeles"로 설정한 0 9 * * *는 고정된 UTC 오프셋이 아니라 연중 로스앤젤레스 시각 09:00에 실행됩니다.
revka cron add '0 9 * * *' --tz America/Los_Angeles 'echo morning'{"kind": "cron", "expr": "0 9 * * *", "tz": "America/Los_Angeles"}타임존 이름은 생성 시 chrono-tz로 유효성 검사가 이루어지며, 알 수 없는 이름은 거부됩니다.
cron.enabled 플래그
섹션 제목: “cron.enabled 플래그”cron.enabled는 서브시스템 전체의 전역 켜기/끄기 스위치입니다. false로 설정하면 스케줄러 루프가 작업을 실행하지 않으며 크론 도구와 API 엔드포인트가 오류를 반환합니다. 기본값은 true입니다.
[cron]enabled = true # default; set false to disable all schedulingAPI를 통해 런타임에서 전환할 수도 있습니다.
PATCH /api/cron/settingsAuthorization: Bearer <pairing-token>Content-Type: application/json
{"enabled": false}작업 저장 위치
섹션 제목: “작업 저장 위치”모든 크론 작업과 실행 기록은 다음 경로의 SQLite 데이터베이스에 저장됩니다.
<workspace_dir>/cron/jobs.dbcron_jobs(정의)와 cron_runs(실행 기록) 두 테이블을 사용하며, 처음 사용할 때 자동으로 생성됩니다. 데이터베이스를 열 때 스키마 마이그레이션이 자동으로 적용됩니다(allowed_tools, source 등 새로운 컬럼이 기존 데이터베이스에 자동으로 추가됨). 따라서 Revka를 업그레이드할 때 수동 마이그레이션이 필요하지 않습니다. 작업을 삭제하면 ON DELETE CASCADE를 통해 해당 cron_runs 행도 함께 삭제됩니다.
모든 인터페이스가 동일한 데이터베이스에 쓰기 때문에, CLI, 에이전트 도구, 게이트웨이 API, 선언적 설정으로 생성된 작업이 모두 revka cron list와 GET /api/cron에서 함께 표시됩니다.