Reason Worker CLI

Run Reason agents from your terminal, on any computer.

Set up

TUI

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.

Basic

curl -fsSL https://reasonmachines.com/install.sh | bash
reason login
reason "hello world"

reason login opens your browser to approve the Workspace.

API key

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.

One-liner

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. No browser.

Machine token

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

Your computer

Copy the setup command from Settings › Computers 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.

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

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

Desktop

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

macOS permissions

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

How it works

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

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

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.

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.

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.