Skip to content

Installation

This page walks you through installing and initializing OLAV in 5 minutes.

Feature Claims

ID Claim Status
C-L2-01 olav version reports version correctly ✅ v0.10.0
C-L2-13 olav init creates project directory structure ✅ v0.10.0

Prerequisites

Dependency Description
Python 3.11+ Runtime environment for OLAV
LLM API Key Supports OpenAI, Anthropic, Ollama (local), and more

Step 1: Install

pip install olav

git clone https://github.com/olav-ai/olav.git
cd olav
uv sync

Development mode

When installed from source, prefix all olav commands with uv run, e.g. uv run olav version. All examples below use bare olav commands (as installed via pip).

Verify the installation:

olav version

Expected output: 

Version:   v0.10.0

Step 2: Initialize a Project

Navigate to your working directory and run:

olav init

olav init creates the .olav/ directory with config skeleton, databases, and core Agent.

Step 3: Configure API Key

Edit the .olav/config/api.json generated by olav init and fill in your API key.

api.json uses shared.api_key for unified key management — LLM and Embedding share the same key, no separate configuration needed:

{
  "shared": { "api_key": "sk-..." },
  "llm": { "provider": "openai", "model": "gpt-4o" },
  "embedding": { "mode": "api", "api": { "model": "openai/text-embedding-3-small" } }
}


{
  "shared": { "api_key": "sk-ant-..." },
  "llm": { "provider": "anthropic", "model": "claude-3-5-sonnet-20241022" },
  "embedding": { "mode": "local" }
}
Anthropic doesn't provide an embedding API; use local mode (mode: local, auto-downloads BAAI/bge).

{
  "shared": { "api_key": "sk-or-..." },
  "llm": { "provider": "custom", "model": "openai/gpt-4o", "base_url": "https://openrouter.ai/api/v1" },
  "embedding": { "mode": "api", "api": { "model": "openai/text-embedding-3-small", "base_url": "https://openrouter.ai/api/v1" } }
}


{
  "llm": { "provider": "ollama", "model": "llama3.1", "base_url": "http://localhost:11434" },
  "embedding": { "mode": "local" }
}
Fully offline, no API key needed.

Protect your keys

api.json contains API keys. It is already in .gitignore (created by olav init).

Environment variables

Override api.json values via environment variables (higher priority): 

export OLAV_LLM_API_KEY="sk-..."       # overrides shared.api_key
export OLAV_LLM_MODEL="gpt-4o"         # overrides llm.model
export OPENAI_API_KEY="sk-..."          # OpenAI shorthand
export ANTHROPIC_API_KEY="sk-ant-..."   # Anthropic shorthand

The resulting directory structure:

.olav/
├── config/
│   ├── api.json        ← LLM + auth config (contains keys — do not commit)
│   ├── services.yaml   ← registered external services
│   └── settings.json   ← platform settings (active Agent, etc.)
├── databases/
│   ├── audit.duckdb    ← audit log (auto-records all operations)
│   └── domain.duckdb   ← domain data (Agent execution results, etc.)
└── workspace/
    └── core/           ← pre-deployed core Agent
        ├── AGENT.md    ← Agent capability definition
        └── MANIFEST.yaml ← route keywords and version info

Step 4: Set Up .gitignore

The workspace is safe to commit — share Agent definitions with your team. Config and databases should not be committed:

# .gitignore
.olav/config/      # contains API keys
.olav/databases/   # contains audit logs and domain data
.olav/run/         # runtime PID files

git add .olav/workspace/
git commit -m "feat: init olav workspace"

Next: Your First Query →