revka cron

revka cron은 Revka 런타임이 자동으로 실행할 작업을 예약합니다. 크론 표현식으로 반복 실행하거나, 고정 인터벌로 반복하거나, 미래의 특정 시점에 한 번 실행할 수 있습니다. 각 작업은 셸 명령어 또는 에이전트 프롬프트 중 하나로 실행되며, 전체 서브시스템은 데몬 스케줄러가 폴링하는 SQLite 데이터베이스로 지원됩니다.

이 페이지는 작업을 생성하고 관리하기 위한 CLI 레퍼런스입니다. 예약하는 네 가지 방법(add, add-every, add-at, once), 목록 조회, 수정, 일시 중지, 재개, 삭제하는 방법, --tz의 시간대 동작 방식, 에이전트 전용 플래그인 --agent와 --allowed-tool을 다룹니다. 개념적 모델과 표현식 문법에 대한 자세한 내용은 크론 개요 및 표현식과 에이전트 작업 및 전달을 참조하세요.

참고

작업을 실제로 실행하는 스케줄러는 revka daemon 내부에서 동작합니다. 데몬이 실행 중이지 않아도 CLI에서 작업을 생성, 조회, 수정할 수 있지만, 실제 실행은 데몬이 동작 중일 때만 이루어집니다. CLI 크론 작업(생성/조회/수정/일시 중지/재개/삭제)은 cron.enabled 설정과 무관하게 실행됩니다. 이 플래그는 데몬 스케줄러가 실제로 작업을 실행할지(그리고 에이전트 크론 도구와 /api/cron 엔드포인트를 사용할 수 있는지)만 제어합니다. cron.enabled = false로 설정되어 있어도 CLI에서 작업을 관리할 수 있지만, 데몬이 실행 중이고 설정이 다시 활성화될 때까지 아무 작업도 실행되지 않습니다. revka gateway, daemon & service를 참조하세요.

예약 유형 한눈에 보기

모든 작업은 세 가지 예약 형태 중 하나를 사용합니다. CLI는 각 형태에 대한 전용 서브커맨드를 제공합니다:

서브커맨드	예약 형태	반복 여부	시간대 지원 여부
revka cron add <expr> <cmd>	크론 표현식	예	예 (--tz)
revka cron add-every <ms> <cmd>	N 밀리초마다 반복	예	아니요
revka cron add-at <rfc3339> <cmd>	절대 UTC 시각에 1회 실행	아니요	아니요 (항상 UTC)
revka cron once <delay> <cmd>	상대적 지연 후 1회 실행	아니요	아니요

--tz는 크론 표현식 작업에서만 적용됩니다. 인터벌 및 1회성 예약은 시간대를 인식하지 않으며, add-at과 add-every는 벽시계 시간대를 완전히 무시합니다.

반복 작업 추가

revka cron add는 크론 표현식과 명령어를 인수로 받습니다:

# Shell job: every five minutes
revka cron add '*/5 * * * *' 'echo ok'

# Shell job: weekdays at 09:00 in a specific timezone
revka cron add '0 9 * * 1-5' --tz Asia/Seoul 'python3 /opt/report.py'

주요 플래그:

플래그	적용 대상	의미
--tz <IANA_TZ>	크론 작업 전용	IANA 시간대 이름 (예: America/Los_Angeles). 기본값: UTC
--agent	모든 add 변형	마지막 인수를 셸 명령어가 아닌 에이전트 프롬프트로 처리
--allowed-tool <NAME>	에이전트 작업 전용 (반복 지정 가능)	에이전트가 사용할 수 있는 도구를 제한

성공 시 CLI는 생성된 작업 ID, 정규화된 표현식, 다음 실행 시각을 출력합니다:

✅ Added cron job 7b3f1c20-...-9a
  Expr: 0 0 9 * * 2-6
  Next: 2026-06-19T00:00:00+00:00
  Cmd : python3 /opt/report.py

출력된 Expr는 정규화된 6-필드 형식입니다. 1-5가 2-6으로 변환된 이유는 표현식 정규화를 참조하세요.

주의

셸 명령어는 생성 시점(그리고 실행 시점)에 보안 정책에 따라 검증됩니다. 위험도가 중간인 명령어는 autonomy.allowed_commands 허용 목록에 등록되어 있지 않거나 승인되지 않은 경우 거부될 수 있습니다. 에이전트 작업은 셸 유효성 검사를 건너뜁니다. 자율성 수준 및 승인과 정책, 명령어 및 샌드박싱을 참조하세요.

인터벌 작업 추가

revka cron add-every는 N 밀리초마다 반복합니다:

# Shell job every hour (3,600,000 ms)
revka cron add-every 3600000 'echo hourly'

# Agent job every 15 minutes
revka cron add-every 900000 --agent 'Check disk space and summarize'

인터벌은 양의 정수여야 합니다. 인터벌 작업은 --tz의 영향을 받지 않습니다.

1회성 작업 추가

작업을 정확히 한 번만 실행하는 방법은 두 가지입니다.

상대적 지연 후 실행

revka cron once는 사람이 읽기 쉬운 지연 값을 받습니다:

revka cron once 1h 'backup create'
revka cron once 30m --agent 'Check the build and post the result'

지연 값은 숫자와 단위의 조합입니다:

단위	의미
s	초
m	분
h	시간
d	일

참고

단위를 생략하면 값은 분으로 해석됩니다. 예를 들어 revka cron once 30 'echo hi'는 30초가 아니라 30분을 의미합니다.

절대 타임스탬프에 실행

revka cron add-at은 RFC 3339 (ISO 8601) UTC 타임스탬프를 받습니다. 오프셋은 필수이며, 생성 시점에 미래 시각이어야 합니다:

revka cron add-at 2026-12-31T23:59:00Z 'echo new year'
revka cron add-at 2026-07-01T08:00:00Z --agent 'Send the monthly reminder'

팁

1회성 셸 작업은 성공적으로 실행된 후 자동으로 삭제됩니다. 1회성 작업이 실패하면 디버깅을 위해 출력이 보존되도록 비활성화됩니다(삭제되지 않음). 확인 후 revka cron remove <id>로 수동 삭제하세요. 에이전트 1회성 작업도 기본적으로 실행 후 삭제됩니다. 자동 삭제 규칙에 대한 자세한 내용은 크론 개요 및 표현식을 참조하세요.

에이전트 작업

add 변형에 --agent를 전달하면 셸 명령어 대신 에이전트 프롬프트를 예약합니다. 마지막 위치 인수가 실행 시점에 Revka 에이전트가 실행할 프롬프트가 됩니다:

revka cron add '0 9 * * 1-5' --agent 'Summarize overnight alerts'
revka cron add-every 3600000 --agent 'Check server health'
revka cron once 30m --agent 'Follow up on the open incident'

에이전트 작업은 기본적으로 격리된 새 세션에서 실행되며, 프롬프트 실행 전에 관련 메모리 컨텍스트를 주입합니다. 에이전트가 읽기 전용 모드일 때는 차단됩니다. 세션 공유, 모델 재정의, 채팅 채널로의 출력 전달을 제어하려면 cron_add 에이전트 도구 또는 선언적 설정을 사용하세요. 해당 내용은 에이전트 작업 및 전달에서 다룹니다.

--allowed-tool로 도구 제한

에이전트 작업에서 해당 작업 실행 중 에이전트가 호출할 수 있는 도구를 정확히 허용 목록으로 지정할 수 있습니다. --allowed-tool을 도구마다 한 번씩 반복해서 지정하세요:

revka cron add '*/15 * * * *' --agent \
  --allowed-tool file_read \
  --allowed-tool web_search \
  'Check the changelog feed and note anything new'

설정된 경우 해당 작업에서는 나열된 도구만 사용할 수 있습니다. 생략하면 모든 도구를 사용할 수 있습니다.

주의

--allowed-tool은 --agent와 함께 사용할 때만 유효합니다. --agent 없이 셸 작업에 사용하면 --allowed-tool is only supported with --agent cron jobs 오류가 반환됩니다. revka cron update에도 동일하게 적용되며, 대상 작업이 이미 에이전트 작업이어야 합니다.

작업 목록 조회

revka cron list는 등록된 모든 작업을 ID, 예약, 다음 및 마지막 실행 시각, 마지막 상태와 함께 출력합니다:

revka cron list

🕒 Scheduled jobs (2):
- 7b3f1c20-...-9a | Cron { expr: "0 0 9 * * 2-6", tz: Some("Asia/Seoul") } | next=2026-06-19T00:00:00+00:00 | last=never (n/a)
    cmd: python3 /opt/report.py
- 9d40f6a1-...-c2 | At { at: 2026-07-01T08:00:00Z } | next=2026-07-01T08:00:00+00:00 | last=never (n/a)
    prompt: Send the monthly reminder

셸 작업은 cmd: 줄을 표시하고, 에이전트 작업은 prompt: 줄을 표시합니다. 예약은 내부 디버그 형식으로 출력되므로 정규화된 표현식과 저장된 시간대를 확인할 수 있습니다. 작업이 없으면 짧은 사용 힌트를 출력합니다.

작업 수정

revka cron update <id>는 작업을 재생성하지 않고 제자리에서 수정합니다. 플래그를 하나 이상 지정해야 합니다:

# Change the schedule and timezone
revka cron update 7b3f1c20 --expression '0 10 * * *' --tz Europe/Berlin

# Change just the timezone, keeping the existing expression
revka cron update 7b3f1c20 --tz Europe/London

# Change the command and label
revka cron update 7b3f1c20 --command 'echo updated' --name 'Morning report'

플래그	의미
--expression <EXPR>	새 크론 표현식 (함께 전달하지 않으면 기존 --tz 유지)
--tz <IANA_TZ>	새 시간대 (단독 사용 시 기존 표현식 유지)
--command <CMD>	새 셸 명령어 (에이전트 작업의 경우 새 프롬프트)
--name <NAME>	새 사람이 읽기 쉬운 레이블
--allowed-tool <NAME>	에이전트 도구 허용 목록 교체 (반복 지정 가능; 에이전트 작업 전용)

참고

--expression과 --tz는 크론 표현식 작업에만 적용됩니다. 이 방법으로 인터벌 또는 1회성 작업을 새 표현식으로 변경할 수는 없습니다. 셸 명령어를 수정하면 보안 정책 검증을 다시 거치므로, 위험도가 중간인 변경은 승인이 필요할 수 있습니다. 플래그를 지정하지 않으면 오류가 반환됩니다.

일시 중지, 재개, 삭제

revka cron pause  7b3f1c20   # disable without deleting
revka cron resume 7b3f1c20   # re-enable
revka cron remove 7b3f1c20   # permanently delete (cannot be undone)

일시 중지된 작업은 예약을 유지한 채 데이터베이스에 남아 있으며, 일시 중지 중에는 다음 실행 시각이 갱신되지 않습니다. remove는 작업과 그 실행 기록(cron_runs 행이 연쇄 삭제됨)을 영구적으로 삭제합니다. 실행 취소는 불가능합니다.

시간대 동작 방식

--tz는 크론 표현식을 임의의 IANA 시간대로 지역화합니다. 스케줄러는 해당 시간대에서 다음 실행 시각을 계산하며(일광 절약 시간 전환도 정확하게 처리), UTC로 변환하여 저장합니다. 따라서 '0 9 * * *' --tz America/Los_Angeles는 고정 UTC 오프셋이 아니라 연중 내내 로스앤젤레스 시각 09:00에 실행됩니다.

시간대 이름은 생성 시점에 chrono-tz가 검증하며, 알 수 없는 이름은 거부됩니다.

주의

--tz를 생략하면 호스트의 로컬 시간대가 아닌 UTC가 기본값으로 사용됩니다. 이 점이 혼란을 일으키는 경우가 많습니다. revka cron add '0 9 * * *' 'echo hi'는 UTC 09:00에 실행됩니다. 호스트 로컬 시간으로 동작하게 하려면 시간대를 명시적으로 지정하세요(예: --tz America/New_York). 또한 --tz는 revka cron add / update에서만 적용되며, add-at, add-every, once는 이를 무시합니다.

표현식 정규화

표준 5-필드 크론탭 표현식(min hour day month weekday)을 작성합니다. Revka는 저장 전에 내부 6-필드 형식으로 정규화하기 때문에 add 출력과 list의 Expr 줄이 입력과 다르게 보입니다.

5-필드 입력에 대해 두 가지 변환이 이루어집니다:

1. 초 필드가 앞에 추가됩니다. 0 9 * * *는 0 0 9 * * *가 됩니다(0초에 실행).
2. 요일 열이 재번호 매김됩니다. 표준 크론탭은 0/7 = 일요일, 1 = 월요일 … 6 = 토요일을 사용합니다. Revka 내부 크론 엔진은 1 = 일요일, 2 = 월요일 … 7 = 토요일을 사용합니다. 따라서 1-5(월~금)는 2-6으로 저장됩니다.

입력 시에는 항상 친숙한 vixie-cron 번호 체계(1 = 월요일)를 사용하면 됩니다. 재번호 매김은 내부적으로 처리됩니다. 와일드카드(*, ?), 이름 지정 요일(MON, MON-FRI), 범위(1-5), 목록(0,6), 스텝(*/2, 1-5/2)이 모두 지원되며, 이름 지정 요일은 재번호 매김 없이 그대로 처리됩니다.

6-필드 및 7-필드 표현식(초 필드를 이미 포함하고 선택적으로 연도 포함)은 이미 내부 형식인 것으로 간주하여 변경 없이 통과됩니다.

작성 예시와 의미:

입력	의미
*/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

CLI 작업과 다른 인터페이스의 관계

여기서 생성한 작업은 에이전트 도구, 게이트웨이 API, 선언적 설정으로 생성된 작업과 함께 동일한 데이터베이스에 저장되며, revka cron list에서 모두 함께 표시됩니다.

크론 개요 및 표현식 예약 유형, 표현식 문법, 정규화, 1회성 자동 삭제에 대한 심층 설명.

에이전트 작업 및 전달 세션 대상, 모델 재정의, 도구 허용 목록, 채널에 결과 공지.

선언적 작업 및 스케줄러 config.toml의 [[cron.jobs]] 아래에 작업을 정의하고 스케줄러를 조정.

크론, 세션 및 첨부 파일 API /api/cron 게이트웨이 엔드포인트를 통해 HTTP로 작업을 관리.