Cloud threads

A Cloud thread runs an AI coding agent in its own isolated cloud sandbox. It keeps working when you close your laptop or quit the app. Cloud threads run Claude Code, Codex, Pi Agent, OpenCode, fx, Hermes, and Devin.

Architecture

The desktop app sends your task to Cloudroom. Cloudroom wakes a sandbox for the thread. Inside it, the open-source Core runs your harness and saves every event, so no reply is lost if your laptop goes offline.

flowchart TB
  app[Desktop app or CLI] -->|task| service[Cloudroom service]
  service -->|wake| sandbox
  subgraph sandbox [Thread sandbox]
    core[Cloudroom Core] --> harness[Harness]
    harness --> repo[Your repo on its own branch]
  end
  harness --> model[(Your model provider)]
  core -->|every event| history[(Saved history)]

One sandbox per thread

• Every thread gets its own Linux sandbox. Child threads share their parent thread's sandbox. A Local thread's Cloud child thread gets its own.
• Each sandbox works on its own Git branch, named after the thread, like room/fix-login-bug-tqz7.
• The agent has full admin rights inside its sandbox, but no access to other users or other sandboxes. It can read anything inside its own sandbox, including your logins. See Security.
• Tools an agent installs are saved for the project, so later threads already have them.

Sleep and wake

A sandbox sleeps after 5 idle minutes on Free, 20 on Pro, and 60 on Ultra. It never sleeps while the agent works or has queued messages. Your next message wakes it and resumes the same conversation. Files and history survive sleep.

stateDiagram-v2
  [*] --> Starting: New thread
  Starting --> Working: Task sent
  Working --> Idle: Turn finished
  Idle --> Working: New message
  Idle --> Sleeping: 5, 20, or 60 idle minutes, by plan
  Sleeping --> Working: New message wakes it
  Idle --> Archived: Archive thread
  Sleeping --> Archived: Archive thread
  Archived --> [*]

An example day. The sandbox is awake only while there is work:

gantt
  title Example day for one thread
  dateFormat HH:mm
  axisFormat %H:%M
  todayMarker off
  section Agent
  Working        :active, 09:00, 90m
  Idle           :10:30, 60m
  Sleeping       :done, 11:30, 150m
  Working        :active, 14:00, 60m
  Idle           :15:00, 60m
  Sleeping       :done, 16:00, 120m

Messages, queues, and Stop

• Messages you send while the agent works wait in a queue. They run in order, one turn at a time.
• Send now pushes a queued message into the running turn when the harness supports it.
• Stop interrupts the current turn and pauses the queue. Click Resume queue to continue.
• Closing the app never stops accepted work. Messages sent while offline wait on your Mac until they are delivered.

The side panel

• Terminal, Browser, and side chats work on Cloud threads.
• The Git diff panel, file preview, and worktrees work only on Local threads.

Get your work back

Pick Open pull request in the thread's menu. The agent opens a PR from the thread's branch. To keep working on your Mac, use Teleport to Local.

Logins and skills

• Connect each harness once. Cloudroom keeps your logins encrypted and writes fresh ones into the sandbox each time it wakes. Logins are removed before a sandbox sleeps, so saved snapshots never contain them. See Harnesses.
• Your skills and instructions sync one way, from your Mac to your sandboxes.

Archive and cleanup

Cloudroom cleans up after its agents, so you never hunt for leftovers.

• Archiving a thread deletes its merged branch right away.
• The sandbox is saved and removed 2 hours later. Restoring after that takes a little longer.
• Unmerged branches stay until you delete the thread.
• Cloud threads unused for a year are deleted with their history. Change this in Settings → Auto-delete.

Automations

Cloud automations start Cloud threads on a schedule, even while your Mac is off. With a check script, they run every minute and start an agent only when there is work. See Automations.

From the CLI

room-cli thread spawn --project PROJECT --machine cloud --provider codex \
  --model MODEL --request-id UNIQUE_ID --prompt "Fix the login bug"

To move a thread between your Mac and the cloud, see Teleport.