REA on a Clean Linux Box: A 15-Minute Lab-Tested Setup Walkthrough

If an AI agent offered to dissect a binary for you, but every answer it gave came out of a black box, how much would you trust it? That discomfort is exactly the problem REA is built around. REA — the rea-agents npm package — is an orchestration layer for reverse engineering: you describe a goal in your AI coding agent, REA plans the tool calls, drives the analysis engines, and returns structured results with receipts attached. Every run mints a verifiable record — a content-addressed evidence ID, the analyzed input's sha256, the exact library versions that produced the result. You're not just told the answer; you're handed the paperwork to check it.

The good news is that the setup that gets you to your first receipt is genuinely short. This walkthrough is the same 15-minute run I execute in my lab before every REA release, and I re-ran it this week — 2026-11-13 — on REA 6.8.0 (shipped 2026-10-25), the current release as I write this. Every output below is quoted from that run or from my dated baseline records from October. One disclosure up front: I run an independent, lab-verified tutorial site for REA and I'm not affiliated with the REA project — that site is the one link at the very end of this article.

One ground rule before touching the terminal: only analyze software you own or are licensed to inspect. In my lab that means the toolchain itself and binaries I compiled from my own source code. Nothing in this walkthrough needs a target shadier than hello world.

Step 1: install the agent

REA ships as a single npm package, rea-agents. You'll want Node 20 or newer, and I recommend a scratch directory so nothing pollutes your real projects:

$ npm install rea-agents@latest
$ npx rea --version
[email protected] — Reverse engineer anything from your terminal or agent.

That's my October baseline: 6.4.0, 35 dependencies, zero vulnerabilities. This week's re-run on the same machine reports 6.8.0. One caution from my upgrade testing: 6.8.0 tightened the Node requirement to ^22.23.4 || ^24.22.1 || >=26.12.1, and my lab box runs Node 22.22.0 — so rea doctor flags a missing_dependency on it. The analyses themselves still run, but if your pipeline gates on doctor's health verdict, upgrade Node before you upgrade REA.

Step 2: run rea doctor first

Before anything else, run the built-in environment diagnosis:

$ 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 not found)
- ghidra: missing_analysis_engine (GHIDRA_INSTALL_DIR not set)
- ida-registration: not_configured

My lab distro isn't on the supported-host list, and doctor says exactly that — with a remediation string, not a shrug. Here's the honest part: REA still ran everything I needed it to on this unsupported host. Doctor's job isn't to stop you; it's to make sure you can never say "nobody told me." Every failing check names its cause and what would fix it. That fail-loudly-instead-of-fail-silently philosophy is the through-line of the whole tool, and it starts here.

While you're in diagnostic mode, run npx rea capabilities once. It lists 18 operations with declared side effects and limitations — effectively the spec of REA's evidence contract. Reading it takes five minutes and explains most of the behavior you'll hit later.

Step 3: wire REA into your AI agent (MCP)

REA speaks the Model Context Protocol, and one command registers it with your agent client — with an automatic config backup and a companion skill install:

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

The config it wrote, verified on disk:

mcp_servers:
  rea:
    command: npx
    args: [-y, [email protected], mcp]
    enabled: true

I then probed the MCP server directly with a small stdio JSON-RPC script rather than trusting the config on faith. initialize returned serverInfo: rea, version 6.4.0, and tools/list enumerated 170 tools. On 6.8.0 this week, the same surface check reports 229 tools, 6 prompts, and a catalog digest where expected equals observed — rea mcp doctor comes back healthy: true, protocol level 2025-11-25. That last detail is worth pausing on: the tool's own surface is part of the audited evidence, so you can verify the toolbox itself, not just the analyses it performs.

Step 4: light up the zero-cost engine

Full honesty about tiers here. REA's deep analysis commands — analyze, decompile — need a heavyweight engine underneath: Ghidra, Hopper, or IDA. Without one, they refuse to run, by design. But there's a free path that covers ELF layout work, and it's enough for your first case: the built-in pwntools-elf provider.

REA never installs Python or packages on its own — you point it at an interpreter that already has what the provider needs:

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

Those three version numbers aren't decorative — pin them exactly, because the evidence records will cite them to the patch digit, and a mismatch is the kind of thing you want to catch at install time, not in a report review.

Step 5: your first evidence-backed case

The lawful first target is one you compile yourself. One file, one known constant:

#include <stdio.h>
int secret(int x){return x*1337+7;}
int main(){printf("hello realearn %d\n", secret(42));return 0;}

Compiled with gcc -O0 -o hello hello.c, it prints hello realearn 56161 — and 42 × 1337 + 7 = 56161 checks out, giving you a runtime ground truth before any tool touches the binary. Now ask REA for the layout:

$ rea inspect-binary-layout 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

Read that record as four proofs, because that's what it is:

• The evidence ID is content-addressed — derived from the record itself, so the ID is the integrity check. Change one input byte and a different ID proves it.
• The subject sha256 pins exactly which bytes were analyzed. "I analyzed this file" becomes "I analyzed the file with this hash" — a claim anyone with the file can verify.
• The provider block cites exact library versions — pwntools 4.15.0, pyelftools 0.33, Unicorn 2.1.2 — so anyone reproducing your run knows precisely what to install.
• The normalized result is independently checkable. I cross-checked the 31-section count against manual readelf -h / readelf -s output on the same binary, and they agreed line by line — entry point 0x400320, symbols intact (my -O0 build isn't stripped, so secret sits right there at 0x400406).

That last bullet is the habit that makes agent-driven analysis trustworthy: before trusting the tool's receipts, hold your own ground truth for the same bytes.

Now the part I consider the real news of this re-run. The hello binary in my lab has not changed since October — same bytes, same sha256 — and this week's 6.8.0 re-run minted an evidence ID byte-for-byte identical to the one in my October 6.8.0 baseline records: ev_5cad21e9933f…c0cec, quoted in full in my dated lab records. Not "close enough." Identical. A deterministic contract you can build on.

Two honest footnotes to that. First, IDs are version-scoped: in my two-version comparison runs between 6.7.0 and 6.8.0, some outputs re-minted their IDs across the upgrade even for identical inputs. The rule I've adopted: pin the tool version in every report header and compare evidence IDs only within one version. Second, don't take my word for the determinism — that's the point of the receipts. Rerun the command on your own box and diff the records.

When you want a stretch goal, try two. One: run the same command on a stripped build (gcc with -s, or strip hello) — the ELF in my lab named hello-stripped still yields a clean evidence record with zero symbol names, and seeing what survives stripping is a lesson in itself. Two: scale up. I ran the CLI against my system's 4.5 MB libcrypto.so.3 — OpenSSL 3.0.12, Apache-2.0 licensed, which explicitly permits this kind of inspection — and got the full result: 30 sections, 11 segments, every record carrying its evidence ID. When a result is too large to return over MCP, REA refuses with resource_constraint and points you at the exportable evidence bundle instead of silently truncating. A tool that refuses to lie to you by omission — that's the design working as intended.

Step 6: know the two tiers

After the win in step 5, it's important to be equally clear about the boundary. Ask REA for deep analysis with no engine installed and it fails closed:

$ 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)

No plausible-looking guess, no silent degradation — a named refusal with per-engine diagnosis. And if you explicitly request the free provider for a deep operation, it refuses just as precisely: capability_unavailable, "The requested analysis provider is unknown. Choose one of: ghidra, hopper, ida."

So the honest mental model: REA is an orchestration layer, not a decompiler. The free tier covers ELF layout analysis plus the full evidence lifecycle — records, bundles, exports. When you eventually install Ghidra and set GHIDRA_INSTALL_DIR, the decompiler slots in underneath REA and the evidence contract stays intact. That pairing — Ghidra as the engine, REA as the auditable agent driving it — is the configuration I'd recommend to anyone serious about agent-driven analysis.

Can you reproduce this?

My box: OpenCloudOS 9.4 x86_64 (not on REA's supported-host list — see step 2), Node 22.22.0, gcc with binutils, isolated venv for the Python trio, rea-agents 6.8.0 for this week's re-run and 6.4.0/6.7.0 for the baseline records. Everything quoted here came from those runs; versions and numbers will age, which is exactly why every claim in my records carries a date and a tool version. Your outputs should match structurally — same fields, same self-checkable shapes — but your evidence IDs will be your own, minted from your own records. If REA ever hands you a result you can't verify, treat that as a bug to investigate, not a workflow to accept.

Where this goes next

Once your first receipt is in hand, the natural next steps are the evidence lifecycle: export a session bundle with the MCP export_evidence_bundle tool, verify it standalone with rea evidence-export, and start attaching evidence IDs to your own reports the way the tool attaches them to its own outputs.

The setup itself teaches the philosophy: run the doctor, read the refusal, hold your own ground truth, and never accept an answer without its paperwork. The full maintained version of this walkthrough — every step with its terminal sessions, kept current release by release — lives on the REA setup guide, the independent, non-affiliated REA tutorial site I run.

Facts, versions and numbers above come from my lab runs dated 2026-10-12 (baseline) and 2026-11-13 (6.8.0 re-run) and will age. Use every tool discussed only on software you own or are licensed to analyze.