Revka 작동 방식

Revka는 단일 바이너리(revka)로 제공되는 Rust 기반, 감사 우선(audit-first) 에이전트 런타임입니다. 이 바이너리에는 REST + WebSocket 게이트웨이, React 대시보드, 크론 스케줄러, 채널 슈퍼바이저, CLI가 내장되어 있으며, 두 개의 Python MCP 사이드카(Kumiho 메모리 및 오퍼레이터)와 선택적 클라우드 에이전트를 조율합니다. 이 페이지에서는 각 레이어의 역할, 실행 위치, 그리고 메시지가 에이전트 턴으로 처리되는 과정을 설명합니다.

채널, 프로바이더, 워크플로우를 구성하기 전에 이 페이지를 한 번 읽어두세요 — 이후 문서 전반에서 전제로 삼는 멘탈 모델을 제공합니다. 바로 시작하고 싶다면 설치와 빠른 시작을 먼저 진행한 후 돌아오세요.

아키텍처 개요

Revka는 레이어 구조로 설계되어 있습니다. 각 레이어는 명확한 역할과 경계를 가집니다.

게이트웨이 런타임

Axum HTTP 서버입니다. REST API, WebSocket 및 SSE 전송, 내장 대시보드, 웹훅 인그레스, 인프로세스 MCP 서버를 호스팅합니다. 기본 바인딩 주소는 http://127.0.0.1:42617입니다.

채널 슈퍼바이저

에이전트를 메시징 플랫폼(Telegram, Discord, Slack, Matrix 등)에 연결합니다. 게이트웨이, 하트비트, 크론과 함께 데몬 내부에서 실행됩니다.

오퍼레이터 + Kumiho 사이드카

두 개의 Python MCP 서버입니다. 오퍼레이터는 서브 에이전트, 팀, 워크플로우를 조율하고, Kumiho는 영속적 그래프 메모리 백엔드입니다.

보안 정책

심층 방어(defence-in-depth) 모델로, 자율성 수준, 명령어 허용 목록, 경로 샌드박싱, OTP 게이팅, 긴급 중지, 변조 방지 감사 로그로 구성되며 모든 도구 실행 전에 평가됩니다.

모든 것은 단일 바이너리에서 시작됩니다. revka를 빌드하거나 다운로드한 후 명령어(revka gateway, revka daemon, 또는 revka agent)를 실행하면, 해당 명령에 필요한 레이어가 활성화됩니다.

게이트웨이 vs 데몬 vs 서비스

세 가지 명령 모두 런타임을 시작하지만, 활성화되는 컴포넌트 조합이 다릅니다. 용도에 맞는 명령을 선택하세요.

명령	실행 내용	사용 시기
revka gateway	HTTP 게이트웨이만 실행: REST API, 대시보드, WebSocket, SSE. 채널 없음.	대시보드와 API만 필요하고 메시징 통합은 필요 없을 때.
revka daemon	게이트웨이 및 설정된 모든 채널, 하트비트, 크론 스케줄러를 실행.	Revka를 상시 실행 에이전트로 운영할 때.
revka service	데몬을 OS 서비스(launchd, systemd, 또는 OpenRC)로 설치 및 관리.	재부팅 후에도 Revka가 자동으로 실행되어야 할 때.

# Gateway only — dashboard + API at http://127.0.0.1:42617
revka gateway

# Full runtime — gateway + channels + heartbeat + cron
revka daemon

# Run as a managed background service
revka service install && revka service start
revka service status
revka service logs --follow

게이트웨이는 기본적으로 127.0.0.1:42617에 바인딩됩니다. --host와 --port로 변경할 수 있습니다. 페어링이 활성화된 상태에서 처음 시작하면 게이트웨이가 일회용 페어링 코드를 출력하며, 클라이언트는 POST /pair를 통해 이 코드를 베어러 토큰으로 교환합니다. 전체 흐름은 페어링 및 인증을 참고하세요.

팁

서비스로 실행하는 것이 권장되는 프로덕션 구성입니다. 백그라운드 서비스로 실행과 런타임 모드, 어댑터 및 리소스 제한을 참고하세요.

설계상 베어러 토큰 없이도 항상 접근 가능한 엔드포인트가 있습니다:

• GET /health — 로드 밸런서용 공개 활성 상태 확인 (시크릿 노출 없음).
• GET /metrics — [observability] backend = "prometheus" 설정 시에만 Prometheus 텍스트 형식으로 제공.
• POST /webhook — 범용 에이전트 인그레스 (선택적으로 X-Webhook-Secret으로 보호 가능).
• POST /admin/shutdown, GET|POST /admin/paircode — 로컬호스트 전용 관리 엔드포인트 (원격 호출 시 403 반환).

런타임 어댑터

런타임 어댑터는 에이전트가 호스트에서 어떻게 실행될지를 결정하는 레이어입니다. 동일한 에이전트 정의라도 배포 환경과 리소스 제약에 따라 포그라운드 프로세스, 게이트웨이 전용, 관리형 서비스, 컨테이너 등 다양한 모드로 실행될 수 있습니다. 선택한 모드는 위의 게이트웨이 / 데몬 / 서비스 명령과 직접 대응됩니다.

모드	실행 방법
포그라운드 런타임	revka daemon
게이트웨이 전용	revka gateway
관리형 서비스	revka service install && revka service start
Docker / Compose	docker compose up -d

런타임 모드, 어댑터 선택, 리소스 제한에 대한 자세한 내용은 런타임 모드, 어댑터 및 리소스 제한과 Docker, Compose 및 원클릭 PaaS를 참고하세요.

오퍼레이터와 Kumiho 사이드카

Revka는 오케스트레이션 브레인과 메모리 백엔드를 Rust 바이너리 외부에 두고, 두 개의 Python MCP 사이드카로 실행합니다. Rust 데몬이 두 사이드카를 stdio를 통해 시작하고 관리하며, Model Context Protocol을 통해 에이전트에 도구를 제공합니다.

오퍼레이터 MCP — 오케스트레이션 브레인

오퍼레이터는 Python 3.11+ MCP 서버로, 데몬이 에이전트 채팅 세션마다 새로 생성합니다. 에이전트에게 서브 에이전트 생성 및 조율, 선언형 YAML 워크플로우 실행, 팀 관리, 결과 기록, A2A 프로토콜을 통한 에이전트 간 통신을 위한 도구를 제공합니다. 오퍼레이터 코드는 데몬을 재시작하지 않아도 변경할 수 있습니다.

오퍼레이터는 Node.js 세션 매니저 사이드카와 연동됩니다. 세션 매니저는 에이전트 SDK 세션(Claude SDK 및 Codex)을 관리하고 라이브 에이전트 이벤트를 게이트웨이의 WebSocket 채널로 중계합니다 — 이것이 대시보드의 라이브 워크플로우 뷰를 구동하는 요소입니다. 세션 매니저 없이도 오케스트레이션은 동작하지만 라이브 실행 오버레이에 이벤트가 전달되지 않습니다.

[operator]
mcp_path = "~/.revka/operator_mcp/run_operator_mcp.py"

오퍼레이터 MCP, 에이전트 생성 및 조율, 그리고 워크플로우 개요를 참고하세요.

Kumiho MCP — 영속적 그래프 메모리

Revka는 메모리를 로컬에 저장하지 않습니다. Rust 수준에서 메모리 바인딩은 항상 no-op(NoneMemory)이며, 모든 영속성은 Kumiho 그래프 메모리 컨트롤 플레인과 통신하는 클라이언트 스텁인 Kumiho MCP 사이드카에 위임됩니다. backend = "kumiho" 또는 backend = "none" 모두 해당 no-op 바인딩으로 처리되며, 그 외의 백엔드 이름(sqlite, qdrant 등)은 시작 시 거부됩니다.

[memory]
backend = "kumiho"          # or "none"; both run NoneMemory locally

[kumiho]
enabled = true
mcp_path = "~/.revka/kumiho/run_kumiho_mcp.py"
api_url = "https://api.kumiho.cloud"
space_prefix = "Revka"
memory_project = "CognitiveMemory"

에이전트는 이중 반사(two-reflex) 패턴을 사용합니다. 응답 전에 kumiho_memory_engage를 호출하여 Kumiho 그래프에서 관련 컨텍스트를 불러오고, 응답 후에 kumiho_memory_reflect를 호출하여 결정, 사실, 선호도 등을 출처 엣지와 함께 구조화된 형태로 저장합니다. 메모리는 계층적 스페이스 내의 아이템으로 저장되며, 각 아이템은 불변 리비전을 가집니다.

주의

Kumiho 컨트롤 플레인(Neo4j 기반 FastAPI)은 로컬에 설치되지 않습니다 — run_kumiho_mcp.py는 클라이언트 스텁일 뿐입니다. 두 사이드카 모두 revka install --sidecars-only로 설치하세요. 자세한 내용은 Python MCP 사이드카 설치를 참고하세요.

메모리 개요, Kumiho 설정, 그리고 그래프 모델: 스페이스, 아이템 및 출처에서 더 자세히 알아보세요.

채널 슈퍼바이저

채널 슈퍼바이저는 revka daemon 내부에서 실행됩니다. 에이전트를 메시징 플랫폼에 연결하고, 수신 메시지를 에이전트 루프로 전달하며 에이전트 응답을 플랫폼으로 반환합니다. 채널은 두 가지 전달 방식으로 나뉩니다:

• 폴링 채널 (Telegram, Discord, Nostr 등) — 공개 포트가 필요 없습니다. 폴링하거나 외부 방향으로 장기 연결을 유지합니다.
• 웹훅 채널 (WhatsApp, Nextcloud Talk, 범용 /webhook 등) — 플랫폼이 게이트웨이로 POST 요청을 보낼 수 있도록 공개 HTTPS 엔드포인트가 필요합니다.

revka channel list      # show configured channels and status
revka channel start     # start the channel supervisor
revka channel doctor    # diagnose channel configuration

채널 전반에 걸쳐 허용 목록 의미 체계는 일관됩니다. 빈 허용 목록은 모든 사용자를 차단하고, "*"는 모든 사용자를 허용하며, 명시적 목록은 지정된 사용자만 허용합니다. 수신 메시지는 LLM에 전달되기 전에 프롬프트 인젝션 스캔을 거치고, 발신 메시지는 전달 전에 자격 증명 누출 감지를 거칩니다.

채널 개요와 메시징 채널 연결을 참고하세요.

에이전트 루프

채널, 대시보드 채팅, /webhook 엔드포인트, 크론 작업, 또는 revka agent를 통해 메시지가 도착하면 Revka는 도구 사용 에이전트 루프를 실행합니다:

1. 인그레스. 채널, WebSocket(/ws/chat), SSE, 웹훅, 또는 CLI를 통해 메시지가 유입됩니다. 수신 텍스트는 프롬프트 인젝션 스캔을 거칩니다.

2. 메모리 인게이지. 에이전트가 kumiho_memory_engage를 호출하여 Kumiho 그래프에서 관련 이전 컨텍스트를 가져와 프롬프트에 주입합니다.

3. 추론 및 도구 호출. LLM이 추론하고 도구 호출을 발행합니다. 모든 도구 호출은 실행 전에 보안 정책에 대해 검사됩니다.

4. 반복. 도구 결과가 루프로 다시 공급되어 작업이 완료되거나 제한(max_tool_iterations, 기본값 60)에 도달할 때까지 반복됩니다. [agent] parallel_tools = true인 경우 도구는 병렬로 실행될 수 있습니다.

5. 리플렉트. 에이전트가 kumiho_memory_reflect를 호출하여 결정과 사실을 출처 엣지와 함께 캡처로 저장합니다.

6. 응답. 답변이 원래 요청 경로로 스트리밍됩니다. 발신 텍스트는 자격 증명 누출 스캔을 거치고, 해당 턴은 감사 로그에 기록됩니다.

주요 설정은 ~/.revka/config.toml의 [agent] 섹션에 있습니다:

키	기본값	의미
max_tool_iterations	60	턴당 최대 도구 호출 횟수
max_history_messages	1000	유지되는 대화 기록 수
max_context_tokens	1050000	컨텍스트 윈도우 예산
parallel_tools	true	동시 도구 호출 허용

더 자세한 내용은 에이전트 루프, 자율성 수준 및 승인, 그리고 세션 및 대화 상태를 참고하세요.

심층 방어 보안

보안은 독립적인 레이어에서 적용되며, 도구 실행이 허용되기 전에 각 레이어가 평가됩니다. 단일 우회 수단으로는 전체 모델을 무력화할 수 없습니다.

자율성 수준

read_only, supervised(기본값), 또는 full. 에이전트가 작업을 수행할 수 있는지 여부와 위험한 명령에 승인이 필요한지를 제어합니다.

명령어 허용 목록

따옴표 인식 셸 파서가 복합 명령을 분리하여 각 세그먼트를 검증하고, 체이닝, 서브셸, 리다이렉션, 위험 분류 명령을 차단합니다.

경로 샌드박싱

파일 작업은 워크스페이스와 allowed_roots로 제한되며, 경로 순회, 심볼릭 링크 탈출, 금지된 경로 검사가 적용됩니다.

OTP 및 긴급 중지

TOTP가 민감한 작업을 보호합니다. revka estop은 도구를 즉시 동결하고 네트워크를 차단하거나 도메인을 블록하며, OTP 게이팅을 통해 재개합니다.

이 외에도 Revka는 시크릿을 저장 시 암호화(ChaCha20-Poly1305)하고, 페어링 토큰을 해싱(SHA-256)하며, 선택적 OS 수준 샌드박스 백엔드(Firejail, Bubblewrap, Landlock, sandbox-exec, Docker)를 지원합니다. 또한 에이전트가 특정 도메인에서 반복적으로 실수를 할 경우 자율성을 자동으로 낮추는 도메인별 신뢰 점수를 적용합니다.

모든 보안 관련 이벤트는 변조 방지 감사 로그에 추가됩니다 — SHA-256 Merkle 해시 체인으로, 선택적으로 HMAC 서명을 적용할 수 있습니다. 다음과 같이 조회하고 검증할 수 있습니다:

# Query recent audit events
curl "http://127.0.0.1:42617/api/audit?limit=50&event_type=command_execution" \
  -H "Authorization: Bearer rk_<token>"

# Verify chain integrity (detects tampering)
curl "http://127.0.0.1:42617/api/audit/verify" \
  -H "Authorization: Bearer rk_<token>"

[autonomy]
level = "supervised"        # read_only | supervised | full
block_high_risk_commands = true
require_approval_for_medium_risk = true
workspace_only = true

[audit]
enabled = true              # tamper-evident Merkle hash chain

보안 모델, 정책, 명령어 및 샌드박싱, OTP 게이팅 및 긴급 중지, 그리고 감사 로그에서 세부 내용을 확인하세요.

다음 단계

에이전트 루프 Revka가 메시지를 도구 사용 에이전트 턴으로 처리하는 단계별 과정.

에이전트, 팀 및 스웜 오퍼레이터가 여러 에이전트를 생성하고 조율하는 방법.

게이트웨이 API 개요 대시보드와 통합을 구동하는 REST 및 WebSocket 인터페이스.

Kumiho 그래프 메모리 영속적 메모리와 이중 반사 인게이지/리플렉트 패턴 설정 방법.