Skip to main content
A Reason Session thinks in the cloud and runs its commands on a computer. That computer is either yours (connected with reason connect) or a Reason cloud computer. One Session can use both.

​
What you will have

  • A Session that runs a command on your computer and another on a cloud computer.
  • You know which default applies to each entry point, and which folders your computer exposes.

​
Prerequisites

reason status shows this computer’s connection. Running reason connect again changes its settings.

​
Local or cloud

The defaults differ by entry point:
  • reason "PROMPT" in a terminal runs on this computer, in this folder.
  • The HTTP API with no target runs in the cloud.
  • reason acp runs on this computer unless its arguments add --cloud or --on.
Name the target explicitly in code, so the default never surprises you.

​
Which computer the agent picks

When the agent starts work itself (through sessions_create or its tools), it places work by these rules. They are live on the Reason server now; the CLI and API defaults above are unchanged.
  • Your own files, apps or sign-ins run on your connected computer, when it is connected, enabled for that Reason and usable on your turn. The agent does not look for those files in the cloud or ask you to upload them.
  • Heavy, long, parallel or sleep-proof work, work that must continue while your computer is off, and everything when no computer is connected, run in the cloud.
  • Several usable computers and none named: the agent runs a read-only step on each one and reports per computer. It asks before it changes anything.
  • An explicit machine choice wins over these rules.
Each reply says which computer each step ran on.

​
One Session on both

A Session can start work on your computer and move a second task to a cloud computer. The agent has tools to list your computers, start a Session on a chosen computer, and run commands, read files, or write files on another computer it can reach. Check the agent’s reply for which computer ran each command. To check it yourself: run a Session that runs pwd on the computer and on a cloud computer, then read both results in the same reply (the ACP recipe does this from an editor).

​
What your computer exposes

  • Folders. A computer runs Sessions only in folders you grant. Choose the folder with reason connect --folder PATH. The API can add or remove a folder with addDeviceRoot and removeDeviceRoot on a device.
  • Direct access. The computer’s direct-access setting is changed with updateDeviceDirectAccess. Read its reference before you turn it on for a shared computer.
  • Your Chrome. Sessions can use your own Chrome on macOS through the Reason extension. Turn it off with reason connect --user-chrome off.
  • Minimal mode. reason connect --minimal keeps the computer to files, shell and terminal. reason desktop install adds the desktop, computer-use and browser-use components again.

​
Find a computer from code

Read your computers with GET /v3/organizations/{orgId}/devices (scope devices:read). Each entry has id, name, kind (mac or headless), online, and roots (the granted folders). Pass the id as device_id and a folder as cwd. The chat UI sample does this. To list every computer you can use, cloud included, call GET /v3/organizations/{orgId}/computers with the computers:read scope (opt-in; existing keys do not get it). For one Reason, call GET /v3/organizations/{orgId}/reasons/{reasonId}/computers. It returns the computers available to that Reason, not only those whose reason_id equals it: a shared workspace cloud computer keeps its owning reason_id, and a connected computer may have a null reason_id. Each computer has id, kind (cloud, mac, cli or worker), state (ready, starting, busy or offline), live (for a cloud computer: awake rather than parked; for others, connected decides whether it is online), reason_id, size, connected, and whether it is yours. The response also includes cloud_sizes and default_cloud_size. Visibility matches the computers_list tool. Pass a computer’s id as device_id to run work on it.
The route is live on the API. Its OpenAPI reference picks it up on the next docs sync, so check the reference for the exact schema. The authenticated response has not been checked against a live key from this page.

​
Keep a computer awake

A cloud computer parks after about two minutes without activity, and a parked computer stops its processes. A Session keeps running while its turn is active. Start a long-running service with a preview, not as a background command, so it stays up while you work.

​
Check it works

  1. Create one Session that runs pwd on your computer and one that runs pwd on the cloud.
  2. Each reply names a different path (your home folder, then a sandbox path).
  3. reason ls lists both Sessions.