Repository Public License
1<!--2ORIX OS Automation3File: docs/user-guide/guide.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# User guide89## Install and first run10111. Open the disk image and drag **ORIX OS Automation** to Applications. The app is signed with a Developer ID and12 notarized; macOS opens it without a warning.132. The welcome guide offers five short steps, all skippable: how control works, a provider key, a workspace14 folder and default mode, macOS permissions, a first task.153. Nothing is requested from macOS until you press a "Request" button or use a feature that needs it.1617Requirements: macOS 15 or later. Built and tested on macOS 27 (Apple Silicon); the Intel slice is built but has18not been run.1920## Providers and your keys (BYOK)2122ORIX has no account and no server. You bring a key from Anthropic, OpenAI or OpenRouter.2324- **Settings › Providers**: paste a key. It is written to the login Keychain of this Mac (service25 `ai.spboucher.orix.automation`) and never shown in full again; only a masked form such as `sk-…a1b2`.26- **Test connection** sends one minimal request (at most 8 output tokens) and shows the latency or the exact error.27- Choose a **default model**; optionally a planner model (used to draft workflows) and a verifier model (a second28 model that audits a finished run and can only lower its status).29- **Spending**: a daily limit and a per-run budget (turns, time, tokens, cost, tool calls). A run stops with30 `BUDGET_EXCEEDED` when it reaches a limit. When a provider reports no price for a model, the cost is shown as a31 lower bound ("≥") and the receipt says the cost limit could not be fully enforced.32- Requests go directly from this Mac to the provider you chose. Tool output is redacted for credential-shaped33 strings before it is sent back to a model. Screen content is sent only if you turned that on in Settings › Privacy.3435OpenAI is used through the Chat Completions endpoint; models that exist only on the Responses API are not listed.3637## How a task runs3839You state an objective in **Agent**, pick the folder it works in and how much it may do there:4041| Folder access | Effect |42|---|---|43| Ask every time | Every read and write asks |44| May read this folder | Reads inside it do not ask; writes do |45| May read and change this folder | Reads and reversible writes inside it do not ask |4647| Mode | Behaviour |48|---|---|49| Quick | One task; asks for anything not already allowed |50| Guided | The agent must present a plan; nothing is changed until you approve it |51| Autonomous | Acts inside what is already allowed; still asks beyond that |52| Review | Read-only; tools that change things are unavailable or simulated |5354When something needs your decision, an **approval card** shows a sentence written by the tool itself (not by the55model), the capability needed, the tier and the arguments with secrets hidden. You can allow once, for the rest of56the run, or (for low tiers) always. Tier 3 actions are allowed one call at a time and require typing APPROVE.5758At the end, the **receipt** lists the checks the runtime performed itself (files exist, contain what was asked,59checksums), every tool call, approvals, artifacts and cost. The status comes from those checks. The agent's closing60statement is shown separately, labelled as a claim.6162**Emergency stop** (toolbar, menu bar, ⌃⌥⌘.) cancels every run, kills every child process group and refuses every63pending approval.6465## Workflows: three views of one document6667A workflow is one validated document. **Agent** can draft it from a description, **Workflow Studio** edits it as a68graph, **Code Studio** edits its YAML or JSON. All three read and write the same stored source; the language is69described in [`docs/workflows/language-reference.md`](../workflows/language-reference.md), the built-in examples in70[`docs/workflows/examples.md`](../workflows/examples.md).7172- A workflow **declares its permissions**. Before the first run you review them; accepting turns them into grants73 that apply to that workflow only. Changing the declared permissions in a later version withdraws the acceptance.74- **Dry run** executes nothing that changes state and reports what was simulated and what was not executed.75- **Debug** starts paused; you set breakpoints, step, and inspect variables.76- YAML comments are not kept when the canvas rewrites the source; the app tells you before it does.7778## Permissions and privacy7980Two layers decide what happens:81821. **macOS** decides what the app may do at all (Automation of each app, Accessibility, Screen Recording,83 Notifications, protected folders). Only you can grant these, in the system prompt or in System Settings. ORIX84 shows their status in **Permissions** and never tries to grant or bypass them.852. **ORIX grants** decide what an agent or workflow may do: a specific folder, host, app, program or secret, at a86 maximum tier, for one call, one run, one workflow, or until revoked. Everything is denied unless a grant covers87 it. **Permissions** lists every grant; revoke one or all at any time.8889Never available, whatever is granted: Keychains, `~/.ssh`, cloud credential folders, the TCC database, `/System`;90`sudo`; scripting macOS privacy prompts; reading secure text fields.9192Data stays on this Mac in `~/Library/Application Support/ORIX Automation/`: the database, the audit log, run93artifacts, skills. There is no telemetry. The audit log is hash-chained; **Settings › Storage › Verify integrity**94detects an edited or removed entry.9596## Scheduling and background operation9798- Triggers: a cron schedule with a time zone, a one-time date, an interval, a change in a folder, login, an app99 launching, power connected, network available.100- Schedules run while the Mac is on and awake and either the app or the **background agent** is running. The101 background agent is optional (Settings › General); macOS lists it under Login Items and you can turn it off there.102- After sleep or a restart, each schedule's **missed-run policy** decides: skip, run once, or run up to N missed103 occurrences. ORIX never claims a run happened while the Mac was off.104- Daylight saving: a local time skipped in spring fires once at the first valid moment; a local time repeated in105 autumn fires once. Schedules that run every hour or more often keep their elapsed-time rhythm instead.106- A scheduled run has nobody to ask. Anything not covered by accepted permissions stops it as107 `WAITING_APPROVAL`; a notification tells you, and nothing is approved automatically.108- Steps that operate the screen (Accessibility, screen capture, browser windows) need an unlocked session.109 File, script and network steps do not.110111## Automation notes by tool family112113- **AppleScript and JXA** run out of process through `osascript`. A script must list the apps it addresses;114 one that addresses an unlisted app is refused before it runs. The first event to each app triggers the macOS115 Automation prompt. Scripts that shell out need the shell runtime as well and are tier 2.116- **Shell**: `shell.run` takes a program and an argument list — no shell, so nothing is interpolated. Inline117 interpreter forms (`bash -c`, `python -c`, …) are refused; use `shell.script`, which is tier 2 and sandboxed.118- **Python** uses a managed environment under the data folder, never the system installation. Packages are119 installed only as exact pins (`name==1.2.3`), as a separate consequential step.120- **Browser** tools drive ORIX's own WebKit view with a private, non-persistent store: no access to Safari's121 cookies or sessions. Navigation is limited to granted hosts, including redirects. Password fields can only be122 filled from a secret reference and their values are never read back. Subresources of a granted page are not123 host-filtered.124- **Accessibility** tools find elements by role and title, re-check the element and the frontmost app right125 before acting, and refuse secure fields. Apps with poor accessibility support may not be controllable.126- **Git**: status, diff, log, branches, commit, patch, push. Push needs approval; force push is tier 3. There are127 no reset, clean or rebase tools.128129## Troubleshooting macOS permissions130131| Symptom | Cause and fix |132|---|---|133| A step ends `BLOCKED_PERMISSION` naming Automation | You declined or never saw the prompt for that app. System Settings › Privacy & Security › Automation › ORIX OS Automation, enable the app. |134| Accessibility tools report "not trusted" | System Settings › Privacy & Security › Accessibility, enable ORIX OS Automation. If it is already on after an update, turn it off and on again. |135| Screen capture is refused | Privacy & Security › Screen & System Audio Recording. macOS may ask you to quit and reopen the app. Capture is also refused while a password field has secure input. |136| No notifications | System Settings › Notifications › ORIX OS Automation, and Settings › General in the app. |137| A folder cannot be read although a grant exists | macOS protects Desktop, Documents and Downloads separately: answer the system prompt, or enable the folder under Privacy & Security › Files and Folders. |138| The background agent does not start | System Settings › General › Login Items: allow ORIX OS Automation under "Allow in the Background". |139| The prompt never appears again | macOS remembers a refusal. Change it in System Settings; ORIX cannot reset it. |140141## Backup, migration and recovery142143- **Back up database** writes a consistent copy of the SQLite store. **Export workflows and settings** writes one144 JSON file with workflows (all versions) and settings; grants, run history and anything secret are never145 included, and credential-shaped strings are replaced.146- To move to another Mac: export, install the app there, import, then enter your provider keys again and review147 each workflow's permissions (grants do not travel).148- If the database file is damaged, ORIX sets it aside as `orix.sqlite.corrupt-<date>`, starts with an empty one149 and tells you. The damaged file is kept.150- A run interrupted by a crash or a forced quit is marked `RECOVERY_REQUIRED`. Opening it offers to continue151 from its last checkpoint. A step that was changing something when the app stopped is never repeated152 automatically: you choose whether the agent inspects and continues, or the run stays stopped.153- Uninstall: quit the app, turn off the background agent in Settings (or in Login Items), delete the app, and154 delete `~/Library/Application Support/ORIX Automation/` and the Keychain items of the service155 `ai.spboucher.orix.automation` if you want nothing left.156