백그라운드 서비스로 실행

revka service는 revka daemon을 OS가 관리하는 지속적인 백그라운드 서비스로 실행합니다. 이를 통해 로그인 또는 부팅 시 자동으로 시작되고 장애 발생 시 재시작됩니다. install, start, stop, restart, status, logs, uninstall이라는 단일 명령 세트가 각 플랫폼에 맞는 네이티브 메커니즘을 구동합니다. macOS에서는 launchd 에이전트, Linux에서는 systemd 사용자 유닛 또는 OpenRC init 스크립트, Windows에서는 Windows 작업 스케줄러 작업이 사용됩니다.

Revka가 재부팅이나 크래시 후에도 터미널 없이 동작하기를 원한다면 이 페이지를 참조하세요. 명령어 수준의 레퍼런스(플래그, 서브커맨드, 페어링)는 revka gateway, daemon & service를 참고하고, 데몬 자체와 컴포넌트 수퍼바이저에 대해서도 같은 페이지를 확인하세요.

init 시스템 선택 방식

revka service는 플랫폼과 Linux의 경우 init 시스템을 자동으로 감지합니다.

플랫폼	메커니즘	아티팩트
macOS	launchd 에이전트	~/Library/LaunchAgents/com.revka.daemon.plist
Linux (systemd)	systemd 사용자 유닛	~/.config/systemd/user/revka.service
Linux (OpenRC / Alpine)	OpenRC init 스크립트	/etc/init.d/revka
Windows	예약된 작업	Revka Daemon이라는 이름의 작업

Linux 감지는 기본적으로 거부 방식으로 동작합니다. /run/systemd/system이 존재하면 systemd를 선택하고, 그렇지 않으면 /run/openrc가 존재하고 OpenRC 바이너리(/sbin/openrc-run 또는 rc-service)가 있을 경우 OpenRC를 선택합니다. 둘 다 찾지 못하면 오류를 반환합니다. --service-init으로 강제 지정할 수 있습니다.

revka service --service-init systemd install
revka service --service-init openrc install

플래그	값	기본값	설명
--service-init	auto, systemd, openrc	auto	특정 Linux init 시스템을 강제 지정합니다. 서브커맨드 앞에 전달해야 합니다.

명령어

동일한 서브커맨드가 모든 OS에서 동작합니다.

revka service install      # generate and register the unit / plist / task
revka service start        # start the service (rotates logs first)
revka service stop         # stop the running service
revka service restart      # stop then start
revka service status       # report whether the daemon is running
revka service logs         # tail the daemon logs (default: last 50 lines)
revka service logs -n 100 --follow
revka service uninstall    # remove the unit / plist / task

서브커맨드	목적
install	플랫폼 아티팩트를 생성하고 등록하며, systemd의 경우 로그인 시 시작되도록 활성화합니다.
start	서비스를 시작합니다. 시작 전에 데몬 로그를 교체합니다(20 MB 초과 시).
stop	실행 중인 서비스를 중지합니다.
restart	중지 후 재시작합니다.
status	서비스 상태를 보고합니다. 폴백으로 45초 이내의 데몬 상태 파일도 확인합니다.
logs	데몬 로그를 tail합니다. -n / --lines <N>으로 줄 수를 설정하고(기본값 50), -f / --follow로 tail -f처럼 새 출력을 스트리밍합니다.
uninstall	플랫폼 아티팩트를 제거합니다.

빠른 시작

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

   revka service install

2. 서비스를 시작합니다.

   revka service start

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

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

참고

기본 게이트웨이 바인딩은 루프백 전용(127.0.0.1:42617)입니다. 서비스로 관리되는 데몬에 다른 머신에서 접근하려면 allow_public_bind = true를 설정하거나 터널을 통해 접근하세요. 네트워크 배포, Raspberry Pi & 프록시 및 터널로 게이트웨이 노출을 참조하세요.

플랫폼별 설정

macOS (launchd)

launchd 에이전트

revka service install은 launchd 에이전트 plist를 ~/Library/LaunchAgents/com.revka.daemon.plist에 작성하고, launchctl load -w와 launchctl start com.revka.daemon으로 로드합니다. 에이전트는 RunAtLoad와 KeepAlive 모두 true로 설정하여 revka daemon을 실행하므로 로그인 시 시작되고 종료 시 재시작됩니다.

생성되는 plist는 다음과 같습니다.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.revka.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/revka</string>
    <string>daemon</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>SoftResourceLimits</key>
  <dict>
    <key>NumberOfFiles</key>
    <integer>4096</integer>
  </dict>
  <key>HardResourceLimits</key>
  <dict>
    <key>NumberOfFiles</key>
    <integer>8192</integer>
  </dict>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key>
    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:...</string>
  </dict>
  <key>StandardOutPath</key>
  <string>/Users/you/.revka/logs/daemon.stdout.log</string>
  <key>StandardErrorPath</key>
  <string>/Users/you/.revka/logs/daemon.stderr.log</string>
</dict>
</plist>

키	값	이유
RunAtLoad / KeepAlive	true	로그인 시 시작하고 종료 시 재시작합니다.
SoftResourceLimits → NumberOfFiles	4096	파일 디스크립터 소프트 한도입니다. launchd 기본값은 256으로, MCP 사이드카를 생성하는 에이전트는 이를 쉽게 소진합니다.
HardResourceLimits → NumberOfFiles	8192	하드 상한선입니다. 운영자는 재설치 없이 런타임에 ulimit -n으로 이 값까지 높일 수 있습니다.
EnvironmentVariables → PATH	직접 지정	데몬이 하위 프로세스 도구를 실행할 수 있도록 명시적인 PATH를 설정합니다.

revka service install
revka service start
revka service logs --follow

Homebrew 설치

Revka가 Homebrew로 설치된 경우, revka service install이 이를 자동으로 감지하고 plist를 조정합니다.

• 로그는 ~/.revka/logs/ 대신 <brew_prefix>/var/revka/logs/에 저장됩니다.
• plist에 REVKA_CONFIG_DIR 환경 키와 Homebrew var/revka 디렉터리를 가리키는 WorkingDirectory가 추가되므로, brew upgrade 후에도 설정과 워크스페이스가 유지됩니다.

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

brew services start revka

전체 Homebrew 라이프사이클은 macOS 업데이트 & 제거를 참조하세요.

Linux (systemd)

systemd 사용자 유닛

systemd 호스트에서 revka service install은 사용자 유닛을 ~/.config/systemd/user/revka.service에 작성한 후, systemctl --user daemon-reload와 systemctl --user enable revka.service를 실행합니다. root 권한이 필요하지 않습니다.

생성되는 유닛:

[Unit]
Description=Revka daemon
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/revka daemon
Restart=always
RestartSec=3
Environment=HOME=%h
LimitNOFILE=4096:8192
Environment="PATH=/home/you/.cargo/bin:/home/you/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:..."
PassEnvironment=DISPLAY XDG_RUNTIME_DIR

[Install]
WantedBy=default.target

지시자	값	이유
Restart / RestartSec	always / 3	종료 후 3초 뒤에 데몬을 재시작합니다.
LimitNOFILE	4096:8192	파일 디스크립터 소프트:하드 한도입니다. systemd 사용자 유닛의 기본 소프트 한도는 1024인 경우가 많으며, MCP 사이드카가 이를 소진합니다.
Environment="PATH=..."	직접 지정	systemd 사용자 서비스는 ~/.cargo/bin과 ~/.local/bin이 제외된 최소한의 PATH로 시작되므로, 이 설정이 없으면 하위 프로세스 도구 실행 시 “No such file or directory” 오류가 발생합니다.
PassEnvironment	DISPLAY XDG_RUNTIME_DIR	헤드리스 브라우저가 동작할 수 있도록 세션에서 상속합니다.
Environment=HOME=%h	사용자 홈	헤드리스 브라우저가 프로파일/캐시 디렉터리를 생성할 수 있도록 합니다.

revka service install
revka service start
revka service status
revka service logs -n 100 --follow

내부적으로 이 명령들은 systemctl --user start|stop|restart|is-active revka.service에 매핑되며, logs는 journalctl --user -u revka.service를 실행합니다.

참고

systemd 사용자 유닛은 활성 로그인 세션이 있는 동안에만 실행됩니다. 로그인 없이 부팅 시에도 서비스를 유지하려면 lingering을 활성화하세요.

loginctl enable-linger $USER

Alpine / OpenRC

OpenRC init 스크립트

OpenRC는 시스템 전체에 적용되며 root 전용입니다. 서비스 명령을 sudo와 함께 실행하세요.

sudo revka service install        # auto-detects OpenRC on Alpine
sudo rc-update add revka default  # enable at boot
sudo rc-service revka start

install은 /etc/init.d/revka를 작성하고, revka:revka 시스템 사용자를 생성합니다(Alpine: addgroup -S / adduser -S -s /sbin/nologin; 기타 배포판: useradd -r -s /sbin/nologin). 또한 /etc/revka/, /var/lib/revka/, /var/log/revka/의 소유권을 설정하고, 최초 설치 시 기존 ~/.revka 설정을 /etc/revka로 마이그레이션합니다($SUDO_USER에서 해석).

생성되는 init 스크립트:

#!/sbin/openrc-run

name="revka"
description="Revka daemon"

command="/usr/local/bin/revka"
command_args="--config-dir /etc/revka daemon"
command_background="yes"
command_user="revka:revka"
pidfile="/run/${RC_SVCNAME}.pid"
umask 027
output_log="/var/log/revka/access.log"
error_log="/var/log/revka/error.log"

export HOME="/var/lib/revka"
rc_ulimit="-n 4096"
export PATH="/usr/local/bin:/usr/bin:/bin:..."

depend() {
    need net
    after firewall
}

start_pre() {
    checkpath --directory --owner revka:revka --mode 0750 /var/lib/revka
}

설정	값	이유
command_user	revka:revka	데몬이 비특권 시스템 사용자(UID < 1000, 셸 /sbin/nologin)로 실행됩니다.
rc_ulimit	-n 4096	OpenRC가 시작 전에 ulimit -n을 호출하여 MCP 사이드카가 FD 한도를 소진하지 않도록 합니다. 단일 값으로 별도의 하드 한도는 없습니다.
command_background	yes	OpenRC가 pidfile을 통해 백그라운드 프로세스를 감독합니다.
umask	027	데몬이 작성하는 파일에 대한 제한적인 기본 권한입니다.

revka service status / start / stop / restart는 rc-service revka <action>에 매핑되며, revka service logs는 /var/log/revka/error.log를 tail합니다(access.log로 폴백).

주의

UID ≥ 1000이거나 nologin이 아닌 셸을 가진 기존 revka 사용자가 있으면 명확한 오류와 함께 올바르게 재생성할 deluser/adduser(또는 userdel/useradd) 명령이 출력됩니다. 이 검사는 데몬이 실제 대화형 계정으로 실행되는 것을 방지합니다.

Windows (Task Scheduler)

예약된 작업

Windows에서 revka service install은 schtasks /SC ONLOGON을 통해 **Revka Daemon**이라는 예약된 작업을 등록하므로 사용자 로그온 시 데몬이 실행됩니다. 관리자 권한이 필요하지 않습니다. 스냅샷된 PATH가 포함된 .cmd 래퍼 스크립트가 설정 로그 디렉터리에 배치되며, 작업은 이 스크립트를 실행합니다.

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

항목	값
작업 이름	Revka Daemon
트리거	/SC ONLOGON (사용자 로그온 시)
stdout 로그	<config_dir>\logs\daemon.stdout.log
stderr 로그	<config_dir>\logs\daemon.stderr.log
로그 follow	PowerShell Get-Content -Wait

작업 스케줄러를 사용할 수 없는 경우, revka service start는 revka daemon을 직접 백그라운드로 실행(분리됨, 콘솔 창 없음)하는 방식으로 폴백하며, 나중에 로그온 자동 시작을 복원하려면 revka service install을 다시 실행하라는 안내를 출력합니다.

참고

Windows에서 revka service status는 데몬 상태 파일도 참조합니다. 상태 파일이 45초 이내에 갱신되었다면 예약된 작업을 조회할 수 없어도 데몬이 이미 실행 중임을 의미합니다.

로그 교체

데몬 로그(daemon.stdout.log와 daemon.stderr.log)는 각 revka service start 전에 교체됩니다.

• 로그 파일이 20 MB를 초과할 때만 교체가 실행됩니다.
• 교체된 복사본은 최대 5개까지 유지되며, daemon.stdout.log.1부터 daemon.stdout.log.5까지 이름이 지정됩니다(stderr도 동일).
• 가장 오래된 복사본은 삭제되고, 나머지는 번호가 하나씩 올라가며, 현재 파일은 .1이 됩니다.

Revka가 Homebrew로 설치된 경우 로그는 Homebrew var/revka/logs/ 디렉터리에, 그렇지 않으면 <config_dir>/logs/에 저장됩니다.

상수	값	의미
교체 임계값	20 MB	이보다 작은 로그 파일은 그대로 유지됩니다.
보관 파일 수	5	스트림당 유지되는 교체된 복사본의 최대 개수입니다.

참고

교체는 service start 시에만 발생하며, 데몬이 계속 실행 중일 때는 발생하지 않습니다. 오래 실행된 서비스는 다음 재시작 시 로그가 교체되므로, 재시작 사이에 현재 로그가 20 MB를 초과할 수 있습니다. systemd 호스트에서는 데몬 출력이 저널에도 캡처됩니다. revka service logs(journalctl --user -u revka.service 호출)로 확인하세요.

동작 확인 및 문제 해결

• 생존 여부 확인. GET http://127.0.0.1:42617/health는 페어링 상태와 컴포넌트 스냅샷을 포함하여 200을 반환하며 인증이 필요하지 않습니다. revka status --format exit-code는 정상이면 0, 아니면 1을 종료 코드로 반환합니다. 구조화된 진단을 위해 revka doctor를 실행하세요.
• 서비스가 시작되지 않음 (Windows). revka service status는 45초 이내의 데몬 상태 파일을 참조합니다. 예약된 작업을 사용할 수 없는 경우 Revka는 직접 실행 방식으로 폴백하므로, 로그온 자동 시작을 복원하려면 나중에 revka service install을 다시 실행하세요.
• 로그아웃 후 systemd 서비스가 중지됨. 사용자 유닛은 로그아웃 후에도 실행을 유지하려면 lingering이 필요합니다: loginctl enable-linger $USER.
• OpenRC 설치 중 사용자 확인 실패. UID ≥ 1000이거나 nologin이 아닌 셸을 가진 기존 revka 사용자는 거부됩니다. 오류 메시지에 출력된 명령으로 재생성하세요.
• 데몬이 하위 프로세스 도구를 찾지 못함. launchd plist, systemd 유닛, OpenRC 스크립트 모두 이 문제를 해결하기 위해 직접 지정된 PATH를 주입합니다. Revka 또는 해당 도구를 비표준 위치에 설치한 경우, 도구가 PATH에 포함된 후 서비스를 재설치하세요.
• 로그에서 재시작 루프 발생. 컴포넌트가 계속 실패하고 데몬 수퍼바이저가 점점 증가하는 백오프로 재시작을 반복합니다. 컴포넌트 수퍼바이저 레퍼런스를 확인하세요.

다음 단계

revka gateway, daemon & service 데몬, 서비스 서브커맨드, 페어링에 대한 명령어 수준 레퍼런스입니다.

런타임 모드, 어댑터 & 리소스 한도 네이티브 대 Docker 런타임, 파일 디스크립터 한도, 샌드박싱입니다.

Docker, Compose & 원클릭 PaaS OS 서비스 대신 컨테이너에서 Revka를 실행합니다.

업데이트, 런북 & 문제 해결 실행 중인 배포를 업데이트하고 일반적인 장애를 해결합니다.