Cloud threads

How cloud threads work

A cloud thread runs its agent in a sandbox of its own, a Linux machine on your own Vercel or Agent37 account. OpenOrc has no cloud of its own. You connect your account, and that service bills you for what its sandboxes use. Cloud threads support Claude Code, Codex, OpenCode, and Oh My Pi. Cursor, Pi, Antigravity, and fx run on the connected computer.

The conversation stays in OpenOrc on your computer, which keeps a worktree for the thread on a branch of its own. The Changes panel, commits, pushes, and pull requests all work from that worktree, as they do for any thread. Code moves between the worktree and the sandbox as Git bundles:

• When a turn starts, OpenOrc sends the sandbox what changed in the worktree since the last turn, such as a commit, an undo, or an edit you made.
• While the agent works, OpenOrc brings its changes to the worktree every 8 seconds, and once more when the turn ends.
• If you edit the worktree while a turn runs, OpenOrc keeps your edits under a Git ref of the thread's own before the sandbox's files replace them. They are never discarded.
• Files that Git ignores, such as dependencies and most .env files, stay where they are on each side. Nothing is pushed anywhere, and the sandbox needs no Git credentials.

Before the first turn, OpenOrc installs the thread's agent in the sandbox, at the version installed on your computer, and runs the project's setup script there instead of on your computer. The script getsOPENORC_CLOUD=1. If the project uses Docker, as a Compose file or a docker compose script shows, OpenOrc installs Docker in the sandbox and starts it. Agents there still have OpenOrc's tools.

Source: packages/cloud/src/sync.ts, packages/core/src/services/cloud-workspaces.ts, packages/protocol/src/owners.ts, uses-docker.ts, packages/cloud/src/agent-install.ts

Connect a cloud service

Open Settings → Cloud. Connect Vercel, Agent37, or both.

Vercel

1. In your Vercel account, create an access token. Under Scope, choose one team, then All Projects. Whoever holds the token can change everything it reaches, so keep it to one team.
2. Under Vercel, paste the token into Access token and click Connect.
3. Choose the Team. Its sandboxes belong to a project named openorc-sandboxes, which OpenOrc creates there.
4. Choose the Sandbox size and the Sandbox region. Both apply to new sandboxes. The size starts at 2 vCPUs and 4 GB. The region starts where your cloud brain runs, or else nearest your time zone.

If the token reaches more than the team you chose, the Account row says so. Disconnect, then connect a token scoped to that team alone.

Agent37

1. Create an API key in your Agent37 workspace.
2. Under Agent37, paste it into API key and click Connect.
3. Choose the Instance size for new cloud threads. It starts at 2 vCPUs and 4 GB.

With both connected, New cloud threads → Run on picks where new cloud threads go. Threads already in the cloud stay where they are.

Check the setup

Under Check, click Run check. OpenOrc makes a throwaway sandbox where new cloud threads run and tries each thing a cloud thread needs: starting the sandbox, finding Node, Git, and Claude Code there, running a process, reaching your computer, keeping sign-ins outside the sandbox, and syncing a change both ways. Then it deletes the sandbox, whatever failed. A failed step shows why.

Source: apps/desktop/src/renderer/src/views/settings-cloud.tsx, settings-cloud-agent37.tsx, settings-cloud-check.tsx, packages/cloud/src/check.ts

How agents sign in there

An agent in a sandbox can't use the sign-in on your computer, so each agent gets one for the cloud. OpenOrc keeps these sign-ins in your system's protected storage, encrypted, and gives a sandbox only the one its turn needs. The first section of Settings → Cloud, Sign-ins for the cloud, lists every sign-in the cloud can use and whether it is ready. Bring them brings the missing ones, one at a time.

If Codex on your computer uses an OpenAI API key, or OpenCode keeps provider keys, Bring them offers to copy them. To find them, OpenOrc reads Codex's auth.json and the credentials OpenCode keeps. It saves a copy only after you approve it with Copy. Your Claude Code login and a ChatGPT sign-in are never copied, because two machines renewing one sign-in sign each other out.

If you send a message to a cloud thread whose agent has no sign-in for the cloud, the message waits. A card in the thread offers that one sign-in, and the message goes once it is ready. Cancel keeps the message in the composer.

Sign-ins kept outside the sandbox

On Vercel, when your plan allows it, the sandbox's firewall adds the real sign-in to the agent's requests on their way out. The sandbox holds only a stand-in that works nowhere, so nothing running there can read the sign-in. This covers Claude Code's requests to api.anthropic.com and mcp-proxy.anthropic.com, Codex's to chatgpt.com or api.openai.com, and OpenCode's and Oh My Pi's to Anthropic, OpenAI, OpenRouter, Google, Groq, Mistral, xAI, and DeepSeek.

Otherwise the sign-in sits in the sandbox, where the agent and the commands it runs can read it. That happens on a Vercel plan that refuses the firewall rule, on Agent37, and for any other OpenCode provider. The check'sKeep sign-ins outside the sandbox step tells you whether the firewall does this for you.

Source: packages/core/src/services/cloud-sign-ins.ts, cloud-agent-env.ts, cloud-codex.ts, cloud-opencode.ts, mac-agent-keys.ts, codex-cloud-login.ts

Start a thread in the cloud

1. On the New thread page, pick a project. Cloud threads need a Git project, so the Workspace has no cloud.
2. Click the line under the composer that says where the thread works, and choose Cloud. The line then reads Runs in the cloud on a new branch.
3. Choose the agent and model, type your request, and press Enter.

The thread opens at once. While the sandbox gets ready, a card shows its steps, such as Starting a Vercel sandbox, Sending your code, Running the setup script, andStarting Claude, with your message below. When it is ready, the message goes to the agent. If a step fails, the card says The cloud workspace did not start, with the reason andTry again.

The thread's header names where it runs: Vercel or Agent37. In the sidebar its row says cloud.

When a sandbox runs

• A sandbox stays awake while it is set up and while its agent runs. About a minute after both end, OpenOrc puts it to sleep. Its files stay, and the next message wakes it.
• An agent with nothing to do closes after 10 minutes, so an idle sandbox sleeps about 11 minutes after the last turn.
• If your computer sleeps or goes offline during a turn, the sandbox keeps going for up to 30 minutes, so the turn can finish. OpenOrc shows what the agent did when it connects again.

Source: apps/desktop/src/renderer/src/components/NewThreadOptions.tsx, CloudStart.tsx, CloudSignInOffer.tsx, packages/core/src/services/cloud-awake.ts

Move a thread to the cloud and back

Between turns, open a project thread's menu, point at This Mac, and choose Move to cloud. The dialog says what will move. A thread in the local checkout first takes every uncommitted change in the checkout, including other threads', into a new worktree on its own branch, and the dialog lists those files.

Where the thread goes depends on whether you set up a cloud brain:

• Without a cloud brain, the worktree, its uncommitted changes, and the agent's session go to a sandbox of its own, where the next message runs. The worktree stays on your computer and follows the sandbox. The thread then stays in the cloud, and can't move back to your computer or into the checkout.
• With a cloud brain, the brain takes the thread, with its history, the agent's session, its branch, and its uncommitted changes. The worktree leaves your computer, and the brain runs the thread in a sandbox of its own. The card on the thread shows Packing the conversation, Waking the cloud brain, and Sending it to the cloud.

A thread on the cloud brain shows Cloud near the top of its menu. Point at it for these choices:

If the brain refuses a move, the thread shows Didn't move with the reason and a way to try again. A conversation outside a project, an Orcling's conversation, a pull request's review copy, and a subagent's thread stay where they are. To move a subagent, move the thread that started it.

Source: apps/desktop/src/renderer/src/components/ThreadActions.tsx, CloudMoveDialog.tsx, packages/core/src/services/cloud-handoff.ts, relocations.ts, relocation-rules.ts, thread-moves.ts

When your computer sleeps

Settings → Cloud → When this Mac sleeps → Carry working threads on in the cloud lets a turn continue in the cloud when your computer goes to sleep in the middle of it. It is off by default. Connect a service and bring the agents' sign-ins before you turn it on.

• While it is on, each turn of a worktree thread on your computer gets a sandbox of its own beside it. During the turn, OpenOrc keeps that sandbox up to date with the worktree's files and the agent's session.
• When your computer goes to sleep, the turn here stops, and the sandbox carries it on for up to two hours. If your computer drops off during a turn without going to sleep, the sandbox takes over after two minutes.
• While your computer sleeps, the agent can't reach OpenOrc's tools or ask you for an approval. When the computer wakes, the thread becomes a cloud thread, says This Mac went to sleep, so the turn carried on in the cloud., and shows the sandbox's work as a turn.

Threads in the local checkout stay on your computer. Quitting OpenOrc ends its turns, and no sandbox takes them over.

Source: packages/core/src/services/cloud-standby.ts

The cloud brain

The cloud brain is a copy of OpenOrc that runs without a window on your Vercel team or Agent37 account. It holds threads of its own and runs each in a sandbox of its own, so they keep going while your computer sleeps, and your phone can follow and start them. Each thread has one owner, your computer or the brain. Your computer's sidebar lists both, and what you do in a brain thread goes to the brain. The brain sleeps when it has been idle for five minutes, and wakes when you open one of its threads or a phone reaches for it.

Set it up

1. Connect Vercel or Agent37. The Cloud brain section appears in Settings → Cloud.
2. If sign-ins are missing, bring them first with Sign-ins for the cloud → Bring them, so the brain starts with them.
3. With both services connected, choose where it Runs on. On Vercel, choose the Region, which is fixed once it is set up.
4. Click Set up. OpenOrc makes the brain's machine and installs the brain that comes with the app, starts it, and sends it the sign-ins.

Choose its projects

Under Projects, switch on each project the brain should work in. OpenOrc sends the brain a copy of the project's default branch as Git bundles, and again when the branch changes while both are awake. If the brain's copy has commits your computer doesn't, it isn't updated, and the row says so. New cloud threads start on the brain only in a project that is switched on. While both are awake, the brain and your computer merge those projects' memory both ways, and the brain keeps a read-only copy of your open tasks for your phone.

What it signs in with

• Claude accounts lists the accounts whose cloud tokens the brain holds. Send appears when it is behind.
• Codex is the brain's own login, separate from the one your computer's sandboxes use. Sign in makes a ChatGPT sign-in for it, or Use an API key.
• GitHub is off by default. Switched on, the brain gets your computer's GitHub sign-in for its own git and gh, to commit, push, and open pull requests. No agent and no sandbox gets it.
• Notifications and Anthropic API key appear once the brain holds a copy of your Apple push key or of memory's Anthropic API key.

Phones and the brain

Click Pair phone and scan the code with OpenOrc on your iPhone. Phones paired with the brain are listed under it, each with Remove. The phone then reaches the brain over the internet, while your computer sleeps or is off. On Vercel, a small function in your team, the Door, wakes a sleeping brain for a paired phone. On Agent37, a request to the brain's address wakes it. See Phone app.

The brain's row shows whether it is awake, with Wake while it sleeps. Move to Agent37 or Move to Vercel appears once the other service is connected. A move brings the brain's threads to your computer, sets up a new brain on the other service, and sends them there. Phones need pairing again, and the brain's Codex sign-in stays behind.

Source: apps/desktop/src/renderer/src/views/settings-cloud-brain.tsx, settings-cloud-brain-projects.tsx, settings-cloud-brain-signins.tsx, packages/core/src/services/cloud-brain.ts, brain-sync.ts, apps/brain/src/awake.ts

Costs and limits

Vercel and Agent37 bill your account for the sandboxes and the brain, under their own prices and plans. OpenOrc charges nothing.

• Sandboxes in Settings → Cloud lists each sandbox, whether it is awake, how long it ran, its size, and on Vercel what it has cost so far at Vercel's list prices.
• The cloud brain's This month counts the brain and the sandboxes it made. On Vercel it uses list prices and includes their snapshots, before your plan's credit. On Agent37 it shows what Agent37 counts.
• With Carry working threads on in the cloud on, every turn of a worktree thread keeps a sandbox awake beside it.
• Each agent's use goes to its own account, such as the Claude account's subscription, your ChatGPT plan or OpenAI API key, and each OpenCode provider's key.

Your Vercel plan sets the largest sandbox, how long one session can last, and whether the firewall can keep sign-ins outside the sandbox. A turn that outlasts the session ends when Vercel stops the sandbox. On Agent37, a project that uses Docker gets a VM instance, which Agent37 bills at a higher rate.

Source: apps/desktop/src/renderer/src/views/settings-cloud-sandboxes.tsx, packages/cloud/src/vercel-sandbox.ts, agent37-sandbox.ts

Remove cloud resources

• Remove beside a sandbox under Sandboxes deletes it, except while its agent works. The thread stays, and its next message makes a new sandbox from the worktree.
• Deleting a cloud thread deletes its sandbox.
• Remove on the cloud brain deletes it from your account, with its disk, the sandboxes it made, and the conversations on it. Bring to Mac any conversation you want to keep first. Paired phones can no longer reach it.
• Disconnect forgets the Vercel token or Agent37 key on your computer. It doesn't delete sandboxes or the brain, so remove them first. On Vercel, OpenOrc first closes the brain's door, which deletes the door's copy of your token.

Source: packages/core/src/handlers/cloud.ts, packages/core/src/services/cloud-brain.ts, apps/desktop/src/renderer/src/views/settings-secret-field.tsx

Next steps