Install

Put the orch executable of Orchemax on your PATH on Windows, macOS or Linux, then confirm the version and the machine home.

Goal#

One binary on your PATH, and a machine home where Orchemax keeps the files that belong to you rather than to any single workspace.

Steps#

0. Get the binary#

orch is a prebuilt executable you download — users never compile it. On Windows the file is orch.exe; on Linux and macOS it is orch (no extension). Get it from your Orchemax account / the download the team gives you with the plan, then continue with step 1.

Do not go build the product repo for day-to-day use. Building from source is only for Orchemax contributors working on the client itself.

1. Run orch install#

orch is a single executable. Run the downloaded file once with install: it copies itself to the folder below for your OS and puts that folder on your user PATH (no admin). Running it again changes nothing and says "already installed". Machine-home (%LOCALAPPDATA%\Orchemax / ~/.config/orchemax) is a different folder.

./orch install        # macOS / Linux, from the folder where you downloaded it
.\orch.exe install   # Windows (PowerShell)

Open a new terminal afterwards so the PATH change is visible. orch uninstall --scope user removes what install added. Reference — where it goes:

Platform Installed binary Add this folder to PATH
Windows %LOCALAPPDATA%\Programs\orch\orch.exe %LOCALAPPDATA%\Programs\orch\
macOS ~/.local/bin/orch ~/.local/bin
Linux ~/.local/bin/orch ~/.local/bin

Avoid /usr/local/bin unless you already manage tools there with admin rights — the paths above need no elevated install.

2. Confirm the binary answers#

orch version

orch version prints the version string and nothing else. If the shell reports that the command was not found, the folder from step 1 is not on PATH yet — open a new terminal, or check the entry.

3. Find your machine home#

orch home

orch home prints where identity files live versus where this workspace's runtime lives:

Machine-home (identity):
  <machine home>
  files: account.json, session.bin, device.token, license.cache.json
Workspace runtime:
  <workspace>/.orch
  files: orch.db, agents/, gateway keys, setup.json, machine.bind.json
Bound: (none yet - login/link writes machine.bind.json)

The machine home is resolved in this order:

  1. ORCH_HOME, when set.
  2. On Windows, %LOCALAPPDATA%\Orchemax.
  3. Otherwise $XDG_CONFIG_HOME/orchemax, falling back to ~/.config/orchemax.

Provider API keys live there too, in keys.env — one vault for every workspace on the machine. The workspace's own .orch/ folder holds only that workspace's runtime database and worktrees.

Verify it worked#

  • orch version prints a version.
  • orch home prints both blocks and does not error.
  • Bare orch prints the help, including a Detected agents footer listing the agent CLIs found on your PATH.

Upgrade#

Replace the binary in that same folder (%LOCALAPPDATA%\Programs\orch\orch.exe on Windows, ~/.local/bin/orch elsewhere), then run orch doctor --fix in each workshop (orch workspace list names them). Wiring only ever names that path: never machine home, never a source build. orch doctor --fix removes the stale hook, MCP and disk files a workshop still carries (or, under guard.wire: disk, rewrites them to that path) and prints each file it changed; a second orch doctor is then green for those checks.