# Set up Ohho for your AI coding agent This playbook is a preview. Agent setup does not work end-to-end today. It is coming with ohho-os 1.2.0, which is not on PyPI. The package on PyPI as of 17 Oct 2026 is ohho-os 1.1.2. Commands below that need 1.2.0 say so. Check `ohho --help`. If the command is missing, record the step as blocked: not released, and continue. Do not report a step as done unless you saw it succeed. Console: https://console.ohho-robotics.com ## How to run Run section 1 once per machine. Run sections 2 and 3 once per coding agent. Perform the actions yourself when you have a terminal or can edit files. Pause only for sign-in, an approval prompt, or a physical action. If a step is blocked, record why and continue with the remaining steps. Do not stop after the first blocked command and hand the rest back as a list, except when the next action is sign-in, approval, or physical. Global or user scope is the default. Do not add a robot during setup. Do not arm hardware during setup. ### Safety rules - The only transport in this playbook is `sim://`. Sim first. - Never arm. Never call release-stop. - Stop on any safety refusal. Do not retry a refused action by another route. - Ask the human for anything physical. The human has to be present before a real robot moves. - Do not set the hardware-arming environment variable. Do not type an arming confirmation. Section 5 says what the human does instead. - Do not call a tool that arms hardware, releases an e-stop, or changes a limit. - There is no API key in this setup. Do not invent one. Do not configure a hosted MCP URL. The MCP server in this playbook is the local stdio process, and it is `sim://` only. ## 1. Install and log in Check Python. OhhO OS needs Python 3.10 or newer. ```sh python --version ``` If `python` is missing or older than 3.10, try `python3 --version`. If neither is 3.10 or newer, record the install as blocked and go to the completion report. Check for an existing CLI: ```sh ohho version ``` `ohho version` is in ohho-os 1.1.2. If the shell reports that `ohho` is missing, install the PyPI package: ```sh pipx install ohho-os ohho version ``` If `pipx` is missing, use the user install: ```sh python -m pip install --user ohho-os ohho version ``` If `ohho` is still not on `PATH`, record the install path the installer printed and continue with whatever later checks can run. Do not add a robot. Do not arm anything. Sign-in is a device flow on the console. It is not in ohho-os 1.1.2. > Requires ohho-os 1.2.0 (not released yet). If `ohho --help` does not list this command, record the step as blocked: not released, and continue. ```sh ohho whoami ``` If the command is missing, record signed-in state as `not signed in: not released` and continue at section 2. If the command runs and nobody is signed in, start the device flow. Pause until the user finishes it in the browser. > Requires ohho-os 1.2.0 (not released yet). If `ohho --help` does not list this command, record the step as blocked: not released, and continue. ```sh ohho login ``` `ohho login` prints a device code and this URL: ```text https://console.ohho-robotics.com/device ``` The user opens that URL, enters the code, and approves the CLI. You do not approve it for them. When they say they have approved it, verify: > Requires ohho-os 1.2.0 (not released yet). If `ohho --help` does not list this command, record the step as blocked: not released, and continue. ```sh ohho whoami ``` Sign out only if the user asks: > Requires ohho-os 1.2.0 (not released yet). If `ohho --help` does not list this command, record the step as blocked: not released, and continue. ```sh ohho logout ``` ## 2. Install Ohho agent rules Run this once for the current agent, at user scope. The rules teach: sim first, never arm, never call release-stop, stop on any safety refusal, and ask the human for anything physical. > Requires ohho-os 1.2.0 (not released yet). If `ohho --help` does not list this command, record the step as blocked: not released, and continue. ```sh ohho rules install --client "" ``` Use the exact client string from section 3. If the installer prints a path, keep it for the completion report. If the command is missing, record `Rules: blocked: not released` and continue. Do not write a substitute rules file and call it installed. ## 3. Connect Ohho MCP Run this once for the current agent. The server is local stdio. It serves `sim://` only. > Requires ohho-os 1.2.0 (not released yet). If `ohho --help` does not list this command, record the step as blocked: not released, and continue. ```sh ohho mcp connect --client "" ``` Use one of these exact client strings: - `Claude Code` - `Codex` - `Cursor` - `VS Code` - `Gemini CLI` - `Windsurf` - `OpenCode` The process that config must launch is this local server: > Requires ohho-os 1.2.0 (not released yet). If `ohho --help` does not list this command, record the step as blocked: not released, and continue. ```sh ohho mcp serve ``` If `ohho mcp connect` is missing, record MCP as blocked for the helper command, then write the manual config for the client you are running in. Still back the file up, still merge, and still launch only `ohho mcp serve` when that command exists. If `ohho mcp serve` is also missing, write the config only if the user wants it ready for 1.2.0, and record MCP as `blocked: not released`. Before you change a config file: 1. Read the file. If it does not exist, you will create it with only the Ohho entry. 2. Copy an existing file to a backup beside it. Use the same name plus `.bak` and the date. Do not skip the backup. 3. Parse the existing JSON or TOML. Add the Ohho entry. Leave every other key as it was. 4. Never replace a file with a document that contains only the Ohho entry when other entries were already there. 5. If an `ohho` entry is already present, leave it unless the user asked you to change it. Record the path. Paths below were checked against each client's docs on 17 Oct 2026. The Sources list has the URLs. If a product's own "open config" action shows a different file, merge into that file and record the path you edited. ### Claude Code Docs: user scope is stored in `~/.claude.json`. Stdio servers are added with `--transport stdio`. Flags go before the server name. The `--` separates those flags from the server command. > Requires ohho-os 1.2.0 (not released yet). If `ohho --help` does not list this command, record the step as blocked: not released, and continue. ```sh claude mcp add --transport stdio --scope user ohho -- ohho mcp serve ``` Inspect existing servers before you add one. Do not remove servers you did not add. ### Codex Docs: `codex mcp add -- ` writes the user config at `~/.codex/config.toml`. A project file `.codex/config.toml` exists for trusted projects. Use the user file unless the user asked for one project. Inspect first with `codex mcp list` when that command exists. > Requires ohho-os 1.2.0 (not released yet). If `ohho --help` does not list this command, record the step as blocked: not released, and continue. ```sh codex mcp add ohho -- ohho mcp serve ``` Manual merge, if you edit the TOML yourself: ```toml [mcp_servers.ohho] command = "ohho" args = ["mcp", "serve"] ``` Add that table. Do not delete other `[mcp_servers.*]` tables. ### Cursor Docs: global config is `~/.cursor/mcp.json`. A project file is `.cursor/mcp.json`. Use the global file unless the user asked for one project. The stdio examples use `mcpServers`, `command`, and `args`. Back up the file, then merge this entry: ```json { "mcpServers": { "ohho": { "command": "ohho", "args": ["mcp", "serve"] } } } ``` The same docs page lists `type` as a stdio field. If other servers in the file you are editing set `"type": "stdio"`, set it on `ohho` too. Do not drop their entries. ### VS Code Docs, checked 17 Oct 2026: the preferred personal file is `~/.copilot/mcp-config.json`, or `$COPILOT_HOME/mcp-config.json` when `COPILOT_HOME` is set. That file uses a top-level `mcpServers` object. Use the same `command` and `args` as the Cursor entry. The user-profile `mcp.json` is still documented. Open it with the command MCP: Open User Configuration. That file uses a top-level `servers` object: ```json { "servers": { "ohho": { "type": "stdio", "command": "ohho", "args": ["mcp", "serve"] } } } ``` Workspace `.vscode/mcp.json` uses `servers` as well. The docs prefer the portable files for a new server. If the user already has an Ohho entry in one of these files, merge there instead of creating a second one. Back up the file you edit. ### Gemini CLI Docs: user config is `~/.gemini/settings.json`. Project config is `.gemini/settings.json`. `gemini mcp add` defaults to project scope. Pass `--scope user`. > Requires ohho-os 1.2.0 (not released yet). If `ohho --help` does not list this command, record the step as blocked: not released, and continue. ```sh gemini mcp add --scope user ohho ohho mcp serve ``` The name is `ohho`. The command is `ohho`. The arguments are `mcp` and `serve`. Manual merge goes under `mcpServers.ohho` with `"command": "ohho"` and `"args": ["mcp", "serve"]`. Leave the rest of `settings.json` in place. ### Windsurf Docs, checked 17 Oct 2026: the Cascade MCP page says Cascade is the legacy agent, and the default Devin Local agent reads Devin CLI config instead. The `mcp_config.json` path on that page is: - macOS and Linux: `~/.config/devin/mcp_config.json`, or `$XDG_CONFIG_HOME/devin/mcp_config.json` when `XDG_CONFIG_HOME` is set - Windows: `%APPDATA%\devin\mcp_config.json` The JSON shape is `mcpServers` with `command` and `args`, the same entry as Cursor. Open the file from the product's MCP config action when that action exists, and merge into the file it opens. Record that path. The page fetched on 17 Oct 2026 does not list `~/.codeium/windsurf/mcp_config.json`. Do not create that older path unless the in-app action opens it. ### OpenCode Docs: local servers live under `mcp` in `opencode.json`. `"type": "local"` and `"command"` is an array. Global config is `~/.config/opencode/opencode.json` (`opencode.jsonc` is valid too). Project config is `opencode.json` in the project. Use the global file unless the user asked for one project. Back up the file, then merge: ```json { "mcp": { "ohho": { "type": "local", "command": ["ohho", "mcp", "serve"], "enabled": true } } } ``` Do not replace other `mcp` servers. Do not point OpenCode at a remote URL for this setup. ## 4. Verify Try the agent check first. > Requires ohho-os 1.2.0 (not released yet). If `ohho --help` does not list this command, record the step as blocked: not released, and continue. ```sh ohho doctor --agent ``` That check is meant to report the CLI version, login, rules, whether an MCP config was found, and whether `sim://` is usable. It is not in ohho-os 1.1.2. When the local MCP server from section 3 is actually connected, use its tools, in order: 1. Connect to `omnibot` on `sim://`. 2. Read telemetry. 3. Drive at 0.1 m/s for 1 second. 4. Stop. 5. Read telemetry again. Stay on `sim://`. If a tool name differs, use the tool the server lists for that action. If the server has no such tool, record that action as not run. Refuse any tool that arms, releases an e-stop, or changes a limit. There is a single sim-verify command for the same check: > Requires ohho-os 1.2.0 (not released yet). If `ohho --help` does not list this command, record the step as blocked: not released, and continue. ```sh ohho verify --sim ``` Use the MCP steps or `ohho verify --sim`, not both, once one of them has run. If both are blocked, say the sim drive was not run. The console simulator is optional and only when it is available: ```text https://console.ohho-robotics.com/sim ``` If that page is missing, record it and continue. It is not a failure of the CLI. When the 1.2.0 checks are blocked, run the checks that exist on ohho-os 1.1.2. These were confirmed in `ohho/cli.py` on the v1.1.2 tag. They do not replace the MCP drive. The report must say the MCP drive was not run. ```sh ohho version ohho doctor ohho sim --robot omnibot --seconds 2 ``` `ohho sim` uses `sim://` and exits when `--seconds` is set. It does not arm hardware. ## 5. Real robots Do this section only if the user asks and is present. Otherwise skip it. Setup never arms hardware. `ohho connect` is in ohho-os 1.1.2. On the v1.1.2 tag, `ohho connect` does not list `--arm` (checked 17 Oct 2026). Current ohho-os main does. The human runs the arming command only when `ohho connect --help` lists `--arm`. If it does not, record hardware as blocked and stop. Do not look for another way to move a real robot. The human, present at the robot, does this in their own terminal. The human sets OHHO_ARM_HARDWARE=1, runs the command in the next block, and types the confirmation the CLI prints. ```text ohho connect --transport --arm ``` You do not run that command. The agent never sets OHHO_ARM_HARDWARE, never passes --arm, never types the confirmation, and never calls release-stop. The human picks the robot id and the transport URI. You do not invent a serial port, a host, or a confirmation word. If the CLI refuses to arm, stop and tell the user what it printed. ## 6. Completion report Report only verified state. Write `blocked` and the reason for any step you did not see succeed. Do not write that login, rules, MCP, or the sim drive succeeded unless that is what the commands printed. The local stdio server in the template is the server from section 3. > Requires ohho-os 1.2.0 (not released yet). If `ohho --help` does not list this command, record the step as blocked: not released, and continue. ```text Ohho agent setup CLI: (), signed in as Rules: MCP: , local stdio `ohho mcp serve`, config Verify: ; sim drive Hardware: not armed (agents cannot arm; ask the user) Reload: ``` Reload or restart the client only if the new rules or the MCP server do not show up. If they already show up, say reload was not needed. ## Sources Checked 17 Oct 2026. - ohho-os 1.1.2 CLI: https://github.com/ohho-robotics/ohho-os/blob/v1.1.2/ohho/cli.py - ohho-os main CLI (has commands the 1.1.2 tag does not): https://github.com/ohho-robotics/ohho-os/blob/main/ohho/cli.py - PyPI: https://pypi.org/project/ohho-os/1.1.2/ - Install notes on this site: https://ohho-robotics.com/docs/ohho-os/install - Console: https://console.ohho-robotics.com - Claude Code MCP: https://code.claude.com/docs/en/mcp - Codex MCP: https://developers.openai.com/codex/mcp - Cursor MCP: https://cursor.com/docs/mcp - VS Code MCP: https://code.visualstudio.com/docs/copilot/customization/mcp-servers - Gemini CLI MCP: https://geminicli.com/docs/tools/mcp-server/ - Windsurf Cascade MCP: https://docs.windsurf.com/windsurf/cascade/mcp - OpenCode MCP: https://opencode.ai/docs/mcp-servers/ - OpenCode config paths: https://opencode.ai/docs/config/