Installation

Ask Mecha's AI Assistant

If you use Claude Code, Codex, or any MCP-compatible AI tool, connect our documentation server for interactive help with installation, configuration, and troubleshooting:

Add to your MCP config (e.g., .mcp.json or settings.json):

{
  "mcpServers": {
    "mecha": {
      "url": "https://mcp.mecha.im/sse"
    }
  }
}

Then ask your AI assistant things like:

• "How do I install mecha?"
• "Set up a Claude worker for PR review"
• "What adapter types does mecha support?"
• "Show me the event rule configuration"

The assistant has access to all mecha documentation and stays current with the latest changes.

What You Need

Mecha is a single binary — no runtime dependencies. What else you need depends on your worker type:

	Docker Workers	Adapter Workers	Unmanaged Workers
What it does	Runs Claude/Codex/Gemini in containers	Translates Ollama/vLLM APIs in-process	Calls your existing HTTP endpoint
Docker 28+	Yes	No	No
LLM running locally	No (bundled in image)	Yes (Ollama, vLLM, etc.)	You manage it

Install Mecha

Option A: Homebrew (Recommended)

The fastest way on macOS or Linux:

brew install xiaolai/tap/mecha

The formula auto-updates with each release.

Option B: Install Script

One command, auto-detects platform:

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/xiaolai/mecha.im/main/scripts/install.sh | sh

Windows (WSL)

irm https://raw.githubusercontent.com/xiaolai/mecha.im/main/scripts/install.ps1 | iex

Pin a specific version with MECHA_VERSION=v0.5.19 or change the install directory with MECHA_INSTALL_DIR=/opt/bin.

Option C: Go Install

Requires Go 1.26+:

go install mecha.im/cmd/mecha@latest

Option D: Download Binary

Download the latest release for your platform from the releases page:

macOS (Apple Silicon)

curl -fsSL https://github.com/xiaolai/mecha.im/releases/latest/download/mecha-darwin-arm64.tar.gz | tar xz
sudo mv mecha /usr/local/bin/

macOS (Intel)

curl -fsSL https://github.com/xiaolai/mecha.im/releases/latest/download/mecha-darwin-amd64.tar.gz | tar xz
sudo mv mecha /usr/local/bin/

Linux (x86_64)

curl -fsSL https://github.com/xiaolai/mecha.im/releases/latest/download/mecha-linux-amd64.tar.gz | tar xz
sudo mv mecha /usr/local/bin/

Linux (ARM64)

curl -fsSL https://github.com/xiaolai/mecha.im/releases/latest/download/mecha-linux-arm64.tar.gz | tar xz
sudo mv mecha /usr/local/bin/

macOS binaries are code-signed and notarized by Apple.

Option E: Build from Source

Requires Go 1.26+:

git clone https://github.com/xiaolai/mecha.im.git
cd mecha.im
make build
sudo cp mecha /usr/local/bin/

Verify

mecha version

Install Claude Code CLI (for Claude Workers)

Claude workers need a setup token generated by the Claude Code CLI. Install it:

npm install -g @anthropic-ai/claude-code
claude login
claude setup-token

This prints a token starting with sk-ant-oat01-. Save it — you'll add it to ~/.mecha/secrets.yml later.

Not using Claude?

Skip this step if you only plan to use Codex, Gemini, or adapter workers (Ollama/vLLM). Each backend has its own auth — see Secrets for details.

Set Up Docker (for Docker Workers Only)

Skip this section if you only plan to use adapter or unmanaged workers.

macOS

Use Colima (lighter than Docker Desktop):

brew install colima docker
colima start --cpu 4 --memory 8

Linux

# Ubuntu/Debian
sudo apt-get install docker.io
sudo systemctl enable --now docker
sudo usermod -aG docker $USER   # log out and back in

Build Worker Images

make image    # builds mecha-worker (unified image)

Or equivalently:

make image

Each image is built on mecha-worker-base (oven/bun:1-slim + git, curl, ripgrep, Caddy). CLIs (Claude Code, Codex) are installed at container start time, not build time — workers always run the latest versions.

Gemini workers

Gemini is not supported as a managed Docker worker — its credential files are encrypted to the host machine and not portable into containers. Use Gemini API endpoints as unmanaged workers instead.

Set Up Secrets

Create ~/.mecha/secrets.yml with tokens for your LLM backends:

mkdir -p ~/.mecha
chmod 700 ~/.mecha

# ~/.mecha/secrets.yml
tokens:
  claude:
    default: sk-ant-oat01-...    # from: claude setup-token
  codex:
    default: sk-...              # from: platform.openai.com
  gemini:
    default: AIza...             # from: aistudio.google.com/apikey

# For GitHub webhooks + write-back (optional)
github:
  token: ghp_...                 # GitHub PAT with repo scope
  webhook_secret: whsec_...      # same secret configured in GitHub webhook settings

# For GitLab webhooks (optional)
gitlab:
  webhook_secret: your_secret    # same token configured in GitLab webhook settings

Lock permissions:

chmod 600 ~/.mecha/secrets.yml

Only include the sections you need. The file is optional — workers can fall through to host CLI defaults (e.g., ~/.claude/.credentials.json).

Where to Get Each Token

Backend	Token	How to get it
Claude (subscription)	sk-ant-oat01-...	claude setup-token (requires Claude Code CLI)
Claude (API)	sk-ant-api03-...	console.anthropic.com — pay-per-token
Codex	sk-...	platform.openai.com
Gemini	AIza...	aistudio.google.com/apikey
GitHub	ghp_...	github.com/settings/tokens — needs repo scope

What's Next

• Quick Start — run your first worker in 5 minutes
• Workers — all worker types and YAML fields
• Secrets — token management in detail