Client configuration and setup
REA connects supported agent clients to its MCP server through each client's own configuration boundary. It discovers usable client profiles, builds a reviewable setup plan, validates ownership and safety, applies only approved changes, and reports or removes registrations without taking control of unrelated settings.
Client discovery
REA treats each supported client as a product with its own registration format and configuration location. The supported-client catalog supplies the rules needed to find the right profile and to distinguish a local registration from a client that requires manual account setup.
Configuration locations
REA resolves client paths from the host, operating system, and selected environment. A client can use one file or several ordered layers. The effective registration is the view the client loads after those layers and its fallback rules are applied. Path rules follow the client that owns the file; for example, XDG-based paths and strict absolute-path rules are not interchangeable. src/…/SupportedClients.ts• L1977-2117 src/…/ClientConfigRoots.test.ts• L11-37
REA requires product evidence before it reads a client automatically. A client directory or configuration marker can show that a product is present. Shared registration storage alone is not enough because another product or REA can create it. An explicit client selection authorizes inspection when automatic discovery has no evidence. src/…/SupportedClients.ts• L1893-1933 src/…/ClientRegistrationStatus.ts• L662-694
Some clients do not expose a local file that REA can write. REA reports these clients as manual instead of treating a data directory as a local registration. This keeps hosted account setup separate from a local MCP connection. src/…/SupportedClients.ts• L386-399 src/…/SupportedClients.ts• L1862-1873
References: src/…/SupportedClients.ts• L1160-1179 src/…/SupportedClients.ts• L1893-1933 src/…/SupportedClients.ts• L1977-2117 src/…/ClientConfigRoots.test.ts• L11-37 src/…/ClientRegistrationStatus.ts• L662-694
Setup planning
Setup is a reviewable workflow. It reads host and client state without changing it, chooses clients and optional workflow files, builds exact actions, and applies them only after approval. rea setup --dry-run exposes the resolved plan without mutation. src/…/Setup.ts• L92-192 src/…/setupCommands.ts• L55-139
Client selection
Interactive setup presents detected clients as choices and selects existing REA-owned registrations by default. Detection alone does not authorize a new registration. Explicit client selections choose exact clients, while --all-detected includes every detected supported client. The approval result can select individual actions, so an approved workflow need not configure every offered client. src/…/Setup.ts• L246-342 src/…/SetupPlan.ts• L84-137 src/…/Setup.configuration.test.ts• L426-502
For each selected client, setup compares the effective registration with the desired REA connection. It creates a missing registration, updates a stale one, skips an aligned one, and stops before writing when a selected configuration is malformed or unsafe. The plan names the target, action, backup path, and relevant registration environment. src/…/SetupPlan.ts• L145-259 src/…/SetupPlan.ts• L262-334
Setup can also install REA's bundled workflow instructions. This is separate from MCP registration, so a client can receive one without the other. The command also supports optional analysis-provider and desktop-build setup as separately approved work. A failure in optional provider setup is reported without undoing client or workflow work that already completed. src/…/SetupTypes.ts• L224-242 src/…/Setup.ts• L383-399 src/…/Setup.configuration.test.ts• L207-330
The high-level setup flow is:
flowchart TD
A[Read host and client state] --> B[Select clients and optional workflow]
B --> C[Inspect selected configurations]
C --> D[Build exact setup plan]
D --> E{Approved?}
E -- No --> F[Return plan or cancellation]
E -- Yes --> G[Apply client changes]
G --> H[Install selected workflow]
H --> I[Run scoped readiness checks]
I --> J[Report ready state or remediation]
References: src/…/Setup.ts• L195-259 src/…/Setup.ts• L277-359 src/…/Setup.ts• L383-399 src/…/Setup.ts• L401-555 src/…/SetupPlan.ts• L145-259 src/…/SetupPlan.ts• L336-418 src/…/Setup.configuration.test.ts• L426-502 src/…/Setup.configuration.test.ts• L660-804 src/…/setupCommands.ts• L262-350
Configuration validation
Validation protects the user's existing configuration and the identity of the REA installation. Setup parses the client format, checks the effective environment and client policy, verifies the registration launcher, and confirms that the target path is safe to edit. src/…/SetupClientConfiguration.ts• L495-685 src/…/ClientRegistration.ts• L163-216
Registration ownership
REA changes a rea entry only when its launcher proves that it belongs to the current REA installation. A foreign or unresolved launcher remains in place and is reported for manual review. This prevents setup from taking control of another REA installation or a hand-written server with the same name. src/…/ClientRegistrationIdentity.ts• L119-159 src/…/ClientRegistration.ts• L139-161 src/…/Setup.configuration.test.ts• L504-534
Ownership is separate from readiness. A registration can belong to REA while its timeout, policy, or transport settings are invalid. Doctor keeps that distinction so setup can repair the entry while reporting the setting that needs attention. A stored launcher can remain readable for ownership even when its transport is not an admitted local stdio connection. src/…/ClientRegistrationStatus.ts• L286-312 src/…/ClientRegistrationStatus.ts• L372-425 src/…/ClientRegistration.test.ts• L238-285
References: src/…/ClientRegistrationIdentity.ts• L119-159 src/…/ClientRegistration.ts• L139-161 src/…/ClientRegistrationStatus.ts• L286-312 src/…/ClientRegistration.test.ts• L238-285 src/…/Setup.configuration.test.ts• L504-534
Client safety checks
Setup fails closed when it cannot establish a safe target or valid configuration. It checks layered files, fallback registrations, disabled entries, and clients that can rewrite their files from memory. A running client with that behavior must be stopped before approval. src/…/SetupClientConfiguration.ts• L142-219 src/…/SetupClientConfiguration.ts• L519-524 src/…/SupportedClients.ts• L322-363
The plan is rejected when a selected file changes between inspection and publication. This prevents a plan based on old contents from replacing newer user changes. REA does not coordinate arbitrary writers, so users should not edit the same configuration while setup runs. src/…/SetupClientConfiguration.ts• L270-307 src/…/ClientConfigurationPublication.ts• L81-163
References: src/…/SetupClientConfiguration.ts• L142-219 src/…/SetupClientConfiguration.ts• L495-685 src/…/ClientRegistrationIdentity.ts• L119-159 src/…/ClientRegistration.ts• L139-216 src/…/SupportedClients.ts• L322-363 src/…/ClientConfigurationPublication.ts• L81-163 src/…/Setup.configuration.test.ts• L575-657
Configuration changes
REA updates the selected client's native representation of the MCP connection while preserving unrelated client settings. The registration receives the current REA launcher and supported selected environment values. Caller-owned policy and unrelated server settings remain under the client's control. src/…/SetupClientConfiguration.ts• L890-964 src/…/SetupPlan.ts• L472-492
Transaction and recovery
Each changed configuration is handled as one transaction. REA preserves the original bytes, publishes the new document, reads the result back, and restores the original when verification fails. Recovery snapshots are retained instead of silently replaced. src/…/SetupClientConfiguration.ts• L413-449 src/…/ClientConfigurationPublication.ts• L164-210 src/…/SetupRecoveryBackup.ts• L24-139
Private client profiles receive an owner-only backup. REA checks that an existing selected backup is a regular file, restricts it to private permissions, and preserves the original bytes without replacing an earlier matching snapshot. This keeps private configuration content from being exposed through a more permissive backup path. src/…/ClientRegistrationBackup.ts• L18-85
The same private-backup rule applies when setup or uninstall edits a private client profile. A backup failure prevents the related change and returns a failure that can be remediated rather than continuing without recovery data. src/…/SetupClientConfiguration.ts• L413-424 src/…/Uninstall.ts• L1175-1213
The result for each client distinguishes an unchanged registration from a configured one. It also records conflicts, unsafe paths, ownership refusals, write failures, readback failures, and rollback failures. These outcomes let the CLI report a repair step without hiding changes that already completed. src/…/SetupTypes.ts• L39-94 src/…/SetupClients.ts• L11-56
References: src/…/SetupClientConfiguration.ts• L366-449 src/…/ClientConfigurationPublication.ts• L164-210 src/…/SetupRecoveryBackup.ts• L24-139 src/…/ClientRegistrationBackup.ts• L18-96 src/…/Uninstall.ts• L1175-1213 src/…/SetupTypes.ts• L39-94 src/…/Setup.configuration.test.ts• L575-657
Registration environments
Setup carries supported, explicitly selected REA settings into the registration. It does not copy the full shell environment. Existing values remain unless setup supplies the same supported key, and provider values replace only matching keys. src/…/SetupTypes.ts• L24-25 src/…/SetupClientConfiguration.ts• L923-963 src/…/SetupPlan.ts• L472-491
Registration updates keep each client's native field names and preserve unrelated data. Where a client has legacy and canonical environment fields, REA accepts only an unambiguous valid form and writes one canonical form. It rejects conflicting aliases instead of choosing silently. src/…/ClientRegistration.test.ts• L41-66 src/…/ClientRegistration.test.ts• L96-180
The launcher is bound to the REA executable that runs setup. Setup uses a same-file runtime or command alias only when it can prove that the alias resolves to that executable. This lets registrations survive supported runtime-manager changes without accepting an unrelated executable as REA. src/…/ClientRegistrationIdentity.ts• L63-87 src/…/ClientRegistrationIdentity.ts• L162-214 src/…/Setup.configuration.test.ts• L536-572
The CLI controls the scope of these changes through explicit client selection, detected-client selection, tool-family and catalog-profile settings, workflow installation, and desktop-build options. The selected family and catalog profile appear in the plan before approval and are then written as registration settings. src/…/setupCommands.ts• L60-127 src/…/setupCommands.ts• L262-391 src/…/Setup.configuration.test.ts• L807-903
References: src/…/SetupClientConfiguration.ts• L890-964 src/…/SetupClientConfiguration.ts• L233-255 src/…/SetupRecoveryBackup.ts• L24-139 src/…/ClientRegistrationIdentity.ts• L63-87 src/…/ClientRegistrationIdentity.ts• L162-214 src/…/ClientRegistration.test.ts• L41-236 src/…/Setup.configuration.test.ts• L807-903 src/…/setupCommands.ts• L262-391
Registration status
Doctor reads the same client boundaries used by setup and projects each registration into a small status model. The model separates launcher identity, client activation, configuration alignment, package drift, and advisory timeout information. src/…/ClientRegistrationStatus.ts• L58-100 src/…/ClientRegistrationStatus.ts• L128-151
Status categories
The main states describe what REA can establish about the registration:
| State | Meaning |
|---|---|
aligned | The owned registration matches the supported client shape and is active. |
stale | REA owns the entry, but setup-managed values need refresh. |
unknown | REA cannot prove the launcher or native transport state. |
missing | No usable REA registration is present. |
invalid | The configuration or client policy cannot be safely used. |
manual | The client needs a user-managed account or remote registration. |
Doctor can report an advisory even when a registration is aligned. For example, a client deadline can be shorter than the known provider allowance. The advisory does not change ownership or silently change a caller-selected deadline. src/…/ClientRegistrationStatus.ts• L385-447 src/…/ClientRegistrationStatus.ts• L604-641
References: src/…/ClientRegistrationStatus.ts• L58-100 src/…/ClientRegistrationStatus.ts• L128-151 src/…/ClientRegistrationStatus.ts• L385-447 src/…/ClientRegistrationStatus.ts• L604-641
Registration removal
rea uninstall removes only registrations and managed workflow files that REA can prove it owns. It inspects all applicable client boundaries first. If a configuration is unsafe or removal could activate a foreign or shadowed entry, it keeps the file and reports the reason instead of guessing. src/…/Uninstall.ts• L187-220 src/…/Uninstall.ts• L351-389
Removal keeps unrelated servers and settings. Shared files are edited once through their owning configuration view, then the result is reported for clients that read the same file. An unresolved shared product is retained without blocking unrelated removals, while an established owned registration remains actionable. src/…/Uninstall.ts• L322-348 src/…/Uninstall.ts• L504-587
The uninstall sequence performs preflight before mutation. A removal failure stops later removals and reports completed work. Optional purge removes only REA-owned cache and state namespaces. It does not remove analysis providers such as Hopper. src/…/Uninstall.ts• L193-318 src/…/Uninstall.ts• L1199-1296
For client-specific registration workflows and native formats, see MCP client registration. For command syntax, output, and exit behavior, see command-line interface.
References: src/…/Uninstall.ts• L187-220 src/…/Uninstall.ts• L322-389 src/…/Uninstall.ts• L504-587 src/…/Uninstall.ts• L1032-1177 src/…/ClientRegistrationBackup.ts• L65-96
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the supported-client catalog, path evidence, and registration status reader aligned. A new path or profile can otherwise be writable by setup but invisible to doctor or uninstall.
- Keep launcher ownership rules aligned between setup admission, doctor status, and uninstall removal. A change in one can turn a safe refresh into a foreign overwrite or leave an owned row behind.
- When a client adds a configuration layer or fallback, update effective-configuration reads and removal preflight together. The active entry can change when an earlier layer or fallback becomes visible.
- Preserve the setup plan's client environment contract when adding a supported REA setting. The setting must be validated, written in the client's native shape, and visible to the client after restart.
- Keep native alias normalization aligned with each client's parser and writer. Accepting two equivalent fields can still create duplicate or conflicting data in the client's document.
- Keep private-profile backup permissions aligned across setup and uninstall. A new backup or recovery path must remain an owner-only regular file and must preserve the bytes that the planned edit inspected.
- Keep optional provider work separate from approved client actions. A provider failure must remain visible without silently removing successful registrations.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
Existing rea entry points to a foreign or unresolved REA launcher | Setup does not overwrite it | Launcher ownership admission requires a proven current entrypoint |
| Selected configuration is malformed or has invalid REA settings | The selected setup plan stops before mutation | Preflight parses each selected client and reports remediation |
| Registration uses a non-stdio transport or malformed stored arguments | Ownership facts may be retained, but the connection is not ready for local setup | Separate launcher parsing from stdio connection admission |
| Client file changes after planning | The client is not updated from stale contents | Publication checks the selected file before and after the write |
| Running client can rewrite its configuration from memory | The new registration can disappear | Setup requires the client to be fully quit when the client has this behavior |
| Native environment aliases conflict or contain invalid values | REA refuses the update instead of choosing a value | Parse aliases as one client policy and emit one canonical field |
| Private backup path is not a regular owner-only file | Setup or uninstall does not proceed with an unprotected recovery copy | Backup handling checks the path and applies private permissions before preservation |
| Optional provider download fails during approved setup | Setup reports remediation while completed client work remains applied | Keep provider actions separate from client and workflow actions |
| Shared storage has no product applicability evidence | Uninstall retains the shared file | Removal separates product evidence from REA ownership evidence |
| Removing REA would expose a foreign duplicate or fallback | Removal stops to avoid activating another registration | Uninstall checks shadowed entries and fallback views before editing |
Key files
| File | Why to read it |
|---|---|
| src/…/SupportedClients.ts | Defines the supported client catalog, path resolution, discovery evidence, and manual boundaries. |
| src/…/ClientConfigRoots.ts | Defines the host and environment rules used to resolve client configuration roots. |
| src/…/Setup.ts | Shows the end-to-end discovery, approval, apply, and final-readiness flow. |
| src/…/SetupPlan.ts | Explains client selection, preflight, and the actions shown for approval. |
| src/…/SetupClientConfiguration.ts | Shows how one client registration is validated, updated, verified, or rejected. |
| src/…/ClientRegistration.ts | Defines launcher parsing, native policy checks, and safe field normalization. |
| src/…/ClientRegistrationBackup.ts | Defines private-profile backup protection shared by setup and uninstall. |
| src/…/ClientRegistrationStatus.ts | Defines doctor’s registration states and remediation model. |
| src/…/ClientConfigurationPublication.ts | Defines safe publication and readback of changed configuration. |
| src/…/SetupRecoveryBackup.ts | Defines matching recovery snapshots and their verification. |
| src/…/Uninstall.ts | Explains ownership-safe removal and reporting across shared or layered files. |
| src/…/setupCommands.ts | Defines the user-facing setup, doctor, uninstall, and setup-scope options. |