Instalación

Pon el ejecutable orch de Orchemax en el PATH en Windows, macOS o Linux, y confirma la versión y el machine home.

Objetivo#

Un binario en el PATH y un machine home donde Orchemax guarda los archivos que son tuyos y no de un workspace en particular.

Pasos#

0. Consigue el binario#

orch es un ejecutable precompilado que descargas — el usuario no lo compila. En Windows el archivo es orch.exe; en Linux y macOS es orch (sin extensión). Consíguelo con tu cuenta Orchemax / la descarga que el equipo te entrega con el plan, y sigue con el paso 1.

No hagas go build del repo del producto para el uso diario. Compilar desde el código fuente es solo para contribuidores de Orchemax que trabajan en el cliente.

1. Ejecuta orch install#

orch es un único ejecutable. Ejecuta el archivo descargado una vez con install: se copia solo a la carpeta de abajo según tu OS y pone esa carpeta en el PATH de usuario (sin admin). Si lo repites no cambia nada y dice "already installed". El machine-home (%LOCALAPPDATA%\Orchemax / ~/.config/orchemax) es otra carpeta.

./orch install        # macOS / Linux, desde la carpeta donde lo descargaste
.\orch.exe install   # Windows (PowerShell)

Abre una terminal nueva después para que el cambio de PATH se vea. orch uninstall --scope user quita lo que agregó install. Referencia — dónde queda:

Plataforma Binario instalado Agrega esta carpeta al PATH
Windows %LOCALAPPDATA%\Programs\orch\orch.exe %LOCALAPPDATA%\Programs\orch\
macOS ~/.local/bin/orch ~/.local/bin
Linux ~/.local/bin/orch ~/.local/bin

Evita /usr/local/bin salvo que ya administres herramientas ahí con privilegios — las rutas de arriba no requieren instalación elevada.

2. Confirma que el binario responde#

orch version

orch version imprime la cadena de versión y nada más. Si el shell dice que el comando no existe, la carpeta del paso 1 todavía no está en el PATH: abre una terminal nueva o revisa la entrada.

3. Ubica tu machine home#

orch home

orch home imprime dónde viven los archivos de identidad frente a dónde vive el runtime de este workspace:

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)

El machine home se resuelve en este orden:

  1. ORCH_HOME, cuando está definida.
  2. En Windows, %LOCALAPPDATA%\Orchemax.
  3. Si no, $XDG_CONFIG_HOME/orchemax, con ~/.config/orchemax como respaldo.

Las llaves de API de los proveedores también viven ahí, en keys.env: una sola bóveda para todos los workspaces de la máquina. La carpeta .orch/ del workspace guarda solo la base de datos de runtime y los worktrees de ese workspace.

Cómo verificar#

  • orch version imprime una versión.
  • orch home imprime ambos bloques y no da error.
  • orch a secas imprime la ayuda, incluido un pie Detected agents con los CLI de agentes encontrados en tu PATH.

Actualizar#

Reemplaza el binario en esa misma carpeta (%LOCALAPPDATA%\Programs\orch\orch.exe en Windows, ~/.local/bin/orch en el resto) y ejecuta orch doctor --fix en cada workshop (orch workspace list los nombra). El cableado solo nombra esa ruta: nunca el machine home, nunca una compilación desde el código fuente. orch doctor --fix quita los archivos de hooks, MCP y disco que un workshop aún conserva (o, con guard.wire: disk, los reescribe a esa ruta) e imprime cada archivo que cambió; un segundo orch doctor queda en verde para esas comprobaciones.

Relacionado#