Run Claude Code and Codex sessions on other machines over SSH, and open them in any terminal.
Install Ocho on each computer. Sessions keep running after you disconnect, and agents can send each other messages. With Ocho Attach, the agent’s interface runs on this computer, so typing doesn’t wait for the network.
Run ocho in the terminal or editor you already use.
ocho new in any tab and choose a machine. The session starts there and opens in the same tab.ocho in the editor’s terminal.localhost link from another machine opens in this browser, and files can be copied in either direction.Claude Code and Codex. For versions, see Supported agents.
Install Ocho on this computer. Adding a machine installs Ocho there too.
curl -fsSL https://fleet-service.eliot-4cd.workers.dev/releases/install-cli.sh | bashThe script checks the download against the release’s checksum, then installs ocho in ~/.local/bin. Make sure ~/.local/bin is on PATH.
To update this computer, run the install command again. Other machines update themselves to match. Running sessions move to the new version between turns, without restarting.
Start an agent on another machine in four steps.
# Add a machine you reach over SSH.
ocho add studio --install
# Add a Claude account.
ocho accounts add --provider claude
# Start a session in a project, and open it here.
ocho run studio --provider claude --cwd ~/project --attach
# Continue the session from any computer.
ocho resume 07ddaa9aTo choose everything from a menu instead, run ocho new. See Quick launch.
Any Mac or Linux computer you reach over SSH can run agents.
ocho add studio --install # studio from ~/.ssh/config
ocho add --local --name "This Mac" # this computer--install installs Ocho on the machine and sets up Ocho’s own SSH key, so an SSH agent isn’t needed.
Run ocho machines to see each machine’s status, load and number of sessions, with This Mac first. Press a to add a machine, r to rename one and d to remove one. Disposable cloud machines are hidden; press s to show every record.
A machine can have more than one address, such as a LAN IP, a Tailscale name and a DNS name. The fastest address that answers is used, and the choice updates when the network changes.
ocho machine add-address studio 192.168.0.60
ocho machine addresses studio --probeocho exec studio -- 'brew upgrade && df -h'ocho machine edit studio --name "Studio" --notes "Desk Mac" --tags build,ios
ocho machine edit studio --permissions claude=auto,codex=yolo # default permission mode for new sessions
ocho machine edit studio --transport ssh # never use moshTo install a supported release of Claude Code or Codex on a machine, run ocho machine update-provider studio claude. Machines keep installed agents up to date.
ocho machine prepare studio --count 5Ocho clones your five most-used repositories on studio and runs their setup scripts. Then an agent on studio finishes setting each one up, such as installing dependencies and building once. ocho machine prepare studio --status shows progress and the agent’s report. To skip the agent, add --provider none.
Commands you run yourself always work. When an agent runs ocho exec, or opens a shell on another machine, agent access decides whether it needs your approval.
Choose which machines agents can run commands on without asking.
Agents in Ocho sessions can start sessions on any machine, send messages, read transcripts and move files. Running a command or opening a shell on another machine with ocho exec is different: on a personal computer, the agent asks first.
Each machine is a personal computer or a worker.
ocho machine edit laptop --agent-role personal
ocho machine edit studio --agent-role worker
ocho machines --fields name,agent_role,agent_access_effectiveTo override a machine’s role, add --agent-access ask, allow or block to ocho machine edit. To let agents run commands on every machine, run ocho access policy unrestricted. Machines set to block stay blocked.
An agent that needs access to a personal computer makes a request, with a reason, and waits:
ocho access request laptop --reason "Build and test the iOS app"Review and answer requests from any terminal:
ocho access list MACHINE SESSION # requests from a session
ocho access allow MACHINE SESSION REQUEST # until the session ends, or for 24 hours
ocho access always-allow MACHINE SESSION REQUEST # any session on that machine, from now on
ocho access deny MACHINE SESSION REQUEST
ocho access revoke MACHINE SESSION REQUESTHere MACHINE is the machine the asking session runs on. Allowing never runs a command by itself: the agent runs it again after approval. A denied request stays denied, and an agent can’t ask again until you change it.
Access applies to ocho exec, shells on a machine, running programs there and terminal panes. Starting sessions, messages, transcripts, file transfers and previews always work.
Agent access keeps well-behaved agents from running commands on your computer without asking. It isn’t a security boundary: Ocho and its agents run as your user, so a process that ignores the rules can still use SSH directly. To isolate code you don’t trust, use a separate user account or a virtual machine.
Add each Claude and Codex account once. Every machine can use the account.
ocho accounts add --provider claude
ocho accounts add --provider codexEach command opens the provider’s sign-in. An account is named by its provider and email, such as claude:name@example.com. To use an API key instead of a subscription, add --api-key. API-key accounts show no usage limits.
Run ocho accounts to see each account’s remaining usage and when it resets. Sign in again or remove an account from there.
With the account set to Auto, the default, each session starts on the account with the most usage left for its model. When a session reaches its limit, continue on another account:
ocho handoff studio SESSION --account claude:other@example.com --yes # new conversation, same folder
ocho switch-account studio SESSION --account codex:other@example.com --yes # Codex: same conversationYour accounts are stored encrypted in Ocho’s service, and this computer holds the key that owns them. If you lose this computer, the recovery key is the only way to get them back. Save it somewhere safe, such as a password manager:
ocho cloud export-recovery ~/Desktop/ocho-recovery-keyOn a new computer, run ocho cloud recover PATH. The old computer’s key stops working.
Set up an MCP server once, and use the server from every machine and account.
Add the server with the agent’s own command and check that it works. Then share it by name:
claude mcp add linear --transport http https://mcp.linear.app/mcp
ocho mcp share linear --from claudeEvery Claude and Codex account on every machine gets the server. Sessions see it after their next launch.
--host-here. Other machines reach it over SSH.ocho mcp list # shared servers
ocho mcp unshare linearSharing reads stdio and Streamable HTTP servers from Codex’s config.toml or from Claude’s settings.
Install a Claude plugin with /plugin in one Claude account. Ocho offers to install it in the other Claude accounts on that machine.
Rent a Mac from Flow, AWS or Scaleway with your own account, and use it as a machine.
ocho rent connect flow # once per provider
ocho rent types # Macs in stock, with prices
ocho rent --type TYPEocho rent rents the Mac, installs Ocho there and adds the Mac to ocho machines. Sessions start there like on any other machine.
ocho rentals # rented Macs, paid-through times and cost
ocho drain MACHINE # move idle sessions to other machines
ocho release MACHINE # give the Mac backocho scale on --cap 100 # spend at most 100 a weekWith scaling on, Ocho rents a Mac when every machine stays busy, and gives it back once it sits idle, after moving its idle sessions to other machines. ocho scale shadow logs what scaling would rent, without renting anything.
Start Claude Code or Codex on a machine with ocho run.
ocho run studio --provider claude --cwd ~/project --attachocho run studio --provider codex --cwd ~/project --attach| Option | Effect |
|---|---|
--attach | Opens the session here after launch. |
--model, --effort | Sets the model and reasoning effort. |
--account | Chooses an account. Auto is the default. |
--permissions | Sets the permission mode, such as auto or manual. |
--worktree NAME | Runs in a new Git worktree of the project. |
auto as the machine | Chooses the machine with the most room. |
ocho run studio --provider codex --cwd ~/app --effort high --save-preset app
ocho run --preset app --attachA preset keeps the machine and the launch settings. A --permissions on the command still applies. ocho profiles lists presets, and ocho profiles remove NAME removes one.
Each session runs under Ocho’s supervisor. Messages between agents, Ocho Attach, Slack, iMessage and ocho resume depend on the supervisor.
Choose a machine, agent, model, account and folder, then start the session.
ocho newThe quick launch starts Claude Code on redwood with the Auto account, in the weather project. The session opens with Ocho Attach, the agent answers, and Control-C twice leaves the agent running.
Choose a machine, then a model, which also chooses Claude Code or Codex. Then choose an account, or Auto for the account with the most usage left, and a folder. Type any path to use a folder that isn’t listed. On another machine, the session opens with Ocho Attach. Machines that don’t answer are marked Offline. Recent choices appear first, so most sessions start with a few presses of Return.
The session opens in place of the quick launch, in the same terminal. A plugin can change where sessions open. In Rex, ⌘N and ⌘⇧N open the quick launch, and the session opens in a new tab.
List, find, read, continue and pause sessions on every machine.
Run ocho sessions to see the sessions on every machine. Select a session to read its latest reply, open it, resume it or archive it.
ocho sessions studio # sessions on one machine
ocho sessions find "road hazards" # matching sessions on every machineocho sessions last studio SESSION # latest reply
ocho transcript studio SESSION --follow # the conversation, as it happensWhen Claude Code or Codex exits, Ocho adds a line below the agent’s own resume message:
Resume this session with:
claude --resume 07ddaa9a-7836-4830-8c93-9a288dea9d19
Continue with Ocho, from any machine:
ocho resume 07ddaa9aocho resume accepts the ID the agent printed, a session ID or part of a title. The conversation continues on the session’s machine, with the session’s account and folder. To continue on another machine, add --on MACHINE.
ocho resume with the ID Claude printed on exit. The conversation continues on the same machine, account and folder.
To start a new conversation from a session’s history instead, add --fork.
ocho sessions send studio SESSION --text "Use the staging database." # after the current turn
ocho sessions send studio SESSION --text "Stop, use staging instead." --now # interrupts the turn
ocho interrupt studio SESSION --yes # stops the turn
ocho sessions show studio SESSION --pane 40 # the terminal’s last 40 linesTo watch a session without typing into it, run ocho attach studio SESSION --read-only.
ocho pause studio SESSION --yes
ocho archive studio SESSION
ocho cleanup --dry-runTo pause idle sessions automatically, run ocho hibernation --enable. A paused session resumes when opened, or with ocho unpause. ocho terminate studio SESSION --yes ends a session, and ocho delete studio SESSION --yes also removes it from Ocho.
The agent runs on another machine. The agent’s interface runs on this computer.
In a remote terminal, each keystroke goes to the other machine, which sends back the updated screen. On a slow connection, such as a phone hotspot, typing lags.
With Ocho Attach, the interface of Claude Code or Codex runs on this computer, so typing and scrolling don’t wait for the network. The agent, with its tools, files and account, stays on the other machine. If the connection drops, the draft stays, and the session reconnects when the network returns.
ocho run studio --provider claude --cwd ~/project --attachClaude Code running on another Mac, typed into from this one. The agent fixes a failing test. Control-C twice leaves the agent running and shows the line for ocho resume.
The first time an agent opens a folder, Claude Code and Codex ask whether to trust it. To answer yes ahead of time, add --trust-folder.
Codex works the same way:
ocho run studio --provider codex --cwd ~/project --attachCodex running on another Mac, typed into from this one. The agent adds a forecast and a test, and the tests pass.
To see the agent’s own terminal on its machine, press Control-]. The view switches in the same tab. Press Control-] again to switch back. The agent keeps running, and the conversation stays the same. In Rex, ⌥⌘A switches between two tabs instead.
ocho attach MACHINE SESSION opens a running session in the agent’s terminal. Press Control-] to switch to Ocho Attach.
Control-] switches between Ocho Attach and the agent’s terminal on its machine.
In Ocho Attach, press Control-C twice to leave and keep the agent running. To end the session, type /exit. Either way, the line to continue appears:
Continue with Ocho, from any machine:
ocho resume 07ddaa9aIn the agent’s terminal, Control-C twice quits the agent and ends the session. To leave and keep the agent running, close the terminal tab, or press Control-] to switch to Ocho Attach first.
Codex: every supported version. Claude Code: releases with a verified patch, listed in Supported agents. On a newer release, the session runs the newest supported release instead.
An agent can start another session, message the other session and wait for a reply, on any machine.
Agents in Ocho sessions get the ocho command and know how to use ocho. Ask an agent to split up a task, and the agent starts helper sessions:
ocho run studio --provider codex --cwd ~/project --prompt "Run the tests and fix failures"
ocho sessions wait studio/SESSION
ocho sessions send studio SESSION --text "Yes, go ahead." --wait 10mClaude asks a Codex agent in the same project which cities it added and whether the tests pass. The answer arrives as a message from the Codex session.
Each message arrives with a header that names the sender and explains how to reply. A message sent while an agent is working waits until the agent is ready.
Ask an agent to keep a dev server or test watcher running, and the agent starts it in a pane beside its session, on its machine:
ocho panes split --name dev -- pnpm dev
ocho panes capture dev --lines 80 # its latest output
ocho panes close devEvery session gets a title, and any session can carry a note.
After the first message, the agent writes a short title for its session, such as “Forecast command cities.” Titles appear in ocho sessions, and in ocho sessions find, and ocho resume accepts a title in place of an ID:
ocho resume "Forecast command cities"To rename a session, run ocho label studio SESSION "Weather API". A name you give replaces the agent’s title.
A note is text you keep with a session on this computer, such as what to check next.
ocho note SESSION "Check the Safari layout before merging."
ocho note SESSION # show the note
pbpaste | ocho note SESSION - # set the note from standard inputTo give a new session a note at launch, add --note TEXT to ocho run.
Give each agent its own Git worktree, so agents in one repository don’t edit the same files.
Start a session in a new worktree:
ocho run studio --provider claude --cwd ~/app --worktree search-fix --attachAdd --ref to start from another commit, --branch to name its branch and --fetch to fetch first. Running the same command again uses the same worktree.
ocho worktree list
ocho worktree remove PATH
ocho worktree restore CHECKPOINTRemoving a worktree first saves its uncommitted work in the repository. ocho worktree remove prints the checkpoint name, and ocho worktree restore brings the work back in a new worktree.
Let Ocho pick the machine for each session, from free memory, load and where you usually work.
ocho run auto --provider codex --cwd ~/app --attachTo see the choice and the reasons, run ocho pick --explain:
> redwood 296.4 12 GB free, 0 working, 8 idle, 96% of recent sessions
laptop 16.3 30 GB free, 1 working, 9 idleOcho never picks a machine where the session can’t start, such as a machine that’s offline or missing the agent.
ocho pick pin ~/app studio # always run ~/app on studio
ocho pick prefer remote # prefer other machines to this one
ocho pick avoid laptop # use laptop only as a last resort
ocho pick never laptopTo draft rules from your past sessions, run ocho pick rules suggest.
Open links that an agent on another machine prints, on this computer.
ocho open http://localhost:3000/settings
ocho open ~/project/out/report.pdfFor a localhost link, the port is forwarded over SSH and the page opens in the browser, with its path and query. For a file on the agent’s machine, the file downloads to ~/Downloads and opens. Agents print the matching ocho open command under each link, so any terminal can open it.
When more than one session is running, add the session, or choose from the list that appears:
ocho open http://localhost:3000 road-hazardsTo keep a port open while you work, forward it directly:
ocho preview studio 3000ocho preview prints the local port, then keeps the forward open until you press Control-D.
Move files between this computer and other machines.
Paste an image or file into an attached session. The file is copied to the agent’s machine, and the file’s path appears in the prompt.
ocho upload studio ./design.png --session SESSIONocho download studio ~/project/out/report.pdf # saves to ~/Downloadsocho run-file studio ~/project/build/App.appA Mac app is copied to this Mac, signed for local use and opened. Anything else runs on the agent’s machine.
ocho files share notes/plan.md # a file on this computer
ocho files share-remote studio ~/app/PLAN.md # a file on another machineOcho publishes the file as a web page and prints its link. Anyone with the link can read it. Sharing the file again updates the page at the same link, and ocho files sync updates every shared file that changed. ocho files unshare takes the page down.
Give an agent an API key without pasting the key into the conversation.
When an agent needs a key, the agent prints a secret link and the matching command:
ocho://secret/STRIPE_KEY
Open this link, or run: ocho secret STRIPE_KEYAn agent asks for an API key.
Run the command in any terminal and type the value. Nothing appears as you type. If more than one session is asking for the same key, choose a session from the list first; only sessions asking for that key appear. The value is written to a file on the agent’s machine over SSH, and never appears in the transcript, the terminal or the command line.
ocho secret saves the key on the agent’s machine without showing it.
A value expires after an hour. To choose, add --ttl 15m, 8h or never.
Move a conversation to another machine, along with its work in progress.
ocho migrate studio SESSION laptop --attachThe session stops on studio and continues on laptop, in the same conversation and with the same account. A session in the middle of a turn, or waiting for a permission answer, doesn’t move unless you add --interrupt. To see what moves first, add --dry-run.
/rewind uses..env files, CLAUDE.md, AGENTS.md, .mcp.json, and Claude and Codex project settings.ocho secret.Other ignored files, such as build output and dependencies, stay on studio, and the move lists them. To move everything, use a volume.
With volumes on, each new session on a Mac works in its own disk image, mounted at /Volumes/ocho-ID. A session started in a repository works in a copy of the repository there. Moving the session copies the whole disk image, with build output and dependencies, and the session continues at the same path on the other Mac.
To turn volumes on, run ocho settings and turn on Session volumes. Volumes are experimental and work only between Macs.
A move copies most of the disk image while the session still runs, so the session stops only for the last changes. Moving back to a Mac copies only what changed since.
ocho volume list studio # volumes, sizes and which are mounted
ocho volume remove studio ID # delete the copy a move left behindocho fork studio SESSION --to laptop --attachOcho keeps a copy of each machine’s recent conversations on this computer, so ocho fork works even while studio is asleep or offline. The fork starts a new conversation from the copy, and the original stays as it was.
ocho drain studioEvery idle session that can move leaves studio for the best other machine. ocho drain lists what stays and why.
Follow the pull requests agents open, and merge them when checks pass.
When an agent opens a GitHub pull request, Ocho links the pull request to the session. Ocho reads pull requests through gh, with the GitHub login on each machine.
ocho pr list # every pull request agents opened
ocho pr status https://github.com/acme/app/pull/42 # state and checks
ocho pr watch # changes as they happen
ocho pr auto-merge https://github.com/acme/app/pull/42ocho pr auto-merge merges the pull request once its checks pass, including a draft. ocho pr cancel turns auto-merge off. ocho pr close and ocho pr reopen close and reopen it.
To send a repository’s ready pull requests to one agent, such as an agent that reviews and merges, run:
ocho pr handoff acme/app SESSIONEach machine where agents open pull requests needs a GitHub login: gh auth login.
Ocho runs in any terminal.
In Ghostty, iTerm, Terminal, Warp, Kitty, a tmux pane, or the terminal in Zed, VS Code or Cursor, run ocho new or ocho run … --attach. The session opens in that tab. Closing the tab doesn’t stop the agent. To reopen the session, run ocho resume or ocho attach.
The session’s terminal keeps running on the agent’s machine, so sessions survive disconnects without tmux.
The Rex integration opens sessions in Rex tabs and adds keyboard shortcuts.
ocho rex installThe Rex integration adds these shortcuts, also listed under Ocho in Rex’s command palette:
localhost link from another machine opens in this browser.The quick launch lists this Mac and each Rex host. For another host, choose where the session opens:
Rex remembers the choice for each host. A Rex host must also be an Ocho machine with the same name.
ocho rex install also teaches agents in Rex to start helpers in new tabs of the same Rex session, on this Mac or another host:
ocho rex start --machine redwood --agent codex "Run the tests and fix failures"
ocho rex wait ID
ocho rex send ID "Yes, go ahead."Each helper works in its own copy of the project, so helpers commit and push their own work.
Rex shows each session’s status on its tab: working, waiting for you or done. Rex carries terminals between machines. Ocho connects machines for everything else, over SSH.
Start sessions and reply to agents from Slack or Messages.
ocho slack connectOpen the link that appears and sign in with Slack. If your workspace doesn’t have Ocho yet, choose Add to Slack. ocho slack status shows the connection.
Send Ocho a direct message, or mention @Ocho in a channel, and a session starts with that message as its task. Replies in the thread go to the same session, and the agent’s answers appear in the thread.
| Message | Effect |
|---|---|
!claude TASK, !codex TASK | Starts a session with that agent. |
!new --machine studio --cwd ~/app TASK | Starts a session with options, like ocho run. |
!machine studio | Sets the machine for new sessions. |
!sessions | Lists sessions. |
!attach SESSION | Links the thread to a running session. |
!status, !detach | Shows the session’s state, or unlinks the thread. |
!model, !plan, !implement | Changes a Codex session’s model or plan mode, or carries out its plan. |
!help | Lists every command. |
Photos sent in a thread go to the agent. When an agent asks for a secret, the thread shows a link to a form, so the value never appears in Slack.
ocho machine pair-imessage studio --phone +14155552671Text the code that appears to the number that appears, from that phone. After the reply “Paired,” text !! to choose a session, or !new and a task to start one. iMessage takes the same commands as Slack.
One Messages conversation follows one session at a time. A message interrupts the agent’s current turn and starts a new turn. Replies arrive as messages, with files the agent links sent as attachments and tables sent as images. Voice memos arrive as text.
Plugins add features and change Ocho’s defaults.
A plugin can add a feature, like session titles or pull request tracking, or replace a default. The Rex integration is a plugin. The Rex integration changes where sessions open and how Ocho Attach switches views.
| Default | A plugin can |
|---|---|
| A new session opens in place of the quick launch. | Open the session in a new tab or window. |
| Ocho Attach switches views in the same tab. | Switch between tabs or windows. |
| Ocho keeps the agent’s terminal running. | Host the terminal in another program. |
| Links open in the browser. | Open links in its own viewer. |
To write a plugin, run ocho docs plugins.
Check Ocho’s setup and find out why something failed.
ocho doctor # this computer’s tools and versions
ocho machine addresses studio --probe # which addresses answer, and how fast
ocho inspect studio # a machine’s hardware, versions and sessions
ocho machine update studio # reinstall Ocho on a machineOcho includes detailed docs for every feature, written for agents and for troubleshooting:
ocho docs
ocho docs search "secret expiry"
ocho docs sessionsTo help diagnose a problem, turn on detailed diagnostics in ocho settings. Ocho then keeps up to 72 hours of timings, error codes and connection states, without prompts, terminal output, paths or credentials. ocho diagnostics show lists what Ocho recorded.
The most common commands. For every command, run ocho --help.
| Command | Effect |
|---|---|
ocho new | Opens the quick launch. |
ocho run MACHINE --provider P --cwd DIR | Starts a session. |
ocho resume ID | Continues a session. |
ocho attach MACHINE SESSION | Opens a running session here. |
ocho sessions | Shows sessions on every machine. |
ocho sessions find QUERY | Finds a session on any machine. |
ocho sessions send MACHINE SESSION --text T | Sends a session a message. |
ocho machines | Shows and manages machines. |
ocho add HOST --install | Adds a machine. |
ocho accounts | Shows and manages accounts. |
ocho open LINK | Opens a link or file from an agent’s machine. |
ocho secret NAME | Gives an agent a secret value. |
ocho preview MACHINE PORT | Opens a remote localhost port. |
ocho upload, ocho download | Moves files. |
ocho migrate MACHINE SESSION TO | Moves a session. |
ocho exec MACHINE -- CMD | Runs a command on a machine. |
ocho docs [TOPIC] | Shows the built-in docs. |
| Feature | Claude Code | Codex |
|---|---|---|
| Sessions on any machine | Yes | Yes |
| Messages between agents | Yes | Yes |
| Ocho Attach | 2.1.301–2.1.303, 2.1.305–2.1.312 and 2.1.314, on Apple silicon Macs | Yes |
| Slack and iMessage | 2.1.289 and later | Yes |
ocho resume | Yes | Yes |
Each Claude Code release needs a verified patch before Ocho Attach supports it. When a machine has a newer release, the session runs the newest supported release instead and says so: “Ocho Attach doesn’t support Claude 2.1.320. Running Claude 2.1.314.” Ocho downloads that release from Anthropic and checks it before use. Your own Claude Code installation stays as it is.