REA Setup Guide — run your first evidence-backed case

Install the agent

REA ships as the rea-agents npm package. Node 20+ is required. Install it in a scratch directory so nothing pollutes your projects:

$ npm install rea-agents@latest
$ npx rea --version
rea@6.4.0 — Reverse engineer anything from your terminal or agent.
35 deps · 0 vulnerabilities · bin: rea / rea-agents

Run rea doctor first

Before anything else, run the built-in environment diagnosis. It checks Node, your host OS, and every analysis engine. Our lab host (opencloudos) is not on the supported list — and doctor tells you exactly that, with the remediation. This is your first real lesson in REA's design: it fails loudly and precisely, never silently.

$ npx rea doctor
healthy: false
  - node: ok (22.22.0)
  - host: UNSUPPORTED — opencloudos 9.4
    remediation: "REA supports macOS 12+, Ubuntu 24.04+, Fedora 41+, Nobara 44+,
    64-bit Arch Linux, CachyOS, Omarchy, and the experimental Windows x64 Ghidra P0 boundary."
  - hopper: missing_analysis_engine (/opt/hopper/bin/Hopper 不存在)
  - ghidra: missing_analysis_engine (GHIDRA_INSTALL_DIR 未设)
  - ida-registration: not_configured

Notable: rea capabilities lists 18 operations with declared side effects and limitations — the "evidence contract / fail-closed" design REA is known for, confirmed present in this version.

Wire REA to your AI agent (MCP)

REA speaks the Model Context Protocol. One command registers the rea MCP server in your agent's config (with an automatic backup) and installs a companion skill:

$ npx rea setup -y --client hermes
appliedActions[2]: configured_hermes, installed_skill
  - configure_client:hermes → config.yaml (自动备份 .rea.backup)
  - install_skill:hermes → skills/reverse-engineer-anything

Config written (verified on disk):

mcp_servers:
  rea:
    command: npx
    args: [-y, rea-agents@6.4.0, mcp]
    enabled: true

We confirmed the link end-to-end with a stdio JSON-RPC probe: initialize returned serverInfo {name: "rea", version: "6.4.0"} and tools/list enumerated 170 MCP tools (annotate_native_function, inspect_native_load_image, batch_decompile, analyze_function, inspect_binary_layout…). The agent-to-engine chain is live.

Light up a zero-cost engine (pwntools-elf)

Deep analysis (analyze/decompile) needs Ghidra, Hopper, or IDA — but REA also ships a pure-Python ELF provider: pwntools-elf. "REA never installs Python or packages"; you point it at a venv that already has the three pinned libraries. This is the free path, and it is fully usable for first lessons:

$ python3 -m venv lab-env/.rea-python
$ .rea-python/bin/pip install pwntools==4.15.0 pyelftools==0.33 unicorn==2.1.2
$ export REA_PWNTOOLS_PYTHON=lab-env/.rea-python/bin/python

Run your first evidence-backed analysis

Now point it at a target you are allowed to inspect (here: a hello-world ELF we compiled ourselves, see lesson 2):

$ npx rea inspect-binary-layout lab-env/hello
evidence_id: ev_6e479c83fba06374c38ab8f9fa3876e561d28d3515aa68473598e9f94dcb556c
subject: hello / sha256 36cdabb6…4207352 / elf / x86_64
provider: pwntools-elf @ pwntools 4.15.0;pyelftools 0.33;unicorn 2.1.2
normalized_result: 31 sections, entry_point 0x400320
(与 lab 01 手工 readelf 结果一致 —— 可交叉验证)

That output is the evidence contract in action: a content-addressed evidence ID, the exact bytes analyzed (sha256), the provider and its three library versions, and a normalized result you can cross-check against manual binutils output — ours matched exactly.

The evidence lifecycle closes through MCP: session-retained evidence exports as a bundle, then exports to canonical form:

$ inspect_binary_layout(hello) → ev_6e479c83… (会话保留)
get_evidence_bundle(detail:summary) → total_retained_records: 1
export_evidence_bundle → hello-bundle.json (39113 bytes, records:1, unknowns:0)
rea evidence-export hello-bundle.json hello-canonical.json → 校验通过 ✓

Know the two tiers (honest boundaries)

What works and what does not with only the free engine — verified by running both:

$ npx rea analyze ./hello
error: Analysis failed · code: provider_unavailable
candidate_ids[3]: ghidra,hopper,ida
rejections[3]: ghidra(not_configured) / hopper(executable_missing) / ida(not_configured)

• Tier 1 — free (pwntools-elf): inspect-binary_layout and the ELF-layout family, plus the full evidence lifecycle. This covers everything in our beginners track and worked on a 4.5MB system library too (30 sections / 11 segments via --format json; the MCP channel reports resource_constraint on very large results and points you to the evidence bundle instead of truncating).
• Tier 2 — decompile/analyze: requires Ghidra, Hopper, or IDA. Forcing the free provider explicitly fails with capability_unavailable: "The requested analysis provider is unknown. Choose one of: ghidra, hopper, ida."

REA is an orchestration layer, not a decompiler — and it will tell you so, with a per-candidate rejection list, every single time. That honesty is exactly why its output is auditable.