Orcho Quickstart for AI Runs

Quickstart

Get through the first Orcho run without learning every internal concept. The goal is simple: choose the smallest useful profile shape, run one mono task with live output, and know what a successful handoff looks like before you inspect the persisted evidence.

profile firstmono-run firstlive CLI outputpipx or Docker

first useful runmono-run

cd ~/www/my-project
orcho workspace init
orcho run \
--task "Add input validation to the login endpoint." \
--output live

Start small. The first win is watching a profile-shaped lifecycle: plan, implementation, review, repair, and final acceptance.

Preview status

Orcho is in public alpha — released and installable, and pre-1.0 surfaces may still change between releases. Project status covers the stage, license, and what is already treated as a contract.

InputA Git project you can safely edit and the selected worker runtime commands available in the terminal.

RunOne repository, one task, and managed Orcho state outside the project.

Success signalThe live stream shows phase progress and a final decision; status, evidence, and git diff let you inspect it afterwards.

1. Prepare prerequisites

You need:

• Python 3.12 or newer;
• a Git project;
• the worker runtime commands selected by your profile available on PATH.

You do not need a scratch branch or a copy for safety: the run edits a run-owned worktree, and your checkout stays untouched until you make an explicit delivery decision. Read Isolation and delivery boundary for the design behind that guarantee.

2. Check worker runtimes

A worker runtime is the code-agent CLI that Orcho invokes for a phase. Orcho owns the lifecycle, gates, evidence, recovery, and delivery decisions. The runtime does the local agent work.

Built-in runtime ids map to terminal commands:

Runtime id	Check command
claude	claude --version
claude-glm	claude-glm --version
codex	codex --version
gemini	gemini --version

Run the checks for the runtimes your profile or local config uses:

claude --version
codex --version

The default preview configuration can route different phases to different runtimes. If a selected runtime is missing, either install and authenticate its CLI, or override the phase runtimes in local config before running Orcho.

The optional claude-glm wrapper is useful when you want GLM-backed phases to show up as a distinct runtime instead of a hidden claude substitution. See Runtime economics for setup and routing.

One installed runtime is enough to start. To route every phase to claude, put this into the workspace config created in step 4. The init output prints its exact path; after shell activation it is $ORCHO_WORKSPACE/.orcho/config.local.json:

{
  "phases": {
    "plan": { "runtime": "claude" },
    "validate_plan": { "runtime": "claude" },
    "implement": { "runtime": "claude" },
    "review_changes": { "runtime": "claude" },
    "repair_changes": { "runtime": "claude" },
    "final_acceptance": { "runtime": "claude" }
  }
}

A one-provider run keeps every gate, receipt, and delivery decision; what you give up is cross-vendor independence between the writer and the reviewer. Add a second runtime later to restore it.

3. Install Orcho

Choose the path that matches where you want Orcho and the agent CLIs to live:

Path	Use when	Command
pipx	Day-to-day native CLI on a trusted machine.	pipx install orcho
Docker	Isolated trial or containerized run/MCP server.	docker pull ghcr.io/symphos-ai/orcho
pip	Project-managed virtualenv, CI image, devcontainer, or custom image.	python -m pip install orcho

For the native path, pipx keeps the CLI isolated from any project environment. Its bootstrap differs per OS — pick your platform:

macOS

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

Linux

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

Windows

Native Windows is supported and exercised in CI. In PowerShell (with Python 3.12+ and Git for Windows installed):

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 steps.

For Docker (OS-agnostic):

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'

The orcho distribution and Docker image include the MCP server used later on the MCP path. For credential bootstrap, Docker MCP setup, and custom project toolchains, see Installation methods. For a minimal engine-only dependency, use pip install orcho-core instead.

Working on Orcho itself, or want a source checkout? That path lives in CONTRIBUTING.md, not here.

4. Connect the repository where it already lives

Do not move or re-parent a repository to adopt Orcho. Enter the project in its current location and initialize it in place:

macOS / Linux

cd ~/www/my-project
orcho workspace init

Windows

Set-Location $HOME\www\my-project
orcho workspace init

Orcho leaves the repository where it is, registers its canonical path, and stores run state in an external managed workspace. The command prints the workspace path, config paths, MCP setup, a language-neutral plugin scaffold, and matching agent guidance. A shared group workspace also prints its optional shell activation command. Later CLI commands resolve the managed workspace from the current project directory, so the first run needs neither --project nor an environment script.

The scaffold is a starting point, not a finished project contract. Generic mode is enough for this first run. The recommended next step is to teach Orcho the repository’s existing architecture, test, lint, build, and analysis commands. If the project already has CI, reuse those commands instead of inventing a second quality system: CI stays independent, while Orcho gains in-run selection, repair or handoff routing, durable receipts, and readiness evidence before delivery. Follow Project tuning and plugins and Set up scheduled verification for the cost-aware selection and schedule strategy.

Later: one shared workspace for a product family

For a long-lived backend/frontend/mobile family, an intentional shared root is the recommended second-stage topology:

~/work/my-product/
├── backend/
├── frontend/
└── workspace-orchestrator/

Initialize the product root with orcho workspace init ~/work/my-product. Run from that root, or source the printed orcho-env.sh when you want the same workspace from any directory. Registered aliases then make cross-project selection explicit without repeating absolute paths. This layout improves multi-repository operation, but it is not a prerequisite for adopting Orcho. See Workspace model.

5. Run one mono task

This first path uses the smallest useful operating shape: one project, one task, one lifecycle, and evidence you can inspect afterwards. Deeper profiles can add more gates, review depth, participant sets, or control surfaces later.

If you are not sure which profile fits the task, use the manual feature path first. After that, read Profile advisor and try --profile auto-detect as an explicit recommendation step.

orcho run \
  --task "Add input validation to the login endpoint. Return 400 if email is empty." \
  --output live

Start with a small task. The point of the first run is to watch the lifecycle: plan, implementation, review, repair, and final acceptance. --output live is the strongest first perception layer; it shows the run as it happens.

Set expectations before you launch: a feature-shaped run takes tens of minutes, not seconds — it plans, implements, reviews, and re-checks before it calls anything done. Run with ORCHO_ACCOUNTING=1 to record per-phase duration and API-equivalent cost; Cost accounting shows a real per-phase breakdown.

6. The delivery decision, then inspect

At the end of an interactive run, Orcho asks what to do with the retained diff. The interactive default is approve: pressing Enter authorizes a committed delivery according to the configured branch and publication policy. Choose apply explicitly when you want the diff in the project checkout uncommitted for manual review. Delivery control covers the full decision surface, including blocked and override paths.

orcho status
orcho evidence --format md

Then inspect the project checkout and recent commit history:

git status --short
git log --all -5 --oneline

For apply, git diff shows the uncommitted draft. For approve, use the delivery record in orcho status or evidence as the authoritative commit, branch, push, and pull-request result.

7. Where to go next

Next intent	Read
Continue the light path	Watch the run → Read the result
Something failed or looks stuck	Troubleshooting
Configure this repository	Project tuning and plugins → Scheduled verification setup
Understand the operating model	Profile semantics → Profile advisor → Run lifecycle
Go deeper into operation	Correction follow-ups → MCP control surface
Open the expert layer	Runtime adapters → Profile and gate policy
See the full map	Docs map