Getting Started

This guide walks you through installing o4, setting up your first provider, and running your first session. It takes about 2 minutes.

1. Install o4

One-line install (recommended)

curl -fsSL https://install.open4rena.ai/o4 | bash

This downloads the latest binary for your platform (macOS or Linux) and installs it to ~/.local/bin.

If ~/.local/bin is not in your PATH, the installer will tell you how to add it.

Manual download

Download the archive for your platform from GitHub Releases, then:

tar -xzf o4-<platform>.tar.gz
chmod +x o4-<platform>
mv o4-<platform> ~/.local/bin/o4

Verify installation

o4 --version

2. Set up your first provider

o4 supports multiple LLM providers. You need at least one API key.

Option A: First-run wizard (easiest)

Just run o4 — if no API key is detected, a setup wizard will walk you through picking a provider and entering your key. It validates the key and saves it automatically.

o4

  Welcome to o4
  ─────────────────────────────────────

  No API key detected. Let's set one up.

  Select a provider:

     1) Anthropic
     2) OpenAI
     ...

  Enter number [1-10]: _

Option B: Set a key manually

# Pick ONE provider and set its key:

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GOOGLE_API_KEY=AIza...
export DEEPSEEK_API_KEY=sk-...
export KIMI_API_KEY=sk-...
export GROQ_API_KEY=gsk_...

To make it permanent, add the export line to your shell profile (~/.zshrc, ~/.bashrc, etc).

Supported providers

Provider	Env var	Default model
Anthropic	`ANTHROPIC_API_KEY`	`claude-sonnet-4-6`
OpenAI	`OPENAI_API_KEY`	`gpt-5.5`
OpenAI Codex	`OPENAI_CODEX_ACCESS_TOKEN` or Codex OAuth	`gpt-5.6-sol`
Claude Code OAuth	`CLAUDE_CODE_OAUTH_TOKEN` or `/auth import claude`	`claude-code:claude-sonnet-4-6`
Google Gemini	`GOOGLE_API_KEY`	Gemini models
DeepSeek	`DEEPSEEK_API_KEY`	DeepSeek models
Kimi Code	`KIMI_API_KEY`	Kimi K3 and K2.7 Code models
xAI (Grok)	`XAI_API_KEY`	Grok models
Mistral	`MISTRAL_API_KEY`	Mistral models
Groq	`GROQ_API_KEY`	Groq models
Ollama (local)	`OLLAMA_API_KEY` (optional)	Local models
OpenRouter	`OPENROUTER_API_KEY`	Various models
Bedrock	AWS credentials	Claude models
Vertex	`GOOGLE_APPLICATION_CREDENTIALS`	Claude/Gemini

3. Start your first session

o4

You’ll see the o4 terminal UI. Type your first prompt:

> What's in this directory?

o4 will use tools to explore your project, read files, and give you an answer.

4. Common first commands

Once you’re in a session, try these:

/help                 Show all commands and keybindings
/config               Change model, providers/keys, reasoning, permissions, themes, keybindings, MCP, plugins, agents, skills, tools, LSP, and formatters
/mcp                  Open MCP browser: configured servers and registry search
/plugins              Discover and install plugins from marketplaces, Git, or local paths
/agents               Open agent browser: browse, create, edit, delete, and select agents
/skills               Browse and create skills; install skill packs through Plugins
/todo                 Open the editable session todo list; Alt+L is the shortcut
/todo add <text>      Add a todo that the active model sees on its next turn
/goal <objective>     Start persistent goal mode for a task; /goal pause, resume, complete, clear
/loop <schedule>      Schedule repeated prompts
/context              See how much context window you've used
/cost                 See token and cost totals
/resume               Browse or resume saved sessions

5. Your first real task

Try asking o4 to do something concrete:

> Find all TODO comments in this project and summarize them

> Run the tests and fix any failures

> Explain how the auth system works in this codebase

o4 will use its tools (bash, read, grep, glob, etc.) to explore your code and complete the task. It will ask for your permission before running commands that modify files.

6. Choosing a model

Pick a model with the -m flag:

# Use a specific model
o4 -m anthropic:claude-sonnet-4-6

# Use a model from a specific provider
o4 -m openai:gpt-5.5

# See all available models
o4 --list-models

Or set a default in ~/.o4/settings.json:

{
  "model": "claude-sonnet-4-6",
  "default_provider": "anthropic"
}

7. One-shot mode (scripts and pipelines)

Use --print for non-interactive mode:

# Get a one-shot answer
o4 --print -p "explain this codebase"

# Pipe content into o4
cat error.log | o4 --print -p "what went wrong?"

# Use in a script
o4 --print -p "write a README for this project" > README.md

8. Resuming sessions

Your conversations are saved. List and resume them:

# List recent sessions
o4 sessions list

# Resume a specific session
o4 --session <session-id>

Inside the TUI, use /resume to browse saved sessions or /resume <id> to resume a specific session.

9. Permissions and safety

o4 asks before running commands that modify your system. You can pre-allow common patterns:

Create .o4/config.toml in your project:

[[permissions.rules]]
pattern = "Bash(cargo test*)"
action = "allow"

[[permissions.rules]]
pattern = "Bash(cargo build*)"
action = "allow"

10. Getting help

In o4: type /help
Docs: see docs/usage.md for the full usage reference
Issues: https://github.com/Open4rena/o4-releases/issues

What’s next?

Plugins: extend o4 with custom commands, agents, skills, workflow metadata, and skill hooks — see docs/o4-plugins.md
MCP servers: connect external tools — open /mcp to browse configured servers and search the registry
Harness controls: set up automated checks and workflows — see docs/harness-controls.md
Multiple providers: you can set keys for as many providers as you want and switch between them per-session from /config