Orcho Installation Methods

Orcho runs on macOS, Linux, and native Windows (plus WSL2). There are three normal install paths. They run the same command set; the difference is where Orcho, the agent CLIs, credentials, and project tools live.

Path	Best for	First command
Native CLI with `pipx`	Day-to-day use on a machine you trust.	`pipx install orcho`
Docker	Trying Orcho without installing it on the host, or running it in a bounded container.	`docker pull ghcr.io/symphos-ai/orcho`
Project-managed `pip`	Virtualenvs, CI images, devcontainers, or custom images that should own their dependencies.	`python -m pip install orcho`

The orcho distribution includes the core CLI and the MCP server. Use orcho-core directly only when you need the engine package without the full command set.

Native CLI with pipx

Use this on a trusted developer machine when you want orcho and orcho-mcp on your shell PATH, isolated from project virtualenvs. pipx bootstraps differently per OS, so pick your platform:

brew install pipx        # skip if pipx is already installed
pipx ensurepath
# ↻ reopen your terminal so the installed `orcho` is on PATH:
pipx install orcho
orcho --help
orcho-mcp --help

python3 -m pip install --user pipx   # or: sudo apt install pipx / sudo dnf install pipx
python3 -m pipx ensurepath
# ↻ reopen your terminal so `pipx` (and later `orcho`) are on PATH:
pipx install orcho
orcho --help
orcho-mcp --help

Native Windows is supported and exercised in CI. Install Python 3.12+ and Git for Windows first, then, in PowerShell:

py -m pip install --user pipx
py -m pipx ensurepath

Now close this PowerShell window and open a new one. pipx ensurepath updates PATH for new shells only, so pipx (and, after install, orcho) are not on PATH in the current window. py -m pipx is used above precisely because bare pipx is not yet resolvable. In the new window:

pipx install orcho
orcho --help
orcho-mcp --help

Prefer a Unix shell? Install into WSL2 with the Linux tab’s steps. The generated orcho-env.sh is a bash script; in native PowerShell, bind the workspace by setting the variables it would export, or pass --workspace per command:

$env:ORCHO_WORKSPACE = "$HOME\www\my-workspace\workspace-orchestrator"
$env:ORCHO_RUNSPACE  = "$env:ORCHO_WORKSPACE\runspace"

If pipx is still missing after the steps above, see the official pipx guide.

Docker

Use Docker when you want the shortest isolated trial path. Your project is mounted into the container, credentials come from an explicit directory, and only resulting file changes land back in the mounted workspace.

docker pull ghcr.io/symphos-ai/orcho
alias orcho='docker run --rm -it \
  -v "$PWD":/workspace \
  -v ~/.orcho-auth:/agent-auth:ro \
  ghcr.io/symphos-ai/orcho orcho'

orcho run --project /workspace --task "Add input validation to the login endpoint."
orcho status

The image includes Python, Node, Orcho, orcho-mcp, and the bundled agent CLI commands. The agent CLIs start logged out, so do a one-time credential bootstrap:

mkdir -p ~/.orcho-auth && chmod 700 ~/.orcho-auth

# Claude Code subscription credentials on macOS:
security find-generic-password -s "Claude Code-credentials" -w \
  > ~/.orcho-auth/claude-credentials.json

# Codex subscription credentials:
cp ~/.codex/auth.json ~/.orcho-auth/codex-auth.json

# Git identity for delivery commits:
cp ~/.gitconfig ~/.orcho-auth/gitconfig

API keys can be passed as environment variables instead of files:

docker run --rm -it \
  -v "$PWD":/workspace \
  -e ANTHROPIC_API_KEY \
  -e OPENAI_API_KEY \
  -e GEMINI_API_KEY \
  ghcr.io/symphos-ai/orcho \
  orcho run --project /workspace --task "Add input validation to the login endpoint."

Verification phases run your project’s own test commands inside the container. For project toolchains beyond the base Python and Node setup, extend the image:

FROM ghcr.io/symphos-ai/orcho
RUN apt-get update && apt-get install -y --no-install-recommends \
    <your build deps> && rm -rf /var/lib/apt/lists/*

On macOS, bind-mounted file I/O is slower than native disk. For heavy worktree runs, native pipx is faster; Docker trades speed for isolation.

Docker MCP server

An MCP client can also start containerized Orcho over stdio. Mount the workspace parent and bind the server to the workspace path inside the container:

{
  "mcpServers": {
    "orcho": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/Users/me/www/my-workspace:/workspace",
        "-v", "/Users/me/.orcho-auth:/agent-auth:ro",
        "-e", "ORCHO_WORKSPACE=/workspace/workspace-orchestrator",
        "ghcr.io/symphos-ai/orcho",
        "orcho-mcp"
      ]
    }
  }
}

Inside that server, projects live under /workspace/<project-name>.

Project-managed pip

Use pip when the current environment should own Orcho, for example inside a CI image, a devcontainer, or a custom project virtualenv:

python -m pip install orcho

For package-specific dependencies:

python -m pip install orcho-core   # engine and CLI package
python -m pip install orcho-mcp    # MCP server package

Source checkout

Use source checkouts when contributing to Orcho itself or testing unreleased changes:

macOS / Linux
Windows

git clone https://github.com/symphos-ai/orcho-core
cd orcho-core
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

git clone https://github.com/symphos-ai/orcho-core
cd orcho-core
py -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

Contributor setup lives with each repository: