150 lines
7.0 KiB
Markdown
150 lines
7.0 KiB
Markdown
# Installation and setup
|
|
|
|
REA separates installing its CLI from configuring external software and agents.
|
|
|
|
## Install the CLI
|
|
|
|
The recommended installation is:
|
|
|
|
```bash
|
|
npm install --global rea-agents
|
|
rea setup
|
|
```
|
|
|
|
REA supports Node.js 22.19+ and 24.11+ (including newer releases). It uses the npm already paired with that runtime and never upgrades Node.js, npm, or Homebrew.
|
|
|
|
Running `npm install rea-agents` without `--global` installs the executable only
|
|
in the current project's `node_modules/.bin`; it does not make `rea` available
|
|
on the shell `PATH`. Use `npx -y rea-agents@latest` for one-off commands or the
|
|
global installation above for a shell-visible `rea` command.
|
|
|
|
The optional curl wrapper installs only the global npm package:
|
|
|
|
```bash
|
|
curl -fsSL https://raw.githubusercontent.com/morluto/rea/main/install.sh | bash
|
|
```
|
|
|
|
It prints the version, runtime, npm command, and destination before installing. When a controlling terminal exists it starts `rea setup`; otherwise it prints the command to run later.
|
|
|
|
Pass options with `bash -s --`:
|
|
|
|
```bash
|
|
curl -fsSL https://raw.githubusercontent.com/morluto/rea/main/install.sh |
|
|
bash -s -- --dry-run
|
|
```
|
|
|
|
Supported options are `--version <semver>`, `--dry-run`, `--no-setup`, `--no-prompt`, and `--verbose`. Neither `--no-prompt` nor a non-interactive shell grants permission to install external dependencies.
|
|
|
|
## Review setup changes
|
|
|
|
`rea setup` discovers the current state, prints one plan, and asks `Continue? [Y/n]`. The plan identifies:
|
|
|
|
- an existing Hopper installation, a validated bring-your-own Ghidra environment, or the official Hopper package it proposes to install;
|
|
- each detected agent configuration path;
|
|
- the REA skill destination;
|
|
- external software and package-manager effects.
|
|
|
|
Declining makes no changes. Agent configuration writes preserve unrelated entries, create backups, use atomic replacement, and verify their result.
|
|
|
|
For automation, `rea setup --json` reports the plan without applying it. `rea setup --yes` applies user-owned registrations and the skill. Installing missing Hopper non-interactively additionally requires `--install-hopper`:
|
|
|
|
```bash
|
|
rea setup --yes --install-hopper --json
|
|
```
|
|
|
|
## Hopper
|
|
|
|
Hopper is separate commercial software with its own license. Its free demo has
|
|
vendor-defined limits, and a paid license is optional. REA reuses any detected
|
|
installation and preserves Hopper during uninstall.
|
|
|
|
On macOS, approved setup downloads the official DMG, checks its published size
|
|
and digest, validates the application bundle, and atomically installs it to
|
|
`~/Applications/Hopper Disassembler.app`. REA then opens Hopper so the
|
|
operator can choose its demo mode or activate an existing license. Homebrew and
|
|
administrator access are not used.
|
|
|
|
On supported Linux distributions, approved setup verifies Hopper's official
|
|
`.deb`, `.rpm`, or Arch package before invoking the native package manager.
|
|
REA runs the supported demo build on a private Xvfb display and selects Hopper's
|
|
offered demo mode for each analysis session; it does not require the user's
|
|
desktop display. Unattended package-manager access requires
|
|
`--yes --install-hopper`.
|
|
|
|
## Ghidra
|
|
|
|
REA's Ghidra provider is bring-your-own and supports Linux x64 with the exact
|
|
official Ghidra 12.1.2 release and a 64-bit full JDK 21. An experimental
|
|
Windows x64 P0 supports approved native x86-64 PE applications. It supplies
|
|
discovery, analysis-profile commitment, an isolated read-only headless session,
|
|
ten bounded inventory/name/search operations, and eight function-analysis
|
|
operations covering metadata, decompilation, assembly, resolved calls, typed
|
|
references, xrefs, CFG, and dossiers. GUI state and analysis mutations remain
|
|
unavailable through Ghidra.
|
|
|
|
Extract Ghidra and install the JDK outside REA, then export absolute paths:
|
|
|
|
```bash
|
|
export GHIDRA_INSTALL_DIR=/absolute/path/to/ghidra_12.1.2_PUBLIC
|
|
export JAVA_HOME=/absolute/path/to/jdk-21 # optional if java/javac are on PATH
|
|
rea doctor --json
|
|
rea setup
|
|
```
|
|
|
|
PowerShell configuration for Windows uses the same non-secret paths:
|
|
|
|
```powershell
|
|
$env:GHIDRA_INSTALL_DIR = "C:\tools\ghidra_12.1.2_PUBLIC"
|
|
$env:JAVA_HOME = "C:\Program Files\Java\jdk-21"
|
|
rea doctor --json
|
|
rea providers --json
|
|
```
|
|
|
|
`rea setup` does not mutate Windows client configuration or install Hopper,
|
|
Ghidra, Java, Python, or another package. Register the built `rea mcp` command
|
|
manually in the intended client and preserve the two environment variables.
|
|
See [Windows Ghidra P0](windows-ghidra-p0.md) for a complete example.
|
|
|
|
Doctor validates the platform, architecture, application version,
|
|
`support/analyzeHeadless` or `support/analyzeHeadless.bat`, Java
|
|
version/bitness, and the presence of `javac`/`javac.exe`.
|
|
When Java is found through `PATH`, setup records its observed JDK home so GUI
|
|
MCP clients do not depend on an incidental shell path. Setup shows every exact
|
|
environment entry in its plan, writes only after approval, and never downloads,
|
|
installs, upgrades, or modifies Ghidra or Java.
|
|
|
|
Each verified session uses an ephemeral temporary project and isolated
|
|
home/cache/config/temp paths. REA passes `-readOnly`, `-deleteProject`, a
|
|
per-file analysis timeout, CPU and heap bounds, and its packaged Java bridge via
|
|
`-scriptPath`; it never opens an existing user project. Linux uses a
|
|
current-user-only local bridge socket and descriptor. Windows P0 uses
|
|
token-authenticated IPv4 loopback, a token-free endpoint record, and bounded
|
|
process-tree termination. It does not yet prove private DACL,
|
|
reparse-point-safe, or Job Object semantics; use only approved non-sensitive
|
|
fixtures.
|
|
|
|
Operations begin only after default auto-analysis completes. A timeout fails
|
|
the open rather than exposing partial analysis. One session contains exactly
|
|
one imported Program; use `provider_id: "ghidra"`, `--provider ghidra`, or
|
|
`REA_ANALYSIS_PROVIDER=ghidra` when both Hopper and Ghidra support the target.
|
|
One persistent decompiler is owned by the Program, Ghidra API calls cross a
|
|
bounded 32-request serial queue, and each native decompile is limited to 30
|
|
seconds. Unresolved computed calls remain unknown, reference-kind provenance is
|
|
preserved, and provider-specific pseudocode is never treated as original source
|
|
or Hopper-equivalent text.
|
|
|
|
Run `GHIDRA_INSTALL_DIR=... npm run verify:ghidra` from a source checkout to
|
|
compile and analyze source-owned x86-64 debug/stripped ELF, AArch64 ELF,
|
|
x86-64 PE, and x86-64 Mach-O conformance fixtures. The verifier expects `cc`,
|
|
`clang`, and `lld-link` on `PATH`; `REA_CC`, `REA_CLANG`, and `REA_LLD_LINK` can
|
|
select alternate command paths.
|
|
|
|
On a controlled Windows x64 runner, use
|
|
`npm run verify:ghidra:windows`. The verifier generates a deterministic native
|
|
PE fixture from source bytes, exercises every admitted Ghidra operation, checks
|
|
target/snapshot/import digest identity, and requires complete runtime cleanup.
|
|
|
|
## Diagnose, update, and remove
|
|
|
|
`rea doctor --json` is strictly read-only. `rea upgrade` updates only the npm installation that owns the running CLI. `rea uninstall` removes only REA-owned agent registrations and skill files; `--purge-data` additionally removes REA cache and state paths.
|