> ## Documentation Index
> Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Run on computers

> Run a Reason Session on your own computer, on a Reason cloud computer, or on both in one thread, and set what each one may touch.

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

```bash theme={null}
curl -fsSL https://reasonmachines.com/install.sh | bash
reason login
reason connect
reason status
```

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

## Local or cloud

| Where | What runs there | How it is chosen |
| - | - | - |
| Your computer | Commands run in a folder you allowed, with your user permissions | `reason "PROMPT"` (default), `target` `{"kind":"headless","device_id":...}` in the API, `--on NAME` for a shared machine |
| A Reason cloud computer | Commands run in a sandbox | `reason "PROMPT" --cloud`, `target` `{"kind":"cloud"}`, or no target in the API |

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](https://ara-90a60a07.mintlify.site/docs/build/editor-app-acp.md#verify) 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](https://ara-90a60a07.mintlify.site/docs/build/chat-ui-api.md) 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.

> [!NOTE]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.