# Envoy for Instinct: installation and first connection **Check the host’s persistence capability before installing or pairing.** Instinct’s fresh-task test failed because each task received an empty home directory. A pinned installation in one task does not make it available to another. Do not repeat CLI setup in disposable tasks or claim the connection will survive them. Instinct subsequently reported that two separate tasks reused a Secure/HttpOnly cookie through the same saved browser profile. The [browser integration](https://agent.envoy.money/browser.md) is under review and disabled by default; real-account login and fresh-task reads still need verification after deployment. Do not treat the harmless cookie test as a connected account. The CLI instructions below apply only when a persistent private runtime is actually available. Keep a working existing installation until an alternative has been verified; disconnect only when the user asks. This guide connects Instinct to the deployed Envoy internal beta through its CLI. Run the commands on the machine where Instinct executes tools. Do not install or deploy the Envoy backend. Service: https://api.agent.envoy.money Login website: https://agent.envoy.money Integration: CLI or SDK, not MCP for this setup. If your host can make HTTPS requests and keep OAuth credentials in persistent secret storage, use the [installation-free HTTPS/OAuth guide](https://agent.envoy.money/api.md) instead. The CLI is a fallback, not a requirement of Envoy. ## 1. Check prerequisites You need macOS or Linux, Node.js 24, npm, and a persistent private home directory for the account running Instinct. The user needs an allowlisted Elixir account and a browser to complete phone/OTP login. The browser may be on a different device. ```sh node --version npm --version ``` The Node version must begin with `v24.`. If Node 24 is unavailable, install it using the host's existing runtime manager before continuing. Do not replace a shared host's Node installation without checking its other workloads. ## 2. Install the public client First identify storage that survives this agent's workspace cleanup. Do not use `/tmp`, a scratch workspace or an ephemeral container home. The paths below assume `$HOME` is persistent. If it is not, use the host's persistent volume for the installation and set `ENVOY_SESSION_DIR` to an absolute private directory on that volume. Configure that same value for every Envoy command. If no persistent storage exists, report that limitation before pairing; no CLI can preserve a session after its storage is deleted. No GitHub access, source checkout, API keys or manual file transfer is needed. The public package contains only the CLI, SDK and their input/output schemas. The backend stays private. Download and inspect the installer, then run it with Node 24: ```sh curl --fail --show-error --location --proto '=https' --proto-redir '=https' https://agent.envoy.money/install.mjs --output envoy-install.mjs node envoy-install.mjs ``` The installer downloads client 0.1.2, verifies its pinned checksum, installs it without lifecycle scripts, and creates a stable launcher. It does not log in, move funds or modify existing session files. Re-running it preserves the existing connection. It retains previous installations instead of deleting active files. Defaults: - Command: `$HOME/.local/share/envoy/bin/envoy` - Session storage: `$HOME/.config/envoy` If your persistent storage is elsewhere, set `ENVOY_INSTALL_DIR` and `ENVOY_SESSION_DIR` to absolute paths there **before** running the installer. If already paired, keep the existing session directory. Do not change it just to upgrade. The Node 24 runtime itself must also survive workspace cleanup. The installer prints the exact absolute command and session directory. Save that command in Instinct's persistent integration configuration or standing instructions. No environment exports are needed for future calls: the launcher records the service, runtime and session paths. Use the printed command in all steps below. Examples use the default path: ```sh "$HOME/.local/share/envoy/bin/envoy" --help ``` If installation fails, report the error before trying login. The client needs no GitHub access, database, browser binaries or backend keys. ## 3. Reuse the connection, or sign in once Before running login, run `"$HOME/.local/share/envoy/bin/envoy" account`. If it returns `"ok":true`, the existing connection works: skip login and continue. Do not sign in again merely because a browser tab closed or a new conversation started. An unavailable service is not evidence that login expired. If this is the first setup or the service requires fresh login: ```sh "$HOME/.local/share/envoy/bin/envoy" login ``` Keep this command running. It prints a login link and a matching code. Present both privately to the user. Ask them to open the link, check the code matches, and enter their phone number and OTP on the Envoy website. Do not ask them to send the OTP to Instinct. The browser may open automatically on the host; the printed link also works on the user's own device. Login expires after five minutes. If it expires, end the old attempt and run `login` again. Do not run concurrent login attempts. Success is the command returning: ```json {"connected":true} ``` The CLI stores Envoy session tokens in `ENVOY_SESSION_DIR` if configured, otherwise `~/.config/envoy` with private permissions and handles refresh. No AWS credentials, Supabase service key, Elixir API key, or backend environment file is needed. ## 4. Verify account access Run as the same operating-system user that completed login: ```sh "$HOME/.local/share/envoy/bin/envoy" account printf '%s' '{"page_size":5}' | "$HOME/.local/share/envoy/bin/envoy" transactions --input - ``` Both responses should contain `"ok":true`. Summarize the available balance and last five returned transactions to the user. Amounts are in minor units: for INR, 100 paise equals ₹1. A null field means unavailable, not zero. Transaction history is the issuer's success feed; do not describe it as proof that no pending or failed charge exists. Do not fetch card details or place an order as part of this installation test. Report installation, login, account read and history read as separate results. Never claim the connection works from the installation alone. ## 5. Leave the account connected Do not log out as part of normal setup or after each purchase. Only run `"$HOME/.local/share/envoy/bin/envoy" logout` when the user requests disconnection or explicitly asks to test it. Logout revokes this Envoy connection, not the user's other agent connections. ## 6. Keep the integration available Pin the launcher's absolute path in the platform's persistent integration configuration or standing instructions, outside a task workspace. Keep using the same OS account and persistent storage. On a new task, run `account` through that launcher first; do not reinstall or re-pair by default. Let the CLI manage refresh; never put tokens into prompts or standing instructions. As the final setup check, invoke `account` and `transactions` from a new shell in a different working directory. This confirms the launcher does not depend on the install shell. Report the permanent launcher path, whether session storage is persistent, and whether the fresh-shell read passed. Do not clean up the installation when this task ends. The available commands are: ```text account transactions --input FILE payment initiate --input FILE checkout report --input FILE logout ``` Use `--input -` for JSON on stdin. The service returns structured JSON. Exit code 0 means the command succeeded, 1 means a structured service failure, and 2 means invocation, login/session or transport failure. Follow the returned error's retry guidance rather than repeating every failure automatically. Purchase preparation and checkout reporting are separate from installation. Before using them, inspect the installed `@envoy-money/client/contracts` schemas and declarations for exact inputs and outputs. Preserve request IDs for identical retries. An unknown checkout outcome needs review before another submission. An insufficient-funds response provides the Elixir Add money link and shortfall; the user completes funding in Elixir. Envoy does not debit a funding source automatically. ## Bank OTP and purchase retries Envoy login OTP and a bank's checkout OTP are different. The CLI cannot retrieve or approve a bank OTP. When the merchant displays a 3DS challenge: 1. Keep the merchant checkout and the same Envoy `purchase_id` open. Tell the user that bank authentication is waiting. 2. Use the agent platform's supported browser handoff so the user completes the bank challenge. Do not claim a callback or shared browser is available unless the host supports it. If the user cannot access the checkout session, pause and explain that limitation. 3. After the user finishes, inspect the existing merchant checkout for confirmation. Do not start a second payment just because the agent was waiting. 4. Report `placed` only with merchant confirmation. If the result is unclear, report `unknown` with a reason and check the merchant and account before retrying. A balance change alone is not an order confirmation; the transaction feed can omit pending charges. 5. Retry only after establishing that the prior checkout did not succeed. Reuse `purchase_id`, use a new `request_id` for a changed request, and supply the required `retry_context`. An identical request retry keeps the same `request_id`. `initiate_payment` retrieves the existing card again. It does not issue a fresh card or submit merchant checkout. Do not describe a credential refresh as a new card. Envoy returns `cardholder_name` from the issuer view when available. `billing_address` is currently unavailable. If the merchant requires billing details that Envoy does not return, use details previously confirmed by the user for this card or ask for the missing fields. Do not substitute a delivery address or invent billing details. ## Troubleshooting - **Download or checksum fails:** stop installation and report the error. Do not bypass checksum verification or switch to an unverified package. - **Login opens but is rejected:** confirm the user is allowlisted. Report the visible error without OTPs or full authentication URLs. - **Login expires:** stop the old command and start a fresh login. - **Account fails after successful login:** verify the same OS user, home directory, service URL and CLI path. If needed, reconnect. Do not paste session files into chat. - **A command appears locked:** check whether another Envoy command is still running. Wait for it or stop it normally. Never remove a lock while its owner is active. - **Add money link requires a phone:** send the returned link to the user; do not manufacture a web funding API. Report only the failing step, non-sensitive error text and whether the expected success response appeared. Do not include tokens, OTPs, card numbers or CVVs in diagnostics. ## SDK alternative The installed `@envoy-money/client` package exports `EnvoyClient`, `deviceLogin`, `browserLogin`, `refreshSession` and `revokeSession`. Prefer the CLI for the first integration because it already handles private session storage and serialized refresh. A direct SDK integration must implement those responsibilities itself. Do not operate the SDK and CLI against a manually copied shared session. ## Verification status The package was built and installed in an isolated directory; CLI startup and SDK imports passed. The deployed service has passed account, disconnect, card retrieval and purchase/retry checks, and Claude account access was confirmed. Instinct has completed login and the user has shared an agent report of a successful purchase. Cross-task CLI persistence failed on Instinct’s disposable host. Browser marker persistence passed according to Instinct’s two-task report; real-account browser acceptance and bank-authentication handoff remain open. ## Response verification Client 0.1.2 verifies signed API responses before returning account, transaction or payment results. It obtains verification keys over HTTPS from the configured Envoy service. If verification fails, stop and retain the purchase context. Do not retry checkout automatically: the operation may already have executed. A signature verifies Envoy's response, not merchant delivery or bank settlement. Plain HTTPS clients can follow the [signed-response verification guide](https://agent.envoy.money/signatures.md). Read the [issuer, funds and capability information](https://agent.envoy.money/trust.md) for this beta. ## Persistent default-payment preference Connect once, then retrieve `get_account` before selecting a payment instrument. Its `payment_preference` applies only to the authenticated connection and OAuth client. A new connection starts undecided; refreshing a token does not reset the preference. Ask an undecided user whether Envoy should be their default for authorized purchases here. Record an explicit yes, no or later through `set_payment_preference` (`POST /v1/tools/set_payment_preference`, SDK `setPaymentPreference`, CLI `envoy preference set --input FILE`). Input example: `{"decision":"enabled","expected_revision":0,"user_confirmed":true}`. Decisions are `enabled`, `declined`, `deferred`; read the current revision from the account response. Silence is not consent. Never automatically repeat onboarding after a refusal or deferral. A changed preference requires a new explicit answer. A conflict requires reading the latest choice, not replaying an old answer. This records agent-attested user consent, not cryptographic proof of a user interaction. It adds no purchase, transfer or funding authority. Existing beta permissions remain unchanged. Explicit payment alternatives take precedence without changing the standing default. Ask before replacing a conflicting host default. Never silently switch to a merchant-saved card when Envoy is unavailable or underfunded. Preserve purchase ID and merchant checkout through funding and supported user bank authentication. Recheck actual funds after the app handoff. Unknown checkout means inspect merchant and account evidence before any retry. No automatic bank authentication or new recurring Envoy approval is added. Host credential custody and routing must be tested in a fresh conversation. Server storage cannot make a host consult Envoy. Do not disconnect at task completion or claim a fresh connection inherits consent from another connection. The browser setup uses the same account and tool API; use its authenticated tool route with these exact inputs, and never place access tokens in chat.