revka gateway, daemon, service

이 명령들은 Revka HTTP 런타임을 실행합니다. revka gateway는 대시보드와 API만 실행하고, revka daemon은 완전한 자율 런타임을 실행하며, revka service는 OS 관리 백그라운드 서비스로 두 가지 모두를 지속적으로 유지합니다. 이 페이지는 세 가지 모두에 대한 참조 문서이며, 페어링 코드 워크플로우와 네트워크 노출을 제어하는 바인드 호스트 제한도 설명합니다.

로컬 대시보드 작업에는 revka gateway를, 프로덕션 환경(채널, 하트비트, 크론 포함)에는 revka daemon을, 로그인 또는 부팅 시 Revka가 자동 시작되고 크래시 후 복구되길 원한다면 revka service를 사용하세요. 처음 시작하는 클릭형 안내는 대시보드 실행하기를, OS별 서비스 설정은 백그라운드 서비스로 실행하기를 참고하세요.

revka gateway

revka gateway는 HTTP/WebSocket 게이트웨이만 시작합니다. /의 내장 React 대시보드, /api/* 하위의 REST API, /api/events의 Server-Sent Events 스트림, 그리고 WebSocket 엔드포인트(/ws/chat, /ws/canvas/{id}, /ws/nodes)가 포함됩니다. 채널, 하트비트, 크론 스케줄러는 시작하지 않으며 — 이를 위해서는 revka daemon을 사용하세요.

revka gateway                        # 설정 기본값으로 시작
revka gateway start                  # 명시적 시작
revka gateway start -p 8080          # 커스텀 포트
revka gateway start --host 0.0.0.0   # 모든 인터페이스 바인딩 (바인드 제한 참고)
revka gateway start -p 0             # 임의의 사용 가능한 포트 바인딩
revka gateway restart                # 그레이스풀 재시작
revka gateway restart -p 9090
revka gateway get-paircode           # 현재 페어링 코드 표시
revka gateway get-paircode --new     # 새 페어링 코드로 교체

서브커맨드 및 플래그

서브커맨드	플래그	설명
start	-p / --port <u16> (0 = 임의), --host <STRING>	게이트웨이를 시작합니다. revka gateway만 입력하면 revka gateway start와 동일합니다.
restart	-p / --port <u16>, --host <STRING>	start와 동일한 플래그로 그레이스풀 재시작합니다.
get-paircode	--new	현재 페어링 코드를 출력하거나, --new로 새 코드로 교체합니다.

기본 바인딩은 127.0.0.1:42617입니다. 수신 포트는 설정의 [gateway].port에서 읽어오며(스키마 기본값 42617), --port/--host는 호출 시마다 설정을 덮어씁니다. 프로세스 시작 시 URL이 출력됩니다.

참고

[gateway].require_pairing이 true(기본값)이면, 게이트웨이는 최초 시작 시 일회용 페어링 코드를 출력합니다. 아래 페어링 코드 및 토큰 섹션을 참고하여 베어러 토큰으로 교환하세요.

revka daemon

revka daemon은 Revka 런타임 전체를 단일 포그라운드 프로세스로 실행합니다. 게이트웨이 서버, 설정된 모든 채널 슈퍼바이저(Telegram, Discord, Slack 등), 하트비트 모니터, 그리고 크론 스케줄러가 포함됩니다. 이것이 권장 프로덕션 진입점입니다 — revka service로 OS가 이를 유지하도록 등록하세요.

revka daemon                    # 설정 기본값 사용
revka daemon -p 9090            # 게이트웨이를 9090 포트로
revka daemon --host 127.0.0.1   # 로컬호스트 전용
revka daemon --host 0.0.0.0     # 모든 인터페이스 (allow_public_bind 필요)

플래그	기본값	설명
-p / --port <u16>	[gateway].port	게이트웨이 수신 포트. 0은 임의의 사용 가능한 포트를 바인딩합니다.
--host <STRING>	[gateway].host	바인딩 주소. 루프백이 아닌 주소는 제한이 있습니다 — 바인드 제한 참고.
--config-dir <PATH>	~/.revka	전역 플래그로, 서브커맨드 앞에 위치해야 합니다. 프로세스의 REVKA_CONFIG_DIR도 설정합니다.

데몬은 SIGINT 또는 SIGTERM 수신 시 정상 종료됩니다. SIGHUP은 명시적으로 무시되므로 SSH 또는 터미널 연결이 끊겨도 프로세스가 유지됩니다. 바이너리가 /usr/local/bin 같은 시스템 설치 위치 대신 사용자 홈 디렉터리에서 실행되는 경우 경고가 기록됩니다.

컴포넌트 슈퍼바이저

네 가지 데몬 컴포넌트 — 게이트웨이, 채널, 하트비트, 스케줄러 — 는 각각 슈퍼바이저로 감싸진 개별 태스크에서 실행됩니다. 크래시 또는 종료 시 슈퍼바이저는 channel_initial_backoff_secs(기본값 2)만큼 대기한 후, 이후 실패마다 channel_max_backoff_secs(기본값 60)까지 지연을 두 배로 늘려 재시작합니다. 재시작 횟수와 마지막 오류는 헬스 스냅샷에 기록됩니다.

[reliability]
channel_initial_backoff_secs = 2   # 초기 재시도 지연 (최소 1)
channel_max_backoff_secs     = 60  # 지수 백오프 상한; initial 이상이어야 함

키	타입	기본값	설명
reliability.channel_initial_backoff_secs	integer	2	초 단위 초기 재시도 지연. 최소 1.
reliability.channel_max_backoff_secs	integer	60	지수 백오프 상한. initial 값 이상이어야 합니다.

참고

정상 종료 후에도 재시작 사이클이 트리거됩니다(백오프 초기화 포함). 데몬 자체가 종료되는 경우가 아니면 어떤 컴포넌트도 종료되어서는 안 되므로, 로그에 반복적인 재시작이 나타난다면 계속 실패하는 컴포넌트가 있다는 신호입니다 — 기록된 마지막 오류를 확인하세요.

데몬 상태 파일

실행 중 데몬은 config.toml과 같은 위치(<config_dir>/daemon_state.json)에 daemon_state.json을 5초마다 기록합니다. 이 파일에는 모든 컴포넌트의 헬스 스냅샷과 written_at 타임스탬프가 포함됩니다.

• 라이브니스 모니터링 — 상태 파일이 45초 이상 오래된 경우 데몬이 종료된 것입니다. 외부 모니터가 이 파일을 직접 폴링할 수 있습니다.
• Windows — revka service start는 직접 데몬 폴백이 이미 실행 중인지 감지하기 위해 이 파일을 읽습니다. Windows 작업 스케줄러는 안정적으로 조회할 수 없기 때문입니다.

페어링 코드 및 토큰

모든 /api/* 요청은 Authorization: Bearer <token>을 포함하며, 이 토큰은 일회용 페어링 코드를 교환하여 발급됩니다. 페어링은 네트워크상의 알 수 없는 클라이언트가 에이전트를 제어하는 것을 막기 위한 보안 장치입니다.

CLI에서 코드 확인 또는 교체

revka gateway get-paircode          # 현재 코드 표시
revka gateway get-paircode --new    # 새 코드로 교체

이 명령들은 로컬호스트 전용 관리 엔드포인트 GET /admin/paircode와 POST /admin/paircode/new를 호출합니다. 코드는 일회용입니다. 클라이언트가 코드로 페어링하면 코드는 소모되며, 다시 발급하려면 교체가 필요합니다.

코드를 토큰으로 교환하기 (revka pair token)

revka pair token은 커맨드라인에서 페어링 코드를 베어러 토큰으로 교환합니다 — 헤드리스 기기나 스크립트 페어링에 유용합니다.

revka pair token --code 123456
revka pair token --code 123456 --name "Field phone" --device-type mobile --hardware "Pixel 8 / Android"
revka pair token --url http://revka.local:8080 --code 123456 --json
revka pair token --code 123456 --host 192.168.1.10 --port 8080

플래그	필수 여부	설명
--code <STRING>	필수	일회용 페어링 코드.
--url <URL>	선택	게이트웨이 전체 기본 URL, 예: http://127.0.0.1:8080.
--host <STRING>	선택	--url이 생략된 경우 사용되는 게이트웨이 호스트.
-p / --port <u16>	선택	--url이 생략된 경우 사용되는 게이트웨이 포트.
--name <STRING>	선택	대시보드 페어링 페이지에 표시되는 기기 이름.
--device-type <STRING>	선택	기기 유형 레이블. 기본값: cli.
--hardware <STRING>	선택	하드웨어/플랫폼 레이블, 예: Pixel 8 / Android.
--json	선택	사람이 읽는 텍스트 대신 머신이 읽는 JSON으로 출력.

내부적으로는 게이트웨이에 코드를 POST하여 베어러 토큰을 반환받습니다.

POST /api/pair
Content-Type: application/json

{
  "code": "123456",
  "device_name": "Field phone",
  "device_type": "mobile",
  "hardware": "Pixel 8 / Android"
}

{
  "token": "<bearer-token>",
  "persisted": true,
  "message": "Pairing successful"
}

주의

평문 토큰은 단 한 번만 출력되며 게이트웨이는 해시만 저장합니다. 즉시 저장하세요. --device-type과 --hardware는 대시보드 페어링 페이지에서 확인할 수 있는 정보용 레이블입니다.

대시보드 측 흐름, QR 기반 기기 페어링, 기기 해지에 대해서는 페어링 및 인증과 시크릿, 페어링 및 기기 인증을 참고하세요.

바인드 제한

게이트웨이는 127.0.0.1(로컬호스트 전용 — 기본값), 0.0.0.0(모든 IPv4 인터페이스), 또는 [::](모든 IPv6 인터페이스)에 바인딩할 수 있습니다. allow_public_bind = true 설정 없이(또한 활성 터널도 없이) 루프백이 아닌 주소에 바인딩하면 경고가 기록되지만 바인딩은 진행됩니다. 이는 의도적인 안전 기본값입니다 — 0.0.0.0은 게이트웨이를 연결된 모든 네트워크에 노출합니다.

[gateway]
host = "0.0.0.0"
port = 42617
allow_public_bind = true

revka daemon --host 127.0.0.1    # 로컬호스트 전용 (기본값)
revka daemon --host 0.0.0.0      # LAN 접근 — allow_public_bind = true 필요

키	타입	기본값	설명
gateway.host	string	127.0.0.1	바인딩 주소. Docker 컨테이너 내부에서는 기본값이 [::]입니다.
gateway.port	integer	42617	수신 포트. 0은 임의의 사용 가능한 포트를 바인딩합니다.
gateway.allow_public_bind	boolean	false	루프백이 아닌 주소에 바인딩하려면 true여야 합니다.

두 키 모두 컨테이너 및 CI 환경을 위한 환경변수 오버라이드를 지원합니다. REVKA_GATEWAY_HOST / HOST, REVKA_GATEWAY_PORT / PORT, 그리고 REVKA_ALLOW_PUBLIC_BIND.

REVKA_ALLOW_PUBLIC_BIND=true revka gateway start --host 0.0.0.0

주의

공개 인터넷에 노출할 경우, 0.0.0.0에 직접 바인딩하는 것보다 게이트웨이를 127.0.0.1에 유지하고 터널로 프론팅하는 것을 권장합니다. 터널로 게이트웨이 노출하기와 네트워크 배포, Raspberry Pi 및 프록시를 참고하세요.

OS 서비스 관리

revka service는 revka daemon을 영구적인 OS 관리 백그라운드 서비스로 실행하여 자동으로 시작되고 실패 시 재시작됩니다. init 시스템은 플랫폼별로 자동 감지됩니다.

• macOS — ~/Library/LaunchAgents/com.revka.daemon.plist의 launchd 에이전트 (RunAtLoad와 KeepAlive 활성화).
• Linux — ~/.config/systemd/user/revka.service의 systemd 사용자 유닛 (root 불필요), 또는 /etc/init.d/revka의 OpenRC init 스크립트.
• Windows — 사용자 로그온 시 실행되는 Revka Daemon이라는 예약 작업 (schtasks /SC ONLOGON), 스케줄러를 사용할 수 없는 경우 직접 백그라운드 스폰 폴백.

명령어

revka service install
revka service start
revka service stop
revka service restart
revka service status
revka service logs -n 100 --follow
revka service logs
revka service uninstall

# init 시스템 강제 지정 (Linux 전용)
revka service --service-init systemd install
revka service --service-init openrc install

서브커맨드	설명
install	서비스 유닛 / plist / 예약 작업을 생성하고 등록합니다.
start	서비스를 시작합니다. 데몬 로그가 20 MB를 초과하면 먼저 로테이션합니다.
stop	실행 중인 서비스를 중지합니다.
restart	중지 후 시작합니다.
status	데몬 실행 여부를 보고합니다. 폴백으로 45초 이내의 데몬 상태 파일도 확인합니다.
logs	데몬 로그를 출력합니다. -n / --lines <N>으로 줄 수를 설정하고(기본값 50), -f / --follow로 tail -f처럼 스트리밍합니다.
uninstall	서비스 유닛 / plist / 예약 작업을 제거합니다.

플래그	값	기본값	설명
--service-init	auto, systemd, openrc	auto	Linux에서 특정 init 시스템을 강제합니다. 모든 서브커맨드에 적용됩니다.

--service-init

revka service는 올바른 init 시스템을 자동 감지하지만, Linux에서는 --service-init으로 강제할 수 있습니다. 서브커맨드 앞에 전달하세요.

• auto (기본값) — systemd, OpenRC, launchd, 또는 Windows 작업 스케줄러를 자동으로 감지합니다.
• systemd — systemd 사용자 유닛을 설치합니다. systemctl --user enable revka.service를 실행하여 로그인 시 시작됩니다. 활성 세션 없이 부팅 시 시작하려면 loginctl enable-linger $USER로 lingering을 활성화하세요.
• openrc — OpenRC init 스크립트를 설치합니다. 시스템 전체 적용이며 root 권한이 필요합니다. 아래 Linux 탭을 참고하세요.

플랫폼별 참고 사항

macOS (launchd)

launchd 에이전트는 RunAtLoad와 KeepAlive로 revka daemon을 실행합니다. Homebrew 설치가 자동으로 감지됩니다. 감지 시 서비스는 로그를 <brew_prefix>/var/revka/logs/에 저장하고 plist에 REVKA_CONFIG_DIR을 환경 키로 포함하여, brew upgrade 후에도 설정과 워크스페이스 데이터가 유지됩니다. 많은 MCP 서버가 동시에 실행될 때 “Too many open files” 오류가 발생하지 않도록 plist는 파일 디스크립터 제한을 높입니다(SoftResourceLimits/HardResourceLimits의 NumberOfFiles, 소프트 4096 / 하드 8192).

brew services start revka도 동일한 plist를 사용합니다.

revka service install
revka service start

Linux (systemd)

systemd 사용자 유닛은 Restart=always와 RestartSec=3으로 revka daemon을 실행하고, LimitNOFILE=4096:8192를 설정하며, 엄선된 PATH(설치 시점의 PATH와 함께 ~/.cargo/bin, ~/.local/bin, /opt/homebrew/bin 포함)를 주입하고, 헤드리스 브라우저 지원을 위해 DISPLAY와 XDG_RUNTIME_DIR을 전달하며, network.target 이후로 순서가 지정됩니다. root 권한이 필요하지 않습니다.

revka service install
revka service start
loginctl enable-linger $USER     # 선택 사항: 활성 로그인 없이 부팅 시 시작

Alpine / OpenRC

OpenRC는 시스템 전체 적용이며 root 권한이 필요합니다. 설치 시 /etc/init.d/revka를 생성하고, revka:revka 시스템 사용자(UID < 1000, 셸 /sbin/nologin)를 생성하며, /etc/revka/, /var/lib/revka/, /var/log/revka/의 소유권을 설정하고, 최초 설치 시 기존 ~/.revka 설정을 /etc/revka로 마이그레이션합니다.

sudo revka service install        # Alpine에서 OpenRC를 자동 감지
sudo rc-update add revka default
sudo rc-service revka start

UID ≥ 1000이거나 nologin이 아닌 셸을 가진 기존 revka 사용자가 있으면 해결 방법과 함께 명확한 오류가 표시됩니다.

Windows

revka service install은 schtasks /SC ONLOGON을 통해 Revka Daemon이라는 예약 작업을 등록하여 사용자 로그온 시 데몬을 실행합니다 — 권한 상승이 필요 없습니다. 스냅샷된 PATH를 포함한 .cmd 래퍼가 설정 로그 디렉터리에 저장됩니다. 작업 스케줄러를 사용할 수 없는 경우 Revka는 직접 백그라운드 스폰으로 폴백하고 나중에 revka service install을 실행하라는 안내를 출력합니다.

revka service install
revka service start
revka service status
revka service logs --follow
revka service uninstall

로그는 <config_dir>/logs/daemon.stdout.log와 daemon.stderr.log에 기록됩니다. revka service logs --follow는 PowerShell Get-Content -Wait를 사용합니다.

로그 로테이션

revka service start 전에 데몬 로그가 20 MB를 초과하면 로테이션됩니다. 최대 5개의 로테이션 사본(daemon.stdout.log.1부터 .5까지)이 유지되며, 이름 변경 전 가장 오래된 파일이 삭제됩니다. 로그는 Homebrew var/revka/logs/ 디렉터리 또는 <config_dir>/logs/에 저장됩니다.

참고

로테이션은 service start 시에만 트리거되며, 데몬이 계속 실행되는 동안에는 발생하지 않습니다. 장기 실행 서비스는 다음 재시작 시 로테이션됩니다.

빠른 시작: 서비스로 설치하고 실행하기

1. 서비스를 설치합니다. init 시스템은 자동으로 감지됩니다.

   revka service install

2. 시작합니다.

   revka service start

3. 정상 동작을 확인합니다. 서비스 상태와 공개 헬스 엔드포인트를 확인합니다.

   revka service status
   curl http://127.0.0.1:42617/health

4. 클라이언트를 페어링합니다. 페어링 코드를 확인하고 토큰으로 교환합니다.

   revka gateway get-paircode
   revka pair token --code 123456

확인 및 문제 해결

• 라이브니스. GET /health는 페어링 상태와 컴포넌트 스냅샷을 포함한 200을 반환하며 인증이 필요 없습니다 — 로드 밸런서에 적합합니다. revka status --format exit-code는 정상 시 0, 그렇지 않으면 1을 종료 코드로 반환합니다(Docker HEALTHCHECK의 표준 방식). 구조화된 진단을 위해 revka doctor를 실행하세요.
• 서비스가 시작되지 않음 (Windows). revka service status는 데몬 상태 파일도 확인합니다. 45초 이내의 상태 파일이 있으면 데몬이 이미 실행 중인 것입니다.
• 로그에 반복적인 재시작. 컴포넌트가 계속 실패하여 슈퍼바이저가 점점 늘어나는 백오프로 재시작하고 있습니다. 기록된 마지막 오류를 확인하고 reliability.channel_max_backoff_secs를 조정하세요.
• 다른 기기에서 게이트웨이에 접근할 수 없음. 기본 바인딩은 루프백 전용입니다. allow_public_bind = true를 설정하거나 터널로 프론팅하세요.
• 페어링 입력이 코드를 거부함. 코드는 일회용입니다. revka gateway get-paircode --new로 교체한 후 다시 시도하세요.

다음 단계

백그라운드 서비스로 실행하기 launchd, systemd, OpenRC, Windows 작업 스케줄러에 대한 OS별 서비스 설정.

대시보드 실행하기 게이트웨이를 시작하고, 브라우저를 페어링하고, 웹 UI를 둘러봅니다.

페어링 및 인증 게이트웨이 페어링 전체 흐름, 기기 레지스트리, 베어러 토큰.

터널로 게이트웨이 노출하기 로컬호스트 게이트웨이를 공개 인터넷에서 안전하게 접근합니다.