Installation & Setup

OpenKoi ships as a single static binary with zero runtime dependencies. No Node.js, no Python, no Docker. Install it and start working in under 60 seconds.

Installation Methods

Homebrew (Recommended)

brew tap openkoi-ai/openkoi
brew install openkoi

The fastest path on macOS and Linux. Installs a pre-built binary — no compiler needed. Updates via brew upgrade openkoi.

Cargo (Source Build)

cargo install openkoi

Requires a Rust toolchain (1.75+). Builds from source on crates.io.

Shell Installer

Auto-detects your platform and downloads the correct pre-built binary:

curl -fsSL https://openkoi.ai/install.sh | sh

Supports Linux (x86_64, ARM64) and macOS (Intel, Apple Silicon).

Quick Start (Zero Config)

OpenKoi is designed for zero-config startup. If you have any supported API key in your environment, it just works:

# Run a task immediately
openkoi "Refactor the auth logic to use JWT"

# Start an interactive session
openkoi chat

# Check what OpenKoi detected
openkoi status

No config file needed. No setup wizard. No account creation.

Credential Discovery

On startup, OpenKoi automatically scans for credentials in this priority order:

1. Environment Variables

The fastest path. Set any of these:

# Anthropic (highest default priority)
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI
export OPENAI_API_KEY="sk-..."

# Google
export GOOGLE_API_KEY="AIza..."

# AWS Bedrock
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"              # optional, defaults to us-east-1
export BEDROCK_DEFAULT_MODEL="..."         # optional

# OpenAI-compatible endpoints
export OPENAI_COMPAT_API_KEY="..."
export OPENAI_COMPAT_BASE_URL="https://your-endpoint.com/v1"

2. OAuth Store

If you've previously run openkoi connect, tokens are loaded from ~/.openkoi/auth.json:

• GitHub Copilot — via openkoi connect copilot
• ChatGPT Plus/Pro — via openkoi connect chatgpt

Tokens are refreshed automatically before expiry. No API key needed — uses your existing subscription.

3. External CLI Credentials

OpenKoi auto-imports keys from existing tools you already use:

• Claude CLI — Reads credentials from ~/.claude/ config
• OpenAI Codex — Reads credentials from OpenAI CLI config
• Other tools that store API keys in standard locations

4. Local Probes

OpenKoi probes for locally running model servers:

• Ollama — Checks localhost:11434 for a running instance
• Detected automatically, no configuration needed

5. Interactive Picker

If no credentials are found anywhere, OpenKoi shows an interactive selection menu:

No API keys detected.

? Select a provider to set up:
> GitHub Copilot — login with your existing subscription
  ChatGPT Plus/Pro — login with your existing subscription
  Anthropic — paste an API key
  OpenAI — paste an API key
  Google — paste an API key
  Ollama — local, free (install from ollama.com)
  Other (OpenAI-compatible URL)

Use arrow keys to navigate, type to filter, and press Enter to select. Options 1 and 2 use device-code OAuth — no API key needed. See Providers for details on each provider.

Default Model Selection

When multiple providers are available, OpenKoi selects the default model in this priority order:

1. Claude Sonnet 4.5 (Anthropic) — Best overall quality
2. GPT-5.2 (OpenAI)
3. Gemini 2.5 Pro (Google)
4. Claude Sonnet 4.5 (Bedrock) — Same model via AWS
5. llama3.3 (Ollama) — Free, local

You can override this in config.toml or per-task with --model.

Manual Configuration

While not required, you can customize OpenKoi via ~/.openkoi/config.toml:

[provider]
default_model = "claude-sonnet-4-5-20250514"

[provider.roles]
executor = "claude-sonnet-4-5-20250514"
evaluator = "gpt-5.2"
planner = "claude-sonnet-4-5-20250514"
embedder = "text-embedding-3-small"

[iteration]
max_iterations = 5
confidence_threshold = 0.85

[soul]
enabled = true
formality = 0.7
verbosity = 0.4

See Configuration Reference for the full list of options.

Verifying Installation

After installing, verify everything works:

# Check version
openkoi --version

# Run diagnostics
openkoi doctor

The doctor command checks:

• Binary integrity
• Detected providers and API keys
• SQLite database health
• File permissions on credential stores
• MCP server connectivity
• Plugin system status

Self-Update

OpenKoi can update itself:

# Check for updates
openkoi update --check

# Update to latest version
openkoi update

OpenKoi checks for updates once per day on startup. If a new version is available, it shows a one-line hint — it never auto-updates.

Versioning

OpenKoi uses CalVer format: YYYY.M.D (e.g., 2026.2.18). Pre-releases use YYYY.M.D-beta.N.

Directory Structure

After first run, OpenKoi creates:

~/.openkoi/
├── config.toml          # User configuration
├── auth.json            # OAuth tokens (GitHub Copilot, ChatGPT)
├── openkoi.db           # SQLite database (memory, sessions, learnings)
├── credentials/
│   └── <provider>.key   # Saved API keys (chmod 600)
├── skills/
│   ├── user/            # Your custom skills
│   └── proposed/        # Auto-proposed skills (need approval)
├── evaluators/
│   └── user/            # Your custom evaluators
├── plugins/
│   ├── wasm/            # WASM plugin binaries
│   └── rhai/            # Rhai script plugins
└── soul.toml            # Soul personality state

Next Steps

• CLI Reference — All commands, flags, and REPL commands
• Providers — Configure and assign models per role
• Configuration — Full config.toml reference