Installation methods

Orcho has 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 install orcho
orcho --help
orcho-mcp --help

If pipx is missing, install it first. On macOS:

brew install pipx
pipx ensurepath
exec zsh -l

On Linux or Windows, use 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:

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

Contributor setup lives with each repository: