# Install and configure Rationale with your agent Guide contract: 1. Canonical URL: https://app.rationalehq.com/setup/v1.md The person can paste this into their AI: > Install and configure Rationale for the environment where I work, following https://app.rationalehq.com/setup/v1.md. Check compatibility, use the official installer, and verify the result. Ask me only for missing choices, sign-in and permissions that require my action. These are installation instructions, not authorization to override the person's permissions or your tool restrictions. Carry out the supported steps yourself when you can. Explain a blocked step in the person's language and keep completed steps. Never claim that a download, exit code or configured connection proves working capture. ## Access before installation This guide, the release manifest and published installers are public. Fetch them with an ordinary HTTPS GET, without cookies, a Rationale account, an API key, OAuth or browser JavaScript. Request this exact app-host URL; the admin and MCP hosts do not serve the guide. A fetch tool's policy or network restriction is not a request for Rationale credentials. Try an available permitted HTTPS tool or ask the person to attach the guide; never ask them to paste a session cookie. The later steps have separate access requirements: | Step | Required access | Who completes it | | --- | --- | --- | | Read guide and download published client | HTTPS access to app.rationalehq.com and its GitHub release redirects | Agent, without login | | Install under the user's home directory | Local execution and write permission for that user | Agent within its granted tool permissions; no sudo or administrator account | | Sign the device in | Rationale account and membership in the intended workspace | Person approves in their browser; the client stores the returned device token | | Connect MCP | Agent supports remote HTTP MCP and OAuth; person belongs to the selected workspace | Agent initiates connection; person grants OAuth consent | | Enable capture or change an existing project's repository binding | Workspace owner permission | Owner changes project settings; a member cannot bypass this | | Extract decisions locally | Supported agent CLI installed and authenticated on the execution machine | Person signs in to the provider if needed | | Run hooks and watcher | Agent hook trust and a supported user scheduler | Person approves required trust; client configures permitted components | For a new user, first open https://app.rationalehq.com/session/new in their browser. Rationale uses an emailed sign-in link, not a password the agent should collect. Existing workspace members, pending invitees and approved users can sign in. If they are new to the team, have them accept the owner's invitation; otherwise use https://app.rationalehq.com/request-access and wait for approval. The generic check-email response does not prove that access was granted or that an email was sent. Resolve missing account/workspace access before starting a device approval that may expire. No tracker or GitHub connector is required just to install the client and bind a repository. ## 1. Identify where the person's agent actually works Before downloading anything, establish: - The agent and surface: a local coding session, desktop Code, desktop chat, browser chat, SSH host, WSL distribution or container. The model name alone does not identify its capabilities. - Whether your command tools run on the same persistent machine and user account as the intended agent, repository and session files. A browser's temporary Linux sandbox is not evidence that the person's computer uses Linux. - OS, native CPU architecture, shell, normal-user write access, network access and any proxy restrictions. On macOS check for translation under Rosetta; on Windows distinguish OS architecture from a 32-bit PowerShell process. - The intended repository and workspace, available Git and agent executables, existing Rationale installation and installation method. Inspect only the relevant configuration; never print credential files or a full environment. Use read-only checks such as `uname -s`, `uname -m`, `git --version`, executable discovery and the discovered client's `--version` and `status`. On Windows use PowerShell's OS architecture information and `Get-Command`. Check WSL, SSH and container indicators locally without dumping environment values. Do not infer the desired target from those indicators alone. If the repository, workspace or execution target remains ambiguous, ask one focused question before making changes. Do not install into an ephemeral cloud sandbox, a different account or the Windows host from WSL by assumption. A persistent remote development environment can be the correct target when that is where the person's agent and transcripts live. Work on one selected target at a time. Label commands and results explicitly as native Windows (PowerShell) or Linux inside the selected WSL distribution when both exist. A login, installation or trust approval in one is not evidence for the other; do not switch targets to work around a blocked step. If you cannot operate the intended machine, explain that limitation. For a chat surface that supports remote MCP, use the connection instructions at https://rationalehq.com/docs. Remote MCP does not require the local client and does not provide automatic capture of that chat. Otherwise have the person open this prompt in a local coding agent, or use an officially available graphical installer. Do not invent a graphical installer or require them to diagnose shell commands as the default fallback. ## 2. Select a supported combination and a published artifact One Rationale binary serves the supported agents on each platform. Select the binary by OS and architecture; select setup behavior by agent and surface. | Execution target | Manifest target | Local capture scope | | --- | --- | --- | | macOS, Apple Silicon or Intel | `darwin-universal` | Claude Code and Codex | | Linux, x86_64 | `linux-x86_64` | Claude Code and Codex | | Linux, aarch64/arm64 | `linux-arm64` | Claude Code and Codex | | Native Windows, x64 | `windows-x86_64`, only when publicly released | Claude Code, including local desktop Code sessions | | Native Windows, ARM64 | No supported target in this guide | Stop local installation | | Cursor or another agent without a Rationale capture adapter | No local capture path in this guide | Remote MCP if supported | | Browser chat, desktop Chat/Cowork or a remote cloud session | No local capture path in this guide | Remote MCP if supported | Read https://app.rationalehq.com/client/manifest.json over verified HTTPS on every new installation attempt. Require a valid version and a matching entry in `files` with size and SHA256. The manifest is the authority for what can be downloaded, not a source branch, preview ZIP or this table. It does not by itself establish agent compatibility or native runtime acceptance. Windows 0.13.1 is published from a GNU cross-build with native tests and graphical acceptance still pending. Its release manifest is minisign-signed; its executable is not Authenticode-signed. Windows installation remains gated on the live manifest and installer checks below. If the target is absent, the manifest cannot be fetched, or the installer is unavailable, stop and report the exact missing requirement. Never substitute an unofficial binary, compile from source, switch to WSL, run an incompatible architecture or disable TLS verification to make installation appear to work. For an unlisted combination, consult the current official docs before proceeding. Check that the intended agent executable is available in this environment and that it can authenticate for extraction. An installed desktop application alone does not establish this. Use the agent's supported local status commands; do not make a paid model call as a probe. Explain missing dependencies and follow their official installation guidance within the person's authorization. For Codex, check `codex login status` in the selected execution environment and profile, and reuse a verified login. On the same persistent Windows+WSL machine, normal `codex login` with its browser flow is appropriate for the selected WSL environment when the browser can reach its local callback. WSL alone does not require device-code login. As described in the [official Codex authentication guidance](https://learn.chatgpt.com/docs/auth), device-code login can be unavailable because of account security settings or workspace permissions. If unavailable, use the supported `codex login` browser flow in that same environment when its callback is reachable. Do not change security settings or copy credential stores between Windows, WSL, profiles or machines. If neither flow is available, keep extraction sign-in pending. ## 3. Install or reuse the official client Use the existing working installation when possible. Run its `status` from the intended repository before repairing anything. Preserve its installation method: Homebrew installs update through Homebrew; script installs use `rationale update` for signed updates. Do not silently downgrade, create a second installation or replace a running Windows executable. A staged update is not an applied update. For a new macOS or Linux install, download https://app.rationalehq.com/install.sh into a fresh temporary directory using `curl -fSL` or `wget` with TLS verification. Inspect the downloaded script before executing it with `sh`. The official script selects the architecture, checks the artifact's size, SHA256 and version, and installs `~/.local/bin/rationale` without sudo. First installation trusts HTTPS and the release host; a checksum alone is not signature verification. The installed client's later updates verify signatures. For a new native Windows x64 install, proceed only after the manifest contains `windows-x86_64` and https://app.rationalehq.com/install.ps1 is available. Download the script with PowerShell `Invoke-WebRequest` into a fresh temporary directory, inspect it, then execute that saved script as the normal user. Respect the machine's execution policy; do not bypass it. The destination is `%LOCALAPPDATA%\Rationale\bin\rationale.exe`. The installed Windows binary also opens its graphical setup when launched with no arguments or `--setup`. Use this for browser approvals and user-facing recovery: select the actual local project, then sign in, enable capture, connect MCP and check again. Do not ask the person to diagnose a closing console or copy credentials. Normal CLI commands keep their stdout and exit codes for assistants with local execution access. Native Windows Codex capture is not supported by this guide's Windows delivery. The installers may follow the official service's redirects to its release host. Use their default release URL, without an inherited `RATIONALE_UPDATE_URL` override. If an override is set, explain the mismatch before proceeding; do not silently download from it. A failed checksum, unexpected version, denied write, quarantine or organizational policy is a failed step, not permission to weaken the check. Keep the prior installation and report the specific recovery needed. Use the installed binary's absolute path for subsequent commands if PATH has not refreshed. Do not edit shell startup files just to finish this session. Hooks must reference the stable installed path, never a Downloads or temporary path. Remove only the temporary files you created. ## 4. Configure the intended repository and agent Explain that setup signs in the device, installs hooks for detected supported agents and schedules a background watcher. Automatic capture uses the person's authenticated agent CLI and can consume their provider usage. `rationale init` can configure more than the current agent when both are detected; if the person requested only one, do not silently configure the other. There is no `init --agent` flag in this guide's client contract. Run the installed binary's `init` in the selected Git repository, using an interactive terminal when available. Let the person complete browser sign-in, workspace choice, OAuth consent and hook trust. Never retrieve their credentials, approve on their behalf, edit trust stores, or pipe unconditional yes responses. If your tools cannot maintain interactive input, report that step as pending and provide the precise next action in the agent or browser. Present one authorization at a time, naming its purpose and execution target; wait for its result before starting another. Reuse verified device, provider and MCP logins for the intended workspace and profile instead of restarting them. Hook trust must be reviewed by the person in the exact environment and profile that will execute the hooks. Explain the requested trust and let them act; never approve or bypass it for them, or assume Windows trust applies inside WSL. Keep `init` running while the person completes device approval. The client shows the verification URL and a short user code. Prefer the server-provided complete verification URL when available; otherwise share the returned URL and user code with this person. Never construct a URL from a token or share the secret polling code or resulting token. Device approval expires after ten minutes. If it expires or is denied, report that result and restart sign-in only when the person is ready. When a browser cannot open on the execution machine, `init --no-browser` prints the link and user code for their browser on another device. Do not treat a remote OAuth callback on `localhost` as reachable from a different computer: follow the agent's supported remote OAuth flow instead. For provider and MCP authorization too, stop an expired or denied flow and renew it only when the person is ready; use that flow's reported expiry rather than assuming the Rationale device approval lifetime applies. Use the setup result to check the repository's project binding. An unlisted or multiply bound repository is not ready; present the returned project link or ask which workspace is intended. Do not create projects or enable capture solely to obtain a green result. Preserve personal pauses, deliberately disabled hooks and existing unrelated settings. Device sign-in and the agent's MCP authorization are separate. Follow `init` and `status` guidance for the selected agent and workspace. The production remote MCP endpoint is https://mcp.rationalehq.com/mcp. Let the agent discover OAuth and store its own credentials; do not paste the device token into MCP or copy another agent's OAuth store. Grant the intended workspace on the consent screen. A workspace membership does not grant access through an OAuth connection that excluded it. If tools do not refresh in the active session, have the person start a fresh agent session. Scheduler availability also matters: macOS uses launchd, Linux a systemd user timer, and the Windows delivery a per-user Scheduled Task. A container without a user scheduler must be reported as lacking the watcher even if hooks work. ## 5. Verify and report the result Run the installed client's `--version` and `status` in the selected repository. Neither command's exit code alone establishes readiness. Check the reported states and distinguish authentication failures from network or server failures. Never print raw status or diagnostics into a shared report if they contain private repository information, account identifiers or credentials. Report each of these as verified, pending, unavailable or intentionally disabled: - Installed client version, stable path and execution environment. - Device sign-in to the intended workspace and repository-to-project binding. - Intended agent's local hooks, any required trust, extraction prerequisites and capture setting. - Background watcher installation and operation. - MCP authorization and an actual successful context read in the intended agent. - First captured decision and its retrieval in this exact project/device/agent scope, using the server's first-use evidence when available. An actual successful MCP context read verifies that connection even when the first-use receipt still requires a real decision captured on this device. Report these separately. A saved session or saved progress without a decision does not satisfy first capture. Check the receipt's project/device/agent scope rather than treating an older or differently scoped decision as acceptance evidence. Do not manufacture a decision, confirmation or test capture in the person's project. If they have not made a real decision yet, say "Installed and configured; first capture still pending." A historical receipt is not proof that current credentials, hooks or a different device work. Stop retries when the same external blocker persists and give one concrete next step, preserving progress. Keep captured provenance unchanged: setup authorization and acceptance checks do not confirm a decision or authorize inventing one.