Docs / Getting started

Getting started with RavenClaws

This guide walks you through your first RavenClaws agent — from installation to running a multi-step task with tools.

Prerequisites

  • Rust 1.86+ (for building from source)
  • Docker (optional, for containerized deployment)
  • An LLM provider — one of:

Installation

Option 1 — Install via Cargo (recommended)

shell
cargo install ravenclaws

Option 2 — Build from source

shell
git clone https://github.com/egkristi/RavenClaws.git
cd RavenClaws
cargo build --release
# Binary is at target/release/ravenclaws

Option 3 — Docker

shell
docker pull ghcr.io/egkristi/ravenclaws:latest

Quick start — your first agent

1. Set up your LLM provider

Set the required environment variables:

environment
# For LiteLLM (default):
export LITELLM_API_KEY="your-key"
export LITELLM_ENDPOINT="http://localhost:4000"

# Or for OpenAI:
export OPENAI_API_KEY="sk-..."
export RAVENCLAWS__LLM__PROVIDER="openai"

# Or for Ollama (fully local):
export RAVENCLAWS__LLM__PROVIDER="ollama"
export RAVENCLAWS__LLM__ENDPOINT="http://localhost:11434"
export RAVENCLAWS__LLM__MODEL="llama3.1"

2. Run a one-shot task

shell
ravenclaws --exec "What is the capital of France?"

You should see a response like: The capital of France is Paris.

3. Start an interactive REPL

shell
ravenclaws --repl

This starts an interactive session where you can have a back-and-forth conversation:

repl
╭─ RavenClaws REPL ─────────────────────────────╮
│ Type /exit to quit, /reset to clear history    │
╰────────────────────────────────────────────────╯
You: Summarize the key features of Rust
RavenClaws: Rust is a systems programming language...
You: /exit
Goodbye!

4. Run a multi-step task with tools

shell
ravenclaws --exec "Create a file called hello.txt with the text 'Hello, RavenClaws!' and then read it back"

This uses the built-in write_file and read_file tools to complete the task.

Configuration

RavenClaws can be configured via three layers (each overrides the previous):

  1. Config file (ravenclaws.toml)
  2. Environment variables (prefixed with RAVENCLAWS__)
  3. CLI flags

Minimal config file

ravenclaws.toml
[llm]
provider = "litellm"
endpoint = "http://localhost:4000"
api_key = "your-key"
model = "gpt-4o-mini"

See the Configuration Reference for all available options.

Next steps