revka install, update, migrate, completions & ACP

이 페이지에서는 실행 중인 Revka 인스턴스 주변에서 동작하는 라이프사이클 및 통합 명령을 다룹니다. Python MCP 사이드카 설치, 바이너리 최신 상태 유지, 다른 런타임에서의 마이그레이션, 컴패니언 데스크톱 앱 실행, 선택적 WASM 플러그인 관리, 셸 자동완성 생성, ACP stdio 프로토콜을 통한 Revka 노출 방법을 설명합니다.

이 명령들은 대부분 초기 설정 시 또는 정기적으로 한 번씩 실행하는 것으로, 일상적인 에이전트 루프에서는 사용하지 않습니다. 처음 설정하는 경우 설치와 온보딩 마법사를 먼저 참고하세요. 전체 명령 목록은 CLI 개요를 참고하세요.

revka install (사이드카)

revka install은 Revka의 Python MCP 사이드카인 Kumiho MCP 클라이언트(그래프 메모리)와 Operator MCP(워크플로우 및 오케스트레이션)를 프로비저닝합니다. 처음부터 완전히 설치하는 과정은 install.sh가 담당하며, CLI 명령은 현재 --sidecars-only 플래그가 필요합니다.

revka install --sidecars-only
revka install --sidecars-only --dry-run                  # preview actions (POSIX only)
revka install --sidecars-only --python /opt/homebrew/bin/python3
revka install --sidecars-only --with-session-manager
revka install --sidecars-only --from-source /path/to/Revka
revka install --sidecars-only --skip-kumiho --skip-operator

플래그	설명
--sidecars-only	필수. Kumiho + Operator Python MCP 사이드카를 설치합니다.
--skip-kumiho	Kumiho MCP 사이드카를 건너뜁니다.
--skip-operator	Operator MCP 사이드카를 건너뜁니다.
--with-session-manager	Node.js Session Manager 사이드카도 함께 설치합니다(npm 필요; 아래 비용 관련 주의사항 참고).
--dry-run	실행하지 않고 예정된 작업만 출력합니다(POSIX 전용).
--python <PATH>	자동 감지 대신 명시적인 Python 인터프리터를 사용합니다.
--from-source <REPO_PATH>	개발 모드: 내장 스냅샷 대신 로컬 저장소 체크아웃에서 operator-mcp를 설치합니다.

내부적으로 인스톨러는 Python 3를 감지하고, ~/.revka/kumiho/venv/와 ~/.revka/operator_mcp/venv/에 사이드카별 독립 가상 환경을 생성합니다. 그런 다음 kumiho[mcp]>=0.10.0과 kumiho_memory>=0.5.2 및 Operator MCP 패키지를 pip으로 설치하고, 런처 스크립트를 작성한 뒤 Operator 스킬을 ~/.revka/skills/에 동기화합니다. Operator MCP 소스는 컴파일 시점에 바이너리에 내장되므로 런타임에 별도로 다운로드하지 않습니다.

사이드카	런처	설정 키
Kumiho MCP	~/.revka/kumiho/run_kumiho_mcp.py	[kumiho].mcp_path
Operator MCP	~/.revka/operator_mcp/run_operator_mcp.py	[operator].mcp_path

참고

대부분의 경우 이 명령을 직접 실행할 필요가 없습니다. ensure_sidecars_ready는 revka agent 및 revka daemon 시작 시 자동으로 실행되며, 사이드카가 없으면 Revka가 대화형으로 설치를 안내합니다. 업데이트 시 런타임 상태 파일(.json, .jsonl, .db, venv/, session-manager/, runlogs/)은 보존됩니다.

주의

--with-session-manager는 인증 및 비용 모델을 변경합니다. Session Manager는 Claude Agent SDK를 사용하므로 ANTHROPIC_API_KEY가 필요하고 토큰당 과금 방식이 적용됩니다. 기본값(Session Manager 비활성화)은 claude --print + codex exec를 사용하는 서브프로세스 방식으로 대체되며, OAuth 기반으로 동작하여 스폰된 에이전트의 API 호출당 비용이 발생하지 않습니다.

사이드카 전체 설치 절차와 검증 명령은 Python MCP 사이드카 설치와 Kumiho 설정을 참고하세요.

revka update

revka update는 Revka의 자체 업데이트 명령입니다. GitHub Releases에서 대상 릴리스 바이너리를 다운로드하고, 검증한 뒤, 교체하며, 문제가 발생하면 자동으로 롤백합니다.

revka update                  # download and install the latest release
revka update --check          # check for an update without installing
revka update --force          # install without the confirmation prompt
revka update --version 0.6.0  # install a specific release

플래그	설명
--check	업데이트만 확인합니다. 현재 버전과 최신 버전을 출력하고 종료합니다.
--force	대화형 확인 프롬프트를 건너뜁니다.
--version <X.Y.Z>	최신 버전 대신 특정 릴리스를 대상으로 지정합니다.

6단계 파이프라인

업데이트는 고정된 파이프라인으로 실행되며, 어느 단계에서든 실패 시 자동으로 롤백됩니다.

1. 사전 확인(Preflight) — 대상 버전을 결정하고 바이너리에 쓰기 권한이 있는지 확인합니다.
2. 다운로드(Download) — 현재 플랫폼에 맞는 릴리스 아티팩트를 가져옵니다.
3. 백업(Backup) — 현재 바이너리를 복원 가능하도록 별도로 복사합니다.
4. 검증(Validate) — 다운로드를 검증합니다: 최소 파일 크기, 바이너리의 CPU 아키텍처(ELF/Mach-O 헤더)가 호스트와 일치하는지, 그리고 --version을 실행하여 revka로 식별되는지 확인합니다. (revka update에서는 SHA256이나 서명 검증을 수행하지 않습니다.)
5. 교체(Swap) — 실행 중인 바이너리를 새 것으로 교체합니다.
6. 스모크 테스트(Smoke test) — 새 바이너리를 실행하여 정상 동작을 확인합니다. 실패 시 백업을 복원합니다.

팁

패키지 관리자를 통해 Revka를 설치한 경우, revka update 대신 해당 관리자의 업그레이드 방법을 사용하는 것이 좋습니다. 예를 들어 macOS에서는 brew upgrade revka, Windows에서는 scoop update revka를 사용하세요. 업데이트, 런북 및 문제 해결과 macOS 업데이트 및 제거를 참고하세요.

revka migrate

revka migrate는 다른 에이전트 런타임의 메모리와 설정을 Revka로 가져옵니다. 현재 버전에서는 OpenClaw만 지원합니다.

revka migrate openclaw
revka migrate openclaw --source /custom/openclaw/workspace
revka migrate openclaw --dry-run

플래그	설명
--source <PATH>	가져올 OpenClaw 워크스페이스 경로입니다. 기본값: ~/.openclaw/workspace.
--dry-run	데이터를 쓰지 않고 소스 워크스페이스를 검증하고 마이그레이션 결과를 미리 확인합니다.

실제로 커밋하기 전에 항상 --dry-run을 먼저 실행하여 소스가 올바르게 감지되는지 확인하고 가져올 내용을 검토하세요.

revka desktop

revka desktop은 로컬 게이트웨이에 연결하는 메뉴바/시스템 트레이 클라이언트인 컴패니언 Tauri 데스크톱 앱을 실행하거나 설치합니다.

revka desktop             # launch the installed desktop app
revka desktop --install   # open the download page to install it

플래그	설명
--install	다운로드 페이지를 엽니다. macOS/Linux에서는 브라우저로 https://www.kumiho.io/download를 엽니다.

--install 없이 실행하면 Revka는 데스크톱 바이너리를 다음 순서로 검색합니다: /Applications/Revka.app(macOS), CLI 바이너리와 같은 디렉터리, ~/.cargo/bin/, ~/.local/bin/, 그리고 PATH. 찾을 수 없으면 종료 코드 1로 종료됩니다. 앱은 http://127.0.0.1:42617/_app/의 로컬 게이트웨이에 연결되므로, 게이트웨이가 별도로 실행 중이어야 합니다(revka gateway 또는 revka daemon).

전체 기능 소개는 데스크톱 앱 페이지를 참고하세요.

revka plugin (기능 게이트)

revka plugin은 WASM 플러그인을 관리합니다. plugins-wasm Cargo 기능으로 빌드된 바이너리에서만 제공되며, 표준 빌드에서는 이 명령이 노출되지 않습니다.

revka plugin list
revka plugin install /path/to/plugin
revka plugin remove my-plugin
revka plugin info my-plugin

서브커맨드	인자	설명
list	—	설치된 플러그인 목록을 표시합니다.
install	<source>	로컬 플러그인 디렉터리(manifest.toml 포함) 또는 로컬 매니페스트 경로에서 설치합니다.
remove	<name>	이름으로 플러그인을 제거합니다.
info	<name>	이름, 버전, 설명, 기능, 권한, WASM 경로를 표시합니다.

플러그인 형식과 기능 모델에 대한 자세한 내용은 WASM 플러그인과 Cargo 기능 플래그 및 ADR을 참고하세요.

revka completions

revka completions는 지정한 셸에 대한 자동완성 스크립트를 stdout으로 출력합니다. 출력은 stdout 전용으로 설계되어 로깅이나 설정 로딩이 발생하지 않으므로, 셸 초기화 파일에서 직접 source해도 안전합니다.

revka completions <shell>

위치 인자 <shell>은 필수이며 bash, fish, zsh, powershell, elvish 중 하나여야 합니다.

셸별 설치 방법

# bash — source on the fly, or persist to your profile
source <(revka completions bash)
revka completions bash > ~/.local/share/bash-completion/completions/revka

# zsh — write to a directory on your $fpath
revka completions zsh > ~/.zfunc/_revka

# fish
revka completions fish > ~/.config/fish/completions/revka.fish

# PowerShell — append to your profile
revka completions powershell | Out-String | Invoke-Expression

# elvish
revka completions elvish >> ~/.config/elvish/rc.elv

revka acp

revka acp는 ACP(Agent Control Protocol) 서버를 시작합니다. IDE 및 도구 통합을 위한 stdin/stdout 기반 JSON-RPC 2.0 인터페이스로, revka agent와 동일한 에이전트 루프를 멀티 세션 RPC 및 스트리밍 방식으로 노출합니다.

revka acp
revka acp --max-sessions 5
revka acp --session-timeout 7200

플래그	기본값	설명
--max-sessions <N>	10	최대 동시 세션 수입니다.
--session-timeout <SECS>	3600	세션 비활성 타임아웃(초 단위)입니다.

프로토콜

ACP는 stdio를 통해 프레이밍된 JSON-RPC 2.0입니다. 지원되는 메서드는 다음과 같습니다.

메서드	목적
initialize	핸드셰이크 및 기능 협상입니다.
session/new	새 에이전트 세션을 생성합니다.
session/prompt	세션에 프롬프트를 전송합니다.
session/stop	에이전트 세션을 종료(제거)합니다.

에이전트 추론, 도구 호출, 콘텐츠는 실시간으로 JSON-RPC 알림 형태로 클라이언트에 스트리밍됩니다. 전송 수단이 stdio이므로 호스트 프로세스(IDE 확장 또는 에디터)가 revka acp를 자식 프로세스로 실행하고 파이프를 통해 통신합니다. Claude Code 확장과 커스텀 IDE 통합이 이 방식으로 Revka를 구동합니다.

참고

ACP는 stdio를 통해 에이전트를 직접 실행하므로 게이트웨이가 필요하지 않습니다. 동일한 에이전트에 HTTP/WebSocket으로 접근하려면 revka gateway를 실행하고 Gateway API를 사용하세요.

참고 항목

• revka onboard — 워크스페이스 및 설정 초기화
• revka gateway, daemon & service — HTTP/WebSocket 런타임 실행
• revka doctor, status & self-test — 설치 전체 검증
• Revka를 MCP 서버로 사용 — 다른 MCP 클라이언트에 Revka 도구 노출