Installation Guide
The easiest way to get Orcha running is the Mac app. Download it, open it, and it walks you through setup in a single window — checking what you need, installing the Orcha helper for you, and creating your first project. No Terminal required.
Prefer the command line, or not on a Mac? There’s a Terminal setup further down.
Get the Mac app Easiest
Universal build for both Apple Silicon and Intel Macs. Download it, open the .dmg, and drag Orcha into your Applications folder.
Signed & notarized by Apple. It opens straight away — no security warnings to click through.
Before you open it — three free tools you’ll need first
The Mac app is the easiest way in, but it isn’t fully self-installing yet. It needs three free tools to be present: it checks for them and won’t continue until they’re in place — but you install them yourself. Get these first (or let the app prompt you for any you’re missing):
1. Homebrew — the Mac package manager. Get it at brew.sh, or run:
# installs Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" 2. Docker — Orcha runs each project in its own isolated container. Install Docker Desktop (or OrbStack) and leave it running.
3. An AI coding agent — Claude Code or Codex. Install one directly with a single command, or download it from claude.ai / chatgpt.com/codex:
# Claude Code
curl -fsSL https://claude.ai/install.sh | bash
# …or Codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh After installing one, sign in once when prompted — Orcha uses whichever you have.
What happens when you open it
The app guides you through a short, four-step setup. You don’t type any commands — you just click along.
Setup check
Orcha checks for three free tools and shows you how to get any you’re missing, then a Re-check button confirms once they’re in place.
Pick a folder
Choose an existing project folder, or create a new one — right from the app.
Name your project
Give the project a name and an objective for your agents to work toward.
Create
Orcha installs its own helper and sets the project up end-to-end — database, portal and all. When it finishes, you’re ready to bring in agents.
The three tools the app checks for
These are free and you install them yourself (each has its own installer or sign-in). The app tells you which, if any, you still need and won’t let you continue until all three are ready — so you can do this now or just let the app prompt you.
1. Homebrew — the Mac package manager. Get it at brew.sh.
2. Docker — Orcha runs each project in its own isolated container. Install Docker Desktop (or OrbStack) and leave it running.
3. An AI coding agent — Claude Code or Codex. Install one with a single command:
# Claude Code
npm install -g @anthropic-ai/claude-code
# …or Codex
npm install -g @openai/codex After installing one, sign in once when prompted — Orcha uses whichever you have.
Advanced — set up from the Terminal
Prefer the command line, automating a setup, or not on a Mac? Everything the app does can be done by hand. The Mac app and the CLI are the same engine underneath — the app just runs these steps for you.
Show the Terminal setup
1. Install the AI coding agent
Orcha plugs its slash-commands into Claude Code (or Codex), so you need one installed and working from any folder. Open the Terminal app (⌘ Space, type “Terminal”) and run one:
# Claude Code
npm install -g @anthropic-ai/claude-code
# …or Codex
npm install -g @openai/codex
Confirm it works from any folder — open a fresh Terminal window and run
claude --version (or codex --version).
2. Install Homebrew
Homebrew is the Mac package manager Orcha installs through:
# installs Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
When it finishes it may print a couple of “Next steps” lines so your Mac can find
brew — copy-paste those too.
3. Install Docker Desktop
# installs Docker Desktop
brew install --cask docker Open Docker Desktop once and leave it running — Orcha needs Docker on while you work. You can also get it from docker.com.
4. Install the Orcha CLI
The orcha command-line tool spins up each project’s private
Postgres + portal and brings the slash commands into your AI coding agent. You’ll also
need Python 3.10+.
# install the CLI with Homebrew brew install open-orcha/orcha/orcha # initialise orchestration inside any project
orcha init --objective "Ship the thing" --as YourName Updating: already have Orcha? Run
brew upgrade orcha to get the latest CLI.
Resetting a project to a clean slate
If a project’s Orcha workspace gets into a bad state and you want to start completely fresh — without uninstalling anything — run this from the Terminal, inside the project folder:
# wipes this project’s Orcha workspace and re-initializes it from scratch
orcha init --force --reset-data This is a destructive command. It permanently erases the Orcha workspace inside this project — every task, agent and bit of history Orcha was tracking — and rebuilds it empty. Your own project code and files are not touched; only Orcha’s own data for this project is wiped. There’s no undo, so only run it when you genuinely want to throw away this project’s Orcha history and begin again.
Stopping or removing Orcha
Want to pause a project, free up your machine, or remove Orcha entirely? Run these from the Terminal, in this order — each line undoes a bit more.
1. Stop a running project
Run this inside the project folder to shut Orcha down and clear that project’s local database and portal:
# stops the project and removes its local data
orcha down -v This erases that project’s Orcha data (its tasks, agents and history live in
the local database the -v flag wipes). Your own code and files are
untouched — but if you just want to pause and come back later, stop here and run
orcha up again when you return, rather than wiping the data.
2. Uninstall the Orcha CLI
Once nothing is running, remove the command-line tool itself:
# removes the orcha command
brew uninstall orcha 3. Remove the Orcha tap
Finally, drop the Homebrew “tap” that Orcha installs from, so Homebrew stops tracking it:
# removes the Orcha source from Homebrew
brew untap open-orcha/orcha
Changed your mind? You can reinstall any time — the Mac app, or
brew install open-orcha/orcha/orcha from the Terminal.