Install

Put the orch binary 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 orch keeps the files that belong to you rather than to any single workspace.

Steps#

0. Get the binary#

orch ships as one prebuilt executable. Public tagged releases and a download page are not published yet: until they are, the binary comes from the Orchemax team together with your account. On Windows the file is orch.exe; on Linux and macOS it is orch with no extension.

If you were handed a source checkout instead of a binary, build it yourself (the module pins go 1.26.3 — install that version or newer):

# Windows (PowerShell), from the checkout root
cd client
go build -o orch.exe ./cmd/orch

# Linux / macOS, from the checkout root
cd client
go build -o orch ./cmd/orch

Move that file into the folder from step 1 below and add that folder to PATH — the rest of this page is the same either way.

1. Put the binary in its own folder#

orch is a single executable. Drop it anywhere you like and add that folder to your user PATH. Nothing else is ever written there — the folder stays empty of orch's own files, as orch --help says: "that folder stays empty of Orche files — PATH only".

Platform Suggested folder How to add it to PATH
Windows %LOCALAPPDATA%\Programs\orch\ User environment variables → Path → new entry. orch setup offers to do this for you.
macOS ~/bin or /usr/local/bin Add export PATH="$HOME/bin:$PATH" to your shell profile.
Linux ~/.local/bin or /usr/local/bin Same; ~/.local/bin is already on PATH in most distributions.

On macOS and Linux the file needs the execute bit: chmod +x orch.

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.