Local Setup (No Docker)本地部署（无需 Docker）

Overview概览

Rikune can run without Docker — directly on Windows, Linux, or macOS. The core engine (Node.js + Python workers) requires only Node.js and Python. All external analysis tools (Ghidra, Rizin, capa, Frida, etc.) are optional — Rikune auto-detects what is available at startup via the plugin systemDeps mechanism and only enables the tools it finds. Rikune 可以不依赖 Docker运行 — 直接在 Windows、Linux 或 macOS 上运行。 核心引擎（Node.js + Python worker）只需要 Node.js 和 Python。 所有外部分析工具（Ghidra、Rizin、capa、Frida 等）都是可选的 — Rikune 启动时通过插件 systemDeps 机制自动检测可用工具， 只启用检测到的工具。

Prerequisites前置要求

Auto Install Script自动安装脚本

The easiest way to get started locally — the install script handles everything: 本地上手最简单的方式 — 安装脚本自动处理一切：

Windows (PowerShell)

git clone https://github.com/Last-emo-boy/rikune.git
cd rikune
.\install-local.ps1

# Windows-native analyzer with local Windows Sandbox execution
.\install-local.ps1 -RuntimeMode auto-sandbox

Linux / macOS (Bash)

git clone https://github.com/Last-emo-boy/rikune.git
cd rikune
chmod +x install-local.sh
./install-local.sh

# Split analyzer/runtime configuration
./install-local.sh -r remote-sandbox

The script will:脚本会：

1. Verify Node.js 22+ and Python 3.11+验证 Node.js 22+ 和 Python 3.11+
2. Run npm install + npm run build运行 npm install + npm run build
3. Create a Python venv and install worker dependencies创建 Python 虚拟环境并安装 worker 依赖
4. Optionally install dynamic analysis, Qiling, and angr packages可选安装动态分析、Qiling 和 angr 包
5. Create data directories创建数据目录
6. Check for optional tools (Ghidra, Rizin, capa, etc.)检查可选工具（Ghidra、Rizin、capa 等）
7. Generate a .env file生成 .env 文件
8. Configure your MCP client (Claude, Copilot, Codex)配置你的 MCP 客户端（Claude、Copilot、Codex）

Manual Setup手动安装

If you prefer to set up step by step: 如果你更喜欢逐步安装：

1. Clone & Build1. 克隆 & 构建

git clone https://github.com/Last-emo-boy/rikune.git
cd rikune
npm install
npm run build

2. Python Environment2. Python 环境

# Create venv
cd workers
python3 -m venv venv
source venv/bin/activate   # Linux/macOS
# .\venv\Scripts\Activate.ps1  # Windows

# Install base requirements
pip install -r ../requirements.txt
pip install -r requirements.txt

# Optional: dynamic analysis (frida, speakeasy, pandare)
pip install -r requirements-dynamic.txt

# Optional: Qiling (isolated venv due to unicorn conflicts)
cd ..
python3 -m venv qiling-venv
./qiling-venv/bin/pip install -r workers/requirements-qiling.txt

# Optional: angr (isolated venv, large ~1.5 GB)
python3 -m venv angr-venv
./angr-venv/bin/pip install angr

3. Create Data Directories3. 创建数据目录

mkdir -p ~/.rikune/{workspaces,data,cache,ghidra-projects,ghidra-logs,logs,storage,samples}

4. Start4. 启动

WORKSPACE_ROOT=~/.rikune/workspaces \
DB_PATH=~/.rikune/data/database.db \
CACHE_ROOT=~/.rikune/cache \
SANDBOX_PYTHON_PATH=./workers/venv/bin/python \
node dist/index.js

Optional Analysis Tools可选分析工具

Install any of these to unlock additional MCP tools. Rikune auto-detects them at startup — just install the tool, set the environment variable if needed, and restart. 安装以下任何工具以解锁更多 MCP 工具。 Rikune 启动时自动检测 — 只需安装工具，必要时设置环境变量，然后重启。

💡 Tip: You don't need to install all tools. Start with the basics and add tools as your workflow demands. Rikune gracefully disables tools whose dependencies are missing. 💡 提示：不需要安装所有工具。从基础开始，按需添加。Rikune 会优雅地禁用缺少依赖的工具。

Runtime note: For local static-only work, keep RUNTIME_MODE=disabled. If you run the analyzer natively on Windows, you can opt into auto-sandbox to launch Windows Sandbox for real sample execution. Linux or WSL analyzers must use manual or remote-sandbox to reach a separate Windows Runtime Node / Host Agent. 运行时说明：如果只是本地静态分析，请保持 RUNTIME_MODE=disabled。如果 analyzer 原生运行在 Windows 上，可以开启 auto-sandbox，通过 Windows Sandbox 执行真实样本。Linux 或 WSL 中的 analyzer 必须使用 manual 或 remote-sandbox 连接独立的 Windows Runtime Node / Host Agent。

Environment Configuration环境配置

The install script generates a .env file in the project root. You can also create one manually: 安装脚本会在项目根目录生成 .env 文件。你也可以手动创建：

# Core (required)
WORKSPACE_ROOT=~/.rikune/workspaces
DB_PATH=~/.rikune/data/database.db
CACHE_ROOT=~/.rikune/cache
SANDBOX_PYTHON_PATH=./workers/venv/bin/python
LOG_LEVEL=info

# API File Server
API_ENABLED=true
API_PORT=18080
API_STORAGE_ROOT=~/.rikune/storage

# Runtime mode (pick one shape)
RUNTIME_MODE=disabled
# Windows-native single-host execution:
# RUNTIME_MODE=auto-sandbox
# Split analyzer/runtime deployment:
# RUNTIME_MODE=manual
# RUNTIME_ENDPOINT=http://windows-vm-ip:18081
# RUNTIME_MODE=remote-sandbox
# RUNTIME_HOST_AGENT_ENDPOINT=http://windows-host-ip:18082
# RUNTIME_HOST_AGENT_API_KEY=change-me
# Optional if the Windows Runtime Node also requires its own key:
# RUNTIME_API_KEY=change-me
# On the Windows Host Agent side, Docker/WSL deployments should bind the agent to 0.0.0.0:
# HOST_AGENT_BIND_HOST=0.0.0.0

# Ghidra (set if installed)
GHIDRA_INSTALL_DIR=/opt/ghidra
GHIDRA_PROJECT_ROOT=~/.rikune/ghidra-projects
GHIDRA_LOG_ROOT=~/.rikune/ghidra-logs

# Tool paths (set for tools you have installed)
RIZIN_PATH=/usr/bin/rizin
CAPA_PATH=/usr/local/bin/capa
CAPA_RULES_PATH=/opt/capa-rules
UPX_PATH=/usr/local/bin/upx
ANGR_PYTHON=./angr-venv/bin/python
QILING_PYTHON=./qiling-venv/bin/python

Key contract: RUNTIME_HOST_AGENT_API_KEY is only for Analyzer → Host Agent control calls. RUNTIME_API_KEY is only for Analyzer → Runtime Node requests (manual runtimes or sandbox runtimes that enforce their own auth). 密钥约定：RUNTIME_HOST_AGENT_API_KEY 仅用于 Analyzer → Host Agent 控制调用；RUNTIME_API_KEY 仅用于 Analyzer → Runtime Node 请求（包括手工运行时或启用了独立鉴权的沙箱运行时）。

MCP Client ConfigurationMCP 客户端配置

For local mode, the MCP client runs node dist/index.js directly (no Docker): 本地模式下，MCP 客户端直接运行 node dist/index.js（无需 Docker）：

Claude Desktop

{
  "mcpServers": {
    "rikune": {
      "command": "node",
      "args": ["C:/path/to/rikune/dist/index.js"],
      "env": {
        "WORKSPACE_ROOT": "C:/Users/you/.rikune/workspaces",
        "DB_PATH": "C:/Users/you/.rikune/data/database.db",
        "CACHE_ROOT": "C:/Users/you/.rikune/cache",
        "SANDBOX_PYTHON_PATH": "C:/path/to/rikune/workers/venv/Scripts/python.exe"
      }
    }
  }
}

VS Code (GitHub Copilot)

{
  "servers": {
    "rikune": {
      "command": "node",
      "args": ["C:/path/to/rikune/dist/index.js"],
      "env": {
        "WORKSPACE_ROOT": "C:/Users/you/.rikune/workspaces",
        "DB_PATH": "C:/Users/you/.rikune/data/database.db",
        "SANDBOX_PYTHON_PATH": "C:/path/to/rikune/workers/venv/Scripts/python.exe"
      }
    }
  }
}

Codex

[mcp_servers.rikune]
command = "node"
args = ["C:/path/to/rikune/dist/index.js"]

[mcp_servers.rikune.env]
NODE_ENV = "production"
PYTHONUNBUFFERED = "1"
WORKSPACE_ROOT = "C:/Users/you/.rikune/workspaces"
DB_PATH = "C:/Users/you/.rikune/data/database.db"
CACHE_ROOT = "C:/Users/you/.rikune/cache"
GHIDRA_INSTALL_DIR = "C:/path/to/ghidra"

Docker-backed MCP基于 Docker 的 MCP

When Rikune is deployed with static or hybrid, connect MCP clients through the running rikune-analyzer container instead of running node dist/index.js on the host. 当 Rikune 使用 static 或 hybrid 部署时，MCP 客户端应通过已运行的 rikune-analyzer 容器连接，而不是在宿主机上直接运行 node dist/index.js。

[mcp_servers.rikune]
command = "docker"
startup_timeout_sec = 180
args = [
  "exec",
  "-i",
  "-e", "API_ENABLED=false",
  "-e", "NODE_ENV=production",
  "-e", "PYTHONUNBUFFERED=1",
  "rikune-analyzer",
  "node",
  "dist/index.js"
]

[mcp_servers.rikune.env]
NODE_ENV = "production"
PYTHONUNBUFFERED = "1"

💡 Tip: The install-local.ps1 script can auto-generate native configs, and install-docker.ps1 -ConfigureClient can generate Docker JSON configs. Codex users who keep MCP servers in config.toml can copy the TOML form above. 💡 提示：install-local.ps1 可以生成原生运行配置， install-docker.ps1 -ConfigureClient 可以生成 Docker JSON 配置。使用 config.toml 管理 MCP server 的 Codex 用户可以复制上面的 TOML 写法。

Running Rikune运行 Rikune

Production生产模式

# Using npm script
npm start

# Or directly
node dist/index.js

Development (watch mode)开发模式（实时编译）

# Auto-reload on source changes
npm run dev

# Run tests
npm test

Health Check健康检查

At startup, Rikune logs a dependency health report showing which tools are available: 启动时，Rikune 会输出依赖健康报告，显示哪些工具可用：

Plugin ghidra:  Ghidra ✓  java ✓
Plugin frida:   frida ✓
Plugin malware: capa ✓  capa-rules ✓
Plugin crackme: angr ✗ (optional — skipped)
Plugin dynamic: frida ✓
...

How Auto-Detection Works自动检测原理

Every plugin can declare a systemDeps array describing the system tools it needs. At startup, Rikune's plugin loader calls checkSystemDeps() for each plugin, which probes each dependency: 每个插件可以声明 systemDeps 数组描述其所需的系统工具。 启动时，Rikune 的插件加载器对每个插件调用 checkSystemDeps()， 逐个探测每个依赖：

If a required dependency is missing, the plugin's tools are disabled. If an optional dependency is missing, the plugin still loads but with reduced functionality. This means you can install tools incrementally and restart Rikune to pick them up. 如果 required 依赖缺失，插件的工具会被禁用。 如果 optional 依赖缺失，插件仍会加载但功能减少。 这意味着你可以增量安装工具，重启 Rikune 即可生效。

Startup Flow:

  discover plugins  →  checkSystemDeps()  →  enable / disable tools
         │                       │                          │
   scan dist/plugins/      for each dep:             if all required deps OK:
   load plugin modules       binary? → exec test       → register MCP tools ✓
                              python? → import test    if required dep missing:
                              venv? → file exists        → skip plugin tools ✗
                              dir? → path exists       if optional dep missing:
                                                         → load with reduced features ⚠

Docker vs LocalDocker 对比本地