Skip to content
cloudroom
Docs/Teleport

Teleport

Move a thread between your Mac and the cloud without losing its conversation, queue, or work.

View as MarkdownAsk ClaudeAsk ChatGPT

Teleport moves a thread between your Mac and the cloud. The thread keeps its conversation, its queued messages, and its work. Start on your Mac, move to the cloud before you close your laptop, and bring the thread back when you want to work locally again.

flowchart LR
  local[Local thread on your Mac] -->|Teleport to Cloud| cloud[Cloud thread in its own sandbox]
  cloud -->|Teleport to Local| local

Start a Teleport

  • Thread menu: pick Teleport to Cloud on a Local thread, or Teleport to Local on a Cloud thread.
  • Message box: send /teleport. It moves the thread to the other side.
  • CLI: run room-cli cloud teleport THREAD_ID. Add --to-local to bring a Cloud thread back.

What can Teleport

  • Harnesses: Claude Code, Codex, and Pi Agent, in both directions. OpenCode and Cursor threads cannot Teleport yet.
  • Threads: parent threads only. A parent's Local child threads move with it.
  • Folders: a Local thread can Teleport from Local or from a Local Worktree.
  • Same settings: the cloud runs the same harness, model, and reasoning level. Cloudroom checks the login and the model before it stops the local agent. If the check fails, the thread stays Local and shows the cause. If the cloud cannot run that model, you pick a cloud model first.

Teleport to Cloud

  1. Cloudroom stops the local agent and its Local child threads.
  2. It sends the conversation, instructions, queued messages, and child thread history to a cloud sandbox.
  3. The cloud agent continues the same conversation right away.
  4. Your branch, uncommitted changes, and attachments upload while the cloud agent works.
sequenceDiagram
  participant Mac as Local thread
  participant Cloud as Cloud sandbox
  Mac->>Mac: Stop the local agent
  Mac->>Cloud: Send history, instructions, and queue
  Cloud->>Cloud: Continue the same conversation
  Mac->>Cloud: Upload changes and attachments
  Cloud-->>Mac: You can close your laptop.

Teleport to Local

  1. Cloudroom stops the cloud agent.
  2. It downloads the agent's session and copies the files that changed in the cloud back to your Mac.
  3. Queued messages move to the local queue.
  4. The same thread continues on your Mac.

If a file changed on both sides, your Mac's version stays. The cloud copy goes to .cloudroom/teleport/. Files deleted in the cloud are not deleted on your Mac. The project folder must already exist on this Mac.

What stays behind

These do not move in either direction:

  • Ignored files, such as .env and build output.
  • Running processes and terminal sessions.
  • Browser sessions.

Cancel or stop

New messages are blocked while a Teleport runs. Click Cancel to stop it before the agent starts on the other side. After that, use Stop.

room-cli cloud teleport THREAD_ID --status
room-cli cloud teleport THREAD_ID --cancel