설치

Revka는 단일 Rust 바이너리(revka)로 배포되어 Raspberry Pi부터 프로덕션 클라우드 클러스터까지 어디서든 실행됩니다. 이 페이지에서는 바이너리를 머신에 설치하는 모든 지원 방법을 설명합니다: 원라인 부트스트랩, 패키지 매니저(Homebrew, Scoop), Windows 설치 스크립트, 사전 빌드 릴리스 바이너리, 소스 빌드, Docker.

가장 빠른 방법을 원한다면 원클릭 부트스트랩을 사용하세요. 설치 후 온보딩 마법사를 실행하고 빠른 시작으로 이동하세요.

설치 방법 선택

대부분의 사용자는 Homebrew(macOS/Linux), Scoop 또는 setup.bat(Windows), 또는 install.sh 원라이너(Unix 계열)를 사용하면 됩니다. 소스 빌드는 컴파일 타임 기능이 필요한 경우에만 사용하고, Docker는 격리된 재현 가능한 런타임이 필요할 때 사용하세요.

리소스 요구사항

사전 빌드 바이너리는 요구사항이 거의 없어 바로 다운로드하여 실행할 수 있습니다. 소스 빌드는 더 많은 리소스가 필요합니다:

리소스	소스 빌드 최소 사양
RAM	2 GB (스왑 포함)
여유 디스크	6 GB
Rust 툴체인	1.87+

부트스트랩 설치 프로그램은 컴파일 전에 프리플라이트 검사로 이 조건을 확인합니다. REVKA_BOOTSTRAP_MIN_RAM_MB(기본값 2048)와 REVKA_BOOTSTRAP_MIN_DISK_MB(기본값 6144)로 임계값을 조정할 수 있습니다. Raspberry Pi 등 리소스가 제한된 기기에서는 컴파일을 건너뛰기 위해 --prefer-prebuilt(아래 참조)를 사용하는 것을 권장합니다.

원클릭 부트스트랩

install.sh는 전체 흐름을 자동화하는 POSIX 셸 설치 프로그램입니다: RAM/디스크를 확인하고, 선택적으로 Rust와 OS 컴파일러 툴체인을 설치하며, 소스에서 빌드하거나 검증된 사전 빌드 바이너리를 다운로드하고, revka onboard를 실행하며, 데몬을 시작할 수 있습니다. 가이드(대화형) 모드와 완전 비대화형 모드, Docker 우선 모드를 모두 지원합니다.

Remote one-liner

curl -fsSL https://raw.githubusercontent.com/KumihoIO/Revka/main/install.sh | bash

리포지토리 체크아웃 외부에서 실행하면 스크립트가 임시 워크스페이스를 클론하고, 빌드 및 설치 후 정리합니다.

Clone + local script

git clone https://github.com/KumihoIO/Revka.git
cd revka
./install.sh

보안이 중요한 환경에서는 스크립트를 실행하기 전에 검토할 수 있도록 이 방법을 사용하세요.

Fresh machine

./install.sh --install-system-deps --install-rust

빌드 전에 컴파일러 툴체인(sudo 필요할 수 있음)과 rustup을 통한 Rust를 설치합니다.

기본적으로 스크립트는 앱 전용이며 기존 Rust 툴체인이 있다고 가정합니다. 기본 동작은 다음과 같습니다:

cargo build --release --locked
cargo install --path . --force --locked

사전 빌드 바이너리 vs 소스 빌드

부트스트랩은 소스에서 컴파일(Cargo 기능 플래그 완전 제어)하거나 GitHub Releases에서 검증된 사전 빌드 바이너리를 가져올 수 있습니다(컴파일러 불필요, 훨씬 빠름).

./install.sh --prefer-prebuilt      # 바이너리 우선 다운로드, 실패 시 소스 빌드로 폴백
./install.sh --prebuilt-only        # 바이너리 전용 — 일치하는 에셋이 없으면 실패
./install.sh --force-source-build   # 사전 빌드 바이너리 사용 안 함

참고

소스 빌드는 컴파일 타임 통합(Matrix, 하드웨어, OpenTelemetry 등)을 선택할 수 있습니다. 사전 빌드 바이너리는 고정된 기능 세트로 빌드됩니다. 전체 목록은 Cargo 기능 플래그를 참조하세요.

비대화형 설정

CI 및 스크립트 부트스트랩에 이상적으로, 프롬프트 없이 온보딩이 실행되도록 프로바이더와 API 키를 미리 설정합니다:

./install.sh --api-key "sk-..." --provider openrouter

# Or via environment variables
REVKA_API_KEY="sk-..." REVKA_PROVIDER="openrouter" ./install.sh

install.sh 플래그

플래그	용도
--guided / --no-guided	대화형 모드 강제 켜기/끄기
--install-system-deps	OS 컴파일러/빌드 툴체인 설치
--install-rust	없는 경우 rustup을 통해 Rust 설치
--prefer-prebuilt	사전 빌드 바이너리 우선 다운로드, 소스로 폴백
--prebuilt-only	바이너리 전용; 소스 폴백 없음
--force-source-build	사전 빌드 경로 완전 비활성화
--docker	Docker/Podman 부트스트랩 모드
--skip-build	(Docker 모드) 로컬 이미지 재사용 또는 GHCR에서 풀
--skip-install	빌드만; 바이너리 설치 안 함
--api-key <key>	API 키 프롬프트 건너뜀
--provider <id>	프로바이더 이름 (기본값: openrouter)
--model <id>	모델 ID 재정의
--cargo-features <list>	소스 빌드용 추가 Cargo 기능 플래그
--skip-onboard	프로바이더/API 키 설정 건너뜀
--install-sidecars / --skip-sidecars	Python MCP 사이드카 설치 제어
--with-session-manager	Node.js Session Manager 사이드카도 설치

유용한 환경 변수: REVKA_API_KEY, REVKA_PROVIDER, REVKA_MODEL, REVKA_CARGO_FEATURES, REVKA_CONTAINER_CLI, REVKA_DOCKER_DATA_DIR, REVKA_DOCKER_IMAGE, REVKA_BOOTSTRAP_MIN_RAM_MB, REVKA_BOOTSTRAP_MIN_DISK_MB, REVKA_SKIP_VERIFY.

전체 목록을 보려면 ./install.sh --help를 실행하세요.

팁

install.sh(및 setup.bat)는 소스 체크아웃이 있고 런처가 없을 때 Kumiho 및 Operator Python MCP 사이드카를 ~/.revka/ 아래에 자동으로 설치합니다. --skip-sidecars로 건너뛰거나 나중에 설치할 수 있습니다 — Python MCP 사이드카 설치를 참조하세요.

사전 빌드 바이너리 및 서명 검증

부트스트랩(및 revka update)은 플랫폼을 감지하고 GitHub Releases에서 일치하는 릴리스 에셋을 다운로드합니다.

지원 타겟 목록

타겟 트리플	플랫폼
x86_64-unknown-linux-gnu	Linux x86-64
aarch64-unknown-linux-gnu	Linux ARM64 (Raspberry Pi 4/5, 64비트)
armv7-unknown-linux-gnueabihf	Linux ARMv7 (Raspberry Pi 2/3)
arm-unknown-linux-gnueabihf	Linux ARMv6
x86_64-apple-darwin	macOS Intel
aarch64-apple-darwin	macOS Apple Silicon
aarch64-linux-android	Android ARM64 (Termux)

musl / Alpine

사전 빌드 바이너리는 아직 musl/Alpine용으로 게시되지 않았습니다. 해당 시스템에서는 설치 프로그램이 소스 빌드로 폴백하며, --prebuilt-only는 즉시 실패합니다.

검증

다운로드된 모든 아카이브는 동일한 릴리스에 게시된 SHA256SUMS 파일과 대조하여 검증됩니다. cosign이 설치된 경우 설치 프로그램은 GitHub OIDC 아이덴티티에 대해 SHA256SUMS의 키리스 서명(SHA256SUMS.sig + SHA256SUMS.pem)도 검증합니다:

• Issuer: https://token.actions.githubusercontent.com
• Identity: KumihoIO/Revka 릴리스 워크플로우

cosign이 없는 경우 SHA256 체크섬은 여전히 적용되며 서명 검증은 안내 메시지와 함께 건너뜁니다. 모든 검증을 우회하려면(권장하지 않음) REVKA_SKIP_VERIFY=1로 설정하세요.

Homebrew (macOS / Linuxbrew)

macOS와 Linux에서 가장 간단한 방법:

brew install revka
brew upgrade revka
brew uninstall revka

Homebrew는 바이너리를 /opt/homebrew/bin/revka(Apple Silicon) 또는 /usr/local/bin/revka(Intel)에 배치하고, 런타임 데이터로 var/revka/ 디렉터리를 사용하여 launchd 서비스로 실행할 수 있습니다:

brew services start revka

참고

Homebrew 설치는 ~/.revka/ 대신 Homebrew 프리픽스(예: /opt/homebrew/var/revka/) 아래에 설정과 워크스페이스 데이터를 저장합니다. revka onboard는 작성하는 설정이 서비스 설정 경로와 다를 경우 경고를 표시합니다. Homebrew 설치와 Cargo 설치가 모두 있는 경우 which revka 및 revka --version을 실행하여 어떤 바이너리가 활성화되어 있는지 확인하세요. macOS 업데이트 및 제거를 참조하세요.

Windows

setup.bat

리포지토리 루트에서 대화형 스크립트가 환경을 자동으로 감지하고 설치를 안내합니다:

setup.bat

모드 플래그로 메뉴를 건너뜁니다:

플래그	빌드
--prebuilt	사전 컴파일된 바이너리 다운로드 (가장 빠름)
--minimal	기본 기능만
--standard	Matrix + Lark/Feishu + Postgres
--full	모든 기능

setup.bat은 RAM을 확인하고(2 GB 미만이면 경고), Rust 여부를 확인하며, cargo install을 호출합니다. x86_64-pc-windows-msvc를 타겟으로 합니다.

Scoop

scoop bucket add revka https://github.com/KumihoIO/scoop-revka
scoop install revka

Manual build

rustup target add x86_64-pc-windows-msvc
cargo build --release --locked --features channel-matrix,channel-lark --target x86_64-pc-windows-msvc
copy target\x86_64-pc-windows-msvc\release\revka.exe %USERPROFILE%\.revka\bin\

사전 요구사항

요구사항	필수 여부	비고
Git	필수	git-scm.com/download/win
Rust 1.87+	필수	setup.bat이 없으면 자동 설치
Visual Studio Build Tools	필수 (소스 빌드)	C++ 워크로드 — MSVC 링커에 필요
Node.js	선택	소스에서 웹 대시보드를 빌드할 때만 필요

Visual Studio Build Tools

Windows에서 소스 빌드는 Visual Studio Build Tools에 포함된 MSVC 링커가 필요합니다. C++ 워크로드가 포함된 Visual Studio가 없는 경우:

1. visualstudio.microsoft.com/visual-cpp-build-tools에서 다운로드합니다.
2. “C++를 사용한 데스크톱 개발” 워크로드를 선택합니다.
3. 설치 후 터미널을 재시작합니다.

링커 오류로 빌드가 실패하면 이 워크로드 누락이 거의 항상 원인입니다. cargo build가 메모리 부족으로 실패하면 setup.bat --prebuilt를 사용하여 바이너리를 다운로드하세요.

설치 후 작업 (Windows)

1. PATH 변경이 적용되도록 터미널을 재시작합니다.
2. Revka를 초기화합니다: revka onboard
3. %USERPROFILE%\.revka\config.toml에서 API 키를 설정합니다.
4. http://127.0.0.1:42617에서 게이트웨이 + 대시보드를 시작합니다: revka gateway (또는 revka daemon으로 전체 런타임 실행).

참고

Revka를 지속적인 Windows 서비스로 실행하려면 작업 스케줄러를 사용합니다 — revka gateway, daemon & service를 참조하세요.

소스 빌드 (모든 플랫폼)

컴파일 타임 기능이 필요한 경우 Cargo로 직접 빌드하세요. --locked로 재현 가능한 빌드가 가능하며, --features로 통합을 선택합니다:

cargo build --release --locked --features hardware,channel-matrix
cargo install --path . --force --locked

리소스가 제한된 머신에서는 메모리 부족 오류를 방지하기 위해 병렬성을 제한하세요:

CARGO_BUILD_JOBS=1 cargo build --release --locked

전체 기능 목록은 Cargo 기능 플래그 및 ADR을 참조하고, ARM/임베디드 빌드(--features hardware,peripheral-rpi)는 네트워크 배포, Raspberry Pi & 프록시를 참조하세요.

Docker

GitHub Container Registry에 두 가지 멀티아치 이미지가 게시되어 있습니다:

• ghcr.io/kumihoio/revka:latest — distroless(셸 없음), 최소 공격 표면. 엔트리포인트: revka daemon.
• ghcr.io/kumihoio/revka:debian — bash, git, curl이 포함된 Debian bookworm-slim. 에이전트에 셸 기반 도구가 필요할 때 사용하세요.

docker run -d \
  -e API_KEY=sk-... \
  -e PROVIDER=openrouter \
  -v revka-data:/revka-data \
  -p 42617:42617 \
  ghcr.io/kumihoio/revka:latest

주요 환경 변수: API_KEY(또는 REVKA_API_KEY), PROVIDER(기본값 openrouter), REVKA_MODEL, REVKA_GATEWAY_PORT(기본값 42617), REVKA_ALLOW_PUBLIC_BIND=true(컨테이너 네트워킹에 필요). 컨테이너는 UID 65534(nobody)로 실행되며 HOME=/revka-data입니다.

표준 활성 상태 확인(이미지 HEALTHCHECK에서도 사용):

docker exec revka revka status --format=exit-code

주의

distroless 이미지는 셸이 없으므로 에이전트 셸 도구(ls, git 등)가 실패합니다 — 해당 도구가 필요하면 :debian을 사용하세요. 일부 ARM64 플랫폼에서 distroless 변형이 즉시 종료될 수 있으므로 이 경우에도 :debian으로 폴백하세요.

부트스트랩 기반 Docker 플로우:

./install.sh --docker
REVKA_CONTAINER_CLI=podman ./install.sh --docker   # Podman

로컬 이미지를 빌드하고 컨테이너에서 온보딩을 실행하며, ./.revka-docker에 데이터를 유지합니다(REVKA_DOCKER_DATA_DIR로 재정의). Podman 실행 시 --userns keep-id와 :Z 볼륨 레이블이 자동으로 적용됩니다.

컨테이너 재시작

컨테이너를 재시작하기 위해 install.sh를 다시 실행하지 마세요 — 이미지를 재빌드하고 온보딩을 다시 실행합니다. 대신 유지된 데이터 디렉터리를 대상으로 docker start / docker compose up -d를 사용하세요.

Compose, 원클릭 PaaS 템플릿(Coolify, Dokploy, EasyPanel), 전체 컨테이너 레퍼런스는 Docker, Compose & 원클릭 PaaS를 참조하세요.

설치 확인

설치 방법에 관계없이 바이너리가 작동하고 환경이 정상인지 확인합니다:

revka --version
revka doctor          # structured config / workspace / environment diagnostics
revka self-test       # full diagnostic suite
revka self-test --quick   # offline checks only

revka doctor는 설정 파일, 프로바이더, API 키, 워크스페이스, 사이드카, CLI 도구를 검증합니다 — 문제가 생기면 가장 먼저 실행하세요. revka doctor, status & self-test를 참조하세요.

다음 단계

온보딩 마법사 revka onboard를 실행하여 프로바이더, 모델, 채널, 메모리 백엔드를 설정합니다.

빠른 시작 게이트웨이를 시작하고, 첫 메시지를 보내고, 감사 체인 검증을 확인합니다.

Python MCP 사이드카 설치 바이너리와 함께 필요한 Kumiho 및 Operator MCP 사이드카를 설정합니다.

Docker, Compose & 원클릭 PaaS 프로덕션 컨테이너 배포, Compose, Coolify/Dokploy/EasyPanel 템플릿.