Skip to main content
Use this guide for an existing JavaScript or TypeScript agent on Node.js 18+. The agent continues to run in your infrastructure. Python, MCP servers, and Codex itself have separate guides.

​
CLI connection

Run from the repository that owns the agent:
A Workspace Admin approves CLI access in the browser. The CLI creates or links the agent, saves .rippletide/project.json, writes RIPPLETIDE in a git-ignored .env, and presents a repository-specific instrumentation prompt. Apply that prompt with your coding agent. It adds inventory registration, causal tracing, tool guards and a response-delivery guard at the existing call sites. It does not replace the agent or its provider. For a headless coding-agent session, the human signs in first:
Use --agent <agentId> to link an existing agent. Re-running connect reuses the saved connection kind and can refresh setup. The CLI can run an existing rippletide:sync script after confirmation; --yes permits that script in a trusted repository. It does not invent the script, run rippletide:start, or start the agent.

​
App-based connection

Choose Connect → Agent and the JavaScript/TypeScript option in the app. Save its generated .env credentials and apply its generated prompt in your repository. The app/manual path uses RIPPLETIDE_AGENT_ID and RIPPLETIDE_API_KEY. The CLI path uses one RIPPLETIDE connection string. Use the configuration your chosen path generates; see API keys for rotation and precedence.

​
Prove the connection

Start your application and send a real request that uses a tool and delivers a response. Run:
The server validates the current inventory, heartbeat, expected tool call, turn and before-response evidence. In Context & actions, inspect the inventory. In Traces, open the run and inspect its tool calls and response outcome. A copied prompt or stored key proves setup only. A missing delivery receipt is not fixed by creating another agent. Check the instrumentation at the real response sink, using Manual TypeScript setup. Run rippletide doctor for configuration and evidence gaps. Review Privacy & capture before exporting runtime content. Declaring a third-party connection reports credential names/status, not the secret values.