# Cloud threads

> Run each AI coding agent in its own cloud sandbox that keeps working when your laptop is closed.

Source: https://www.cloudroom.dev/docs/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.

## 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.

```mermaid
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. Subagents share their parent thread's sandbox.
- Each sandbox works on its own Git branch, named after the thread, like `cloudroom/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](/security).
- Tools an agent installs are saved for the project, so later threads already have them.

## Sleep and wake

A sandbox sleeps after 30 idle minutes. 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.

```mermaid
stateDiagram-v2
  [*] --> Starting: New thread
  Starting --> Working: Task sent
  Working --> Idle: Turn finished
  Idle --> Working: New message
  Idle --> Sleeping: 30 idle minutes
  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:

```mermaid
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, 30m
  Sleeping       :done, 11:00, 180m
  Working        :active, 14:00, 60m
  Idle           :15:00, 30m
  Sleeping       :done, 15:30, 150m
```

## 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.

## 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.

## Teleport

Teleport moves a running thread between your Mac and the cloud, keeping the same conversation.

- **Teleport to Cloud:** stops the local agent, then sends history and files to a sandbox.
- **Teleport to Local:** stops the cloud agent and brings its session and changed files back. If a file changed on both sides, your Mac's version wins. The cloud copy is saved in `.cloudroom/teleport/`.

## 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](/docs/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 and its snapshots are removed 7 days later.
- Unmerged branches stay until you delete the thread.

## From the CLI

```sh
room-cli thread spawn --project PROJECT --machine cloud --provider codex \
  --model MODEL --request-id UNIQUE_ID --prompt "Fix the login bug"
room-cli cloud teleport THREAD_ID
room-cli cloud teleport THREAD_ID --to-local
```