Skip to content

Quick Start

Install

Install uv if you don't have it, then install Obra:

curl -LsSf https://astral.sh/uv/install.sh | sh   # Install uv
uv tool install obra                                # Install Obra

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install obra

For voice dictation in Studio, add the voice extra:

uv tool install obra --with 'obra[voice]'

Authenticate

Obra requires authentication and terms acceptance before first use:

obra login          # Accept terms + authenticate via browser

This opens a browser for OAuth. Your code never leaves your machine — only orchestration metadata reaches the Obra service.

Validate Your Environment

obra doctor         # Check provider CLIs, API connectivity, config

Obra needs at least one LLM provider CLI installed:

  • Claude Code: curl -fsSL https://claude.ai/install.sh | bash (or brew install --cask claude-code)
  • OpenAI Codex: npm install -g @openai/codex
  • Gemini CLI: npm install -g @google/gemini-cli
  • Ollama: ollama.com (local, no cloud account needed)

Or run obra setup to pick which of your installed providers Obra uses.

Run Your First Session

obra run "Add a hello world function to greet.py"

Or use the full guided setup for interactive provider selection with recommended settings:

obra setup          # Terms + auth + provider selection + config

Launch Workflow Studio

For visual workflow authoring, run monitoring, and AI-assisted editing:

obra studio         # Check readiness, start gateway, open Studio UI

If Studio is not ready, diagnose with:

obra studio doctor
obra studio doctor --fix

Start the Gateway Directly

Use the gateway directly when integrating against the HTTP or WebSocket API:

obra gateway start

The API surface is documented in Gateway API.

MCP Integration

For OpenClaw, Claude Desktop, Cursor, or any MCP-compatible AI client:

obra mcp serve      # Start MCP server (stdio transport)

See the Gateway API for the full automation contract.

Other Useful Commands

obra doctor         # Environment health check
obra briefing quick # Quick context for AI assistants
obra models         # Available LLM models
obra help domains   # Discover workflow domains
obra config show    # View configuration
obra status         # Check session status

Desktop App (macOS)

A native macOS desktop app is code-complete with guided onboarding, gateway lifecycle management, and a build-verified app bundle. Distribution is pending Apple Developer signing/notarization. See the CLI path above until then.

Upgrade

uv tool upgrade obra

← Back to home