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

# Reason Worker CLI

> Run Reason agents from your terminal, on any computer.

## Set up

<Tabs>
  <Tab title="TUI">
    ```bash wrap theme={null}
    curl -fsSL https://reasonmachines.com/install.sh | bash
    reason
    ```

    Run `reason help all` for every command and option; `reason --help` shows the three you use every day. Each command also accepts `--help`.

    In the TUI, press **Ctrl+V** to attach a clipboard image to your next message, whether the Session runs on this computer, another computer or in the cloud. Delete its image marker to leave it out. If sending fails, the image stays in the draft so you can retry. Clipboard access must be available to the terminal running the CLI.
  </Tab>

  <Tab title="Basic">
    ```bash wrap theme={null}
    curl -fsSL https://reasonmachines.com/install.sh | bash
    reason login
    reason "hello world"
    ```

    `reason login` opens your browser to approve the Workspace.
  </Tab>

  <Tab title="API key">
    ```bash wrap theme={null}
    curl -fsSL https://reasonmachines.com/install.sh | bash
    export REASON_API_KEY=reason_…
    reason "hello world"
    ```

    Sign in without a browser, for CI and scripts. [Create an API key](https://reasonmachines.com/customize?tab=api).
  </Tab>

  <Tab title="One-liner">
    ```bash theme={null}
    curl -fsSL https://reasonmachines.com/install.sh | bash && REASON_API_KEY=reason_… ~/.local/bin/reason "hello world"
    ```

    Installs, then starts a session with your [API key](https://reasonmachines.com/customize?tab=api). No browser.
  </Tab>

  <Tab title="Machine token">
    ```bash wrap theme={null}
    # On your laptop: create a token for the machine "build"
    reason machines token build

    # On the server: install Reason, no login
    curl -fsSL https://reasonmachines.com/install.sh | bash

    # On the server: join "build" and keep it running as a service
    reason serve --token rmt_… --service

    # From anywhere: send work to it
    reason "hello world" --on build

    # Or over the HTTP API, with an API key
    ORG_ID=$(curl -s https://api.reasonmachines.com/v3/self \
      -H "Authorization: Bearer $REASON_API_KEY" | jq -r .org_id)
    curl https://api.reasonmachines.com/v3/organizations/$ORG_ID/sessions \
      -H "Authorization: Bearer $REASON_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"prompt": "hello world",
           "target": {"kind": "machine", "name": "build"}}'
    ```

    The server connects out to Reason, so it needs no open ports. `--service` keeps it running after reboots (`reason connect --token rmt_…` does the same). `reason machines token` also prints a one-liner that installs and joins in one step. Run it on more servers to add workers to the same machine; every member can send work to a machine.
  </Tab>

  <Tab title="Your computer">
    Copy the setup command from [Settings › Computers](https://reasonmachines.com/customize?settings=1\&tab=computer) and run it on the computer. One command installs Reason, signs in with your browser's approval and connects the computer, asking nothing, then opens Reason in that terminal. A computer set up this way runs Sessions for every Workspace you belong to.

    ```bash wrap theme={null}
    # From Settings › Computers; the code is yours and expires
    curl -fsSL https://reasonmachines.com/install | sh -s -- --pair CODE --open
    ```

    By hand, the same steps are `reason login` and `reason connect`. A computer signed in with a plain `reason login` runs Sessions for one Workspace only, the one that login approved.

    ```bash wrap theme={null}
    reason login
    # Connect this computer once; it stays connected in the background
    reason connect
    reason status
    # Let Sessions run in another folder too (outside your home folder)
    reason connect --add-folder ~/work/app
    reason disconnect
    ```

    Connects this computer as **one** computer in your Workspace, rooted at your home folder and running commands with your user permissions; it has no sandbox mode, and a connection or Device an earlier CLI ran sandboxed runs with your user permissions from its next start. It starts again at login and `reason update` restarts it on the new version. Folders are not separate computers: `reason "PROMPT"` in any folder runs on this connection, and a folder outside your home folder is added to it first. `--remove-folder PATH` takes one away. `reason device` is the earlier name of `reason connect` and runs the same command.

    New computers are **Personal**: only you start Sessions on them. Switch one to **Team** in [Settings › Computers](https://reasonmachines.com/customize?settings=1\&tab=computer) to let every member start Sessions there. Sessions are shared either way, so teammates can follow and continue a Session that already runs on your computer.

    Your computer is connected in the workspace you signed in to. It is also connected, by itself, in up to 8 other workspaces you belong to, each as that workspace's own computer, when it was signed in with the setup command Reason shows you (it carries `--pair CODE`) or by the Reason app, and was connected after that. A computer signed in with `reason login` alone, or connected with an API key, stays in its one workspace: run the setup command from Reason on it, then `reason disconnect` and `reason connect` if it was connected before. One sign-in covers one computer. `reason status` says when this applies.

    On a headless box with no `reason login`, connect with an API key that has the `devices:write` scope: `REASON_API_KEY=reason_… reason connect --name build-box --yes` (or `--api-key KEY`; `--api-url URL` targets another Reason API). The connection keeps the key, in the Keychain on macOS, to renew itself. `reason disconnect` removes the computer from Reason and forgets the key (it never asks, and accepts `--yes` for scripts). `reason logout` also disconnects it. A computer you disconnect, here or in Settings › Computers, stays disconnected: `reason "…"` refuses to connect it (`computer_disconnected`) until you run `reason connect`. For a box that only lives for one run, `reason connect --once` connects while the command runs and removes itself when it exits.
  </Tab>

  <Tab title="Desktop">
    ```bash wrap theme={null}
    # Every install sets up desktop, computer use and browser use; check or repair them
    reason desktop status
    reason desktop install
    # Files, shell and terminal only: install with --minimal, or have installs and updates skip the desktop
    curl -fsSL https://reasonmachines.com/install | sh -s -- --minimal
    reason desktop minimal
    ```

    Installs Open Computer Use, Open Browser Use and Chrome for Testing on macOS and Linux; updates keep them current and skip them on a minimal computer. Safe to run again. On macOS, add `--permissions standard` to grant Accessibility and Screen Recording now instead of at first use.
  </Tab>

  <Tab title="macOS permissions">
    ```bash wrap theme={null}
    # List Screen Recording, Accessibility and Full Disk Access, and who holds each
    reason permissions
    # Ask for every missing one, or one: screen, accessibility or disk
    reason permissions allow
    ```

    Screen Recording and Accessibility belong to Reason (desktop video and computer use). Full Disk Access, recommended for Sessions in Desktop, Documents, Downloads, iCloud Drive and Mail, belongs to the worker: macOS cannot ask for it, so `allow disk` opens its pane, shows the file to add in Finder and waits for it.
  </Tab>
</Tabs>

## How it works

```text theme={null}
        Reason cloud                                Machine
 ┌────────────────────────┐                ┌────────────────────────┐
 │ Brain                  │                │ reason CLI             │
 │ plans, calls the model │◀── connects ───│ runs the shell,        │
 │                        │─── commands ──▶│ edits files            │
 │                        │◀── results ────│                        │
 └────────────────────────┘                └────────────────────────┘
```

Every session has a **Brain** and **Hands**. The Brain is the agent loop: model calls, planning, memory and tool selection, hosted by Reason. The Hands are the execution environment that carries out each tool call: a shell, a filesystem and a working tree.

The CLI is a Hands runtime: it attaches your machine to a session over an outbound WebSocket.

## Choose where it runs

| Command | Commands run |
| - | - |
| `reason "PROMPT"` | This computer, in this folder |
| `reason "PROMPT" --cloud` | Reason's cloud, on this checkout's repo |
| `reason "PROMPT" --on NAME` | Machine NAME, on whichever of its workers is free |

On this computer the agent works with your user permissions, uncommitted changes included. The Session runs on this computer's connection (`reason connect`), so it keeps going after you close the terminal; the first run connects the computer. A Session runs on one computer at a time; a machine queues Sessions across its workers.

## Computers and machines

* **Computer:** one per computer, Workspace and person, made by `reason connect`. Its folders and running Sessions belong to it. Personal by default; Team lets every member start Sessions on it.
* **Machine:** a named, shared pool of workers for the team, made with `reason machines token NAME` and `reason serve` or `reason connect --to NAME`. Work sent with `--on NAME` waits for a free worker.
* **One-shot workers** (`--once`) are not listed and remove themselves when they stop.

[Settings › Computers](https://reasonmachines.com/customize?settings=1\&tab=computer) lists the computers you can start Sessions on. Disconnect one there, or with `reason disconnect`; work running on it stops. Workspace owners and admins see every member's computers and can disconnect any of them. Deleting a Session removes its worktree from `~/.reason/workspace/sessions` on the computer it ran on; its `reason/<id>` branch stays.

## Follow and steer

```bash theme={null}
reason ls                          # recent sessions
reason watch ID                    # follow until done
reason send ID "also add a test"   # steer mid-run
reason cancel ID                   # ends suspended; send resumes it
```

Add `-d` to `--cloud` or `--on` to print the session ID and return.

## Scripts and CI

Use `reason run --task "PROMPT"` in scripts; it runs in the cloud by default. It prints the result as text; `--output-format json` returns it unchanged.

`reason run` and `reason "PROMPT"` exit with `0` success, `1` task failed, `2` Reason or usage error, `3` action required, `130` interrupted.

## FAQ

<AccordionGroup>
  <Accordion title="What can I use it for?">
    Anything that can run a command can start a session. One line brings a full agent into any script, trigger or workflow:

    * A step in your CI/CD pipeline, such as fixing a failing test or reviewing a change.
    * A cron job, git hook or webhook handler.
    * Your own scripts and internal tools, on your laptop or a server.
  </Accordion>

  <Accordion title="Why not just use the regular API?">
    The API starts and steers sessions. The CLI does that too, and it is the Hands: the agent works in your real checkout with your toolchain and credentials. Nothing to push, no image to build, no inbound ports.
  </Accordion>

  <Accordion title="Why not run Claude Code or Codex headless?">
    Those run the whole agent in one process on one machine. Here the Brain runs in the cloud:

    * Sessions live in Reason, not a process. Follow and steer them from the CLI or the dashboard.
    * Your team sees and continues the same sessions.
    * `--on NAME` queues work across a machine's pool of workers.
    * Workspace memory, skills and integrations come with every session.
    * No model API keys on the machine.
  </Accordion>
</AccordionGroup>


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