47 KiB
Client configuration and troubleshooting
Use this reference when a client's configuration paths, profiles, trust settings, or schema limits affect REA. Start with installation and setup for the reviewed setup transaction and client IDs. The versioned verification notes below describe their stated runs; live service acceptance is verified only where explicitly recorded.
Launchers and PATH
A client launched from a desktop app, IDE or service can inherit a different
PATH from your terminal. An absolute path to rea-agents does not resolve its
interpreter: the npm launcher's #!/usr/bin/env node still searches PATH for
Node. Running that command successfully in a terminal does not establish that
the client can launch it.
For JavaScript installations, setup registers the selected runtime
executable and REA script by absolute path. On POSIX, it prefers executable
node or bun and REA aliases on setup's PATH only when they resolve to the
same selected files. This preserves manager-owned aliases across version updates;
otherwise setup uses the selected paths directly. This also applies when setup
runs through a package runner: retain the selected cache entry and runtime while
the registration uses them. Clearing either makes startup fail without resolving
another package from the client's project. Restore the same installation before
repairing it; an unidentified registration remains untouched. See
installation and recovery.
Setup does not copy your ambient environment into client
settings. To refresh an older registration, preview
rea setup --client <client-id> --skill=false --dry-run, then run the same command
without --dry-run and approve the displayed changes. Setup preserves unrelated
settings, backs up changed configuration and leaves an aligned registration
unchanged. Restart the client after applying the update.
If a runtime manager removes the registered executable and no surviving alias was available, doctor reports its identity as unknown and setup retains the registration. REA does not infer that an arbitrary missing executable was Node from its script argument. Back up the client's configuration, verify the absolute path and supported version of the runtime you intend to use, then update only the runtime command, preserving the REA script arguments and other settings. Rerun setup to review the registration and restart the client.
rea mcp doctor --json tests the production MCP adapter using the runtime
executable and environment of the terminal running doctor. It does not launch
the client's configured command or reproduce the client's environment. If doctor
passes but the client disconnects, inspect the client's startup error and registered
launcher; see verification scope.
Runtime settings and client deadlines
update_analysis_settings changes curated defaults inside the running REA
server. It does not edit the client registration, extend the client's tool-call
deadline, or recompute timeout values previously derived by rea setup. When
raising a REA startup or operation deadline, separately ensure the client allows
enough time for the full request. Use inspect_analysis_settings for the running
server's defaults; rea doctor checks launch configuration and cannot observe
another process's runtime overrides. See the
settings design for ownership and lifetime.